Import, export, and debug Typesense from the CLI

Inspect the operation before sending data

TypesenseKit validates structured input before making a network request. Inspect the generated schema and examples for the current CLI version before building an import or export job.

tsk documents.import --schema
tsk documents.import --examples
tsk documents.export --schema

All operation input is one JSON object supplied inline or through a JSON file. Operation names and schemas come from the same 95-operation registry used by the MCP server.

Import or upsert documents

Create an input file containing the collection, optional import action, and either an array of documents or a JSONL string.

{
  "collection": "products",
  "action": "upsert",
  "documents": [
    { "id": "sku-1", "title": "Oak chair", "price": 289 },
    { "id": "sku-2", "title": "Walnut chair", "price": 349 }
  ]
}

Run the import. Because imports can replace existing data depending on the action, the CLI asks for confirmation.

tsk documents.import --input import-input.json --json

Use --yes only in controlled automation after checking the collection and action.

tsk documents.import --input import-input.json --yes --json

To wrap an existing JSON array in the required operation object:

jq '{collection:"products", action:"upsert", documents:.}' products.json > import-input.json

Export all or filtered documents

Typesense returns exports as JSONL. TypesenseKit represents that response as a JSON string in structured output, so use jq -r to write the original lines to disk.

tsk documents.export \
  --input '{"collection":"products"}' \
  --json | jq -r . > products.jsonl

Pass supported Typesense export parameters through params to filter records or limit fields.

tsk documents.export \
  --input '{"collection":"products","params":{"filter_by":"in_stock:=true","include_fields":"id,title,price"}}' \
  --json | jq -r . > in-stock-products.jsonl

Check the file before using it as a backup or migration input.

wc -l products.jsonl
head -n 3 products.jsonl | jq .

Debug import failures

Typesense import responses contain one JSON result per submitted document. Preserve the raw output, then filter unsuccessful rows.

tsk documents.import --input import-input.json --yes --json \
  | jq -r . > import-results.jsonl

jq -c 'select(.success == false)' import-results.jsonl

Common causes include missing required fields, incompatible field types, invalid nested data, and using create when a document ID already exists.

Retrieve the live collection schema and compare it with a failing document:

tsk collections.retrieve \
  --input '{"collection":"products"}' --json > products-schema.json

jq . products-schema.json
jq . products.json

Separate data problems from cluster problems

Check connectivity and cluster health before debugging an import payload. Then run a small search to verify the target collection is queryable.

tsk profile test production
tsk health --input '{}' --json
tsk collections.retrieve --input '{"collection":"products"}' --json
tsk documents.search --input '{"collection":"products","params":{"q":"*","query_by":"title","per_page":1}}' --json

Automate without leaking credentials

Use environment variables or pipe a key over stdin. Keep keys out of command arguments and shell history, request stable JSON, and fail the job when unsuccessful import rows are present.

TYPESENSE_URL=https://your-cluster.typesense.net \
TYPESENSE_API_KEY="$TYPESENSE_API_KEY" \
tsk documents.import --input import-input.json --yes --json \
  | jq -r . > import-results.jsonl

test "$(jq -c 'select(.success == false)' import-results.jsonl | wc -l | tr -d ' ')" = "0"

Use a key restricted to the target collection and required document actions. Review the complete CLI guide for profiles, Keychain storage, environment-only use, and shell completion.