Skip to main content
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

talkvalue path import analyze --file <path>

​
Options

FlagTypeDescription
--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

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

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

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

{
  "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