Skip to main content
Command-line interface for TopK — upload documents, ask questions and search relevant passages grounded in your data.

​
Installation

brew tap topk-io/topk
brew install topk

​
Authentication

To authenticate, run: 
topk login
Alternatively, you can set TOPK_API_KEY environment variable and skip the topk login command. 
export TOPK_API_KEY=<your-api-key>

​
Commands

​
ask

Get a grounded answer with citations 
topk ask "my question" --dataset my-dataset
FlagRequiredDescription
--datasetYesDataset to search (repeatable, e.g. -d ds1 -d ds2)
--modeNoResponse mode: auto (default), summarize, research
--fieldNoMetadata field to include in results (repeatable, e.g. -f title -f author)
--show-refsNoShow citations inline in the answer
--output-dirNoSave result content (images, text chunks) to a directory
The query can also be piped via stdin: 
echo "my question" | topk ask --dataset my-dataset
Find relevant passages in documents 
topk search "my query" --dataset my-dataset
FlagRequiredDescription
--datasetYesDataset to search (repeatable, e.g. -d ds1 -d ds2)
--top-kNoNumber of results to return (default: 10)
--fieldNoMetadata field to include in results (repeatable, e.g. -f title -f author)
--output-dirNoSave result content (images, text chunks) to a directory
The query can also be piped via stdin: 
echo "my query" | topk search --dataset my-dataset

​
upload

Upload files to a dataset 
topk upload '*.pdf' --dataset my-dataset
topk upload 'docs/**/*.md' --dataset my-dataset
topk upload docs --dataset my-dataset -r
topk upload report.pdf notes.md images/ --dataset my-dataset
ArgumentRequiredDescription
PATTERNYesOne or more file paths, directories, or glob patterns
--datasetYesDataset to upload into
-rNoRecurse into subdirectories when PATTERN is a directory
-yNoSkip the upload confirmation prompt
-cNoNumber of concurrent uploads, 1–64 (default: 32)
--waitNoWait for processing; optionally up to a duration (e.g. --wait 5m)
--dry-runNoPreview which files would be uploaded without uploading

​
list

List documents in a dataset: 
topk list --dataset my-dataset
Streams results as they arrive. In agent mode (-o json) outputs one JSON object per line (NDJSON).
FlagRequiredDescription
--datasetYesDataset to list documents from
--fieldNoMetadata field to include (repeatable, e.g. -f title)

​
delete

Delete a document from a dataset: 
topk delete --dataset my-dataset --id my-doc-id
FlagRequiredDescription
--datasetYesDataset containing the document
--idYesDocument ID to delete
-yNoSkip confirmation prompt

​
dataset

Manage datasets

​
list

List all datasets: 
topk dataset list
This command has no subcommand-specific flags.

​
get

Get a dataset: 
topk dataset get my-dataset
ArgumentRequiredDescription
DATASETYesDataset name

​
create

Create a dataset: 
topk dataset create --region aws-us-east-1-elastica my-dataset
topk dataset create --region aws-us-east-1-elastica --description "My dataset" my-dataset
ArgumentRequiredDescription
DATASETYesDataset name
--regionYesRegion to create the dataset in. List available regions at https://docs.topk.io/regions
--descriptionNoDataset description

​
update

Update a dataset: 
topk dataset update my-dataset --description "My dataset description"
FlagRequiredDescription
DATASETYesDataset name
--descriptionNoDataset description

​
delete

Delete a dataset: 
topk dataset delete my-dataset
ArgumentRequiredDescription
DATASETYesDataset name
-yNoSkip confirmation prompt

​
login

To authenticate, run: 
topk login
Alternatively, you can set TOPK_API_KEY environment variable and skip the topk login command. 
export TOPK_API_KEY=<your-api-key>

​
logout

Log out and clear cache: 
topk logout

​
Global flags

These flags are accepted by every command:

​
--output

Options:
  • text (default)
  • json
Output results as NDJSON — one JSON object per line, compatible with jq: 
topk -o json dataset list | jq '.name'

​
--api-key

API key to use for this invocation. Overrides the TOPK_API_KEY environment variable and the key saved via topk login.

​
Updating the CLI

To update CLI to the latest version, run: 
brew update
brew upgrade topk