> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trytalkvalue.com/llms.txt
> Use this file to discover all available pages before exploring further.

# talkvalue path import analyze

> Upload a CSV file, get a fileKey, and preview the server's column mapping before creating an import job.

Pre-check a CSV without committing to an import. The command uploads the file to TalkValue's import staging area, returns a `fileKey` you pass to `import create`, and prints the headers, a sample preview, and TalkValue's suggested column mapping. Required target fields the file cannot satisfy come back under `missingRequired` so you can fix the file before running the full import.

## Synopsis

```bash theme={null}
talkvalue path import analyze --file <path>
```

## Options

| Flag            | Type              | Description                                                                                                                                                           |
| --------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--file <path>` | string (required) | Path to the CSV file on disk. Read locally, uploaded as `multipart/form-data`. Permission and "file not found" errors surface as usage errors with no upload attempt. |

## Examples

### 1. Inspect a file before importing

```bash theme={null}
talkvalue path import analyze --file ./registrants.csv
```

Prints a single record with the `fileKey`, the row count, headers, the first few rows as preview, and the suggested column mappings.

### 2. Pipe the mapping into a script

```bash theme={null}
talkvalue path import analyze --file ./registrants.csv --json \
  | jq -r '.data.columnMappings[] | "\(.csvIndex):\(.suggestedField)"'
```

Prints one `csvIndex:targetField` pair per line, ready to feed into `import create --mapping`. Capture `.data.fileKey` from the same response and you have both pieces the create step needs.

### 3. Halt the pipeline when required fields are missing

```bash theme={null}
talkvalue path import analyze --file ./bad.csv --json \
  | jq -e '.data.missingRequired | length == 0' \
  || { echo "Fix required columns and try again"; exit 1; }
```

`jq -e` exits non-zero if `missingRequired` has entries, so the surrounding shell can fail loudly instead of forwarding a broken file to `import create`.

## Response

```jsonc theme={null}
{
  "data": {
    "fileKey": "u/2026/05/9f1a-registrants.csv",
    "totalRows": 1247,
    "headers": ["email", "first_name", "last_name", "company"],
    "preview": [
      ["alice@acme.com", "Alice", "Kim", "Acme"]
    ],
    "columnMappings": [
      { "csvIndex": 0, "csvHeader": "email", "suggestedField": "EMAIL", "confidence": 0.98, "suggestions": [] },
      { "csvIndex": 1, "csvHeader": "first_name", "suggestedField": "FIRST_NAME", "confidence": 0.92, "suggestions": [] }
    ],
    "missingRequired": []
  }
}
```

`fileKey` is the only field you must keep. It is the handle `import create` requires. Each entry in `columnMappings` carries the CSV column's index and header alongside the server's `suggestedField` guess plus a confidence score. Pass `csvIndex:suggestedField` to `import create --mapping`, overriding any guess you disagree with.

## See also

* [`import create`](/cli/commands/path/import/create). The next step that consumes the `fileKey` and mapping.
* [Column mapping](/path/import/column-mapping). The full list of valid target fields.
* [Recipe: CSV import](/cli/recipes/csv-import). Analyze, create, status in one script.