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

# CLI

> Upload documents, ask questions and search relevant passages with TopK CLI.

Command-line interface for [TopK](https://topk.io) — upload documents, ask questions and search relevant passages grounded in your data.

## Installation

```bash theme={null}
brew tap topk-io/topk
brew install topk
```

## Authentication

To authenticate, run:

```bash theme={null}
topk login
```

Alternatively, you can set `TOPK_API_KEY` environment variable and skip the `topk login` command.

```bash theme={null}
export TOPK_API_KEY=<your-api-key>
```

## Commands

### ask

Get a grounded answer with citations

```bash theme={null}
topk ask "my question" --dataset my-dataset
```

| Flag           | Required | Description                                                                  |
| -------------- | -------- | ---------------------------------------------------------------------------- |
| `--dataset`    | **Yes**  | Dataset to search (repeatable, e.g. `-d ds1 -d ds2`)                         |
| `--mode`       | No       | Response mode: `auto` (default), `summarize`, `research`                     |
| `--field`      | No       | Metadata field to include in results (repeatable, e.g. `-f title -f author`) |
| `--show-refs`  | No       | Show citations inline in the answer                                          |
| `--output-dir` | No       | Save result content (images, text chunks) to a directory                     |

The query can also be piped via stdin:

```bash theme={null}
echo "my question" | topk ask --dataset my-dataset
```

***

### search

Find relevant passages in documents

```bash theme={null}
topk search "my query" --dataset my-dataset
```

| Flag           | Required | Description                                                                  |
| -------------- | -------- | ---------------------------------------------------------------------------- |
| `--dataset`    | **Yes**  | Dataset to search (repeatable, e.g. `-d ds1 -d ds2`)                         |
| `--top-k`      | No       | Number of results to return (default: 10)                                    |
| `--field`      | No       | Metadata field to include in results (repeatable, e.g. `-f title -f author`) |
| `--output-dir` | No       | Save result content (images, text chunks) to a directory                     |

The query can also be piped via stdin:

```bash theme={null}
echo "my query" | topk search --dataset my-dataset
```

### upload

Upload files to a dataset

```bash theme={null}
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
```

| Argument    | Required | Description                                                         |
| ----------- | -------- | ------------------------------------------------------------------- |
| `PATTERN`   | **Yes**  | One or more file paths, directories, or glob patterns               |
| `--dataset` | **Yes**  | Dataset to upload into                                              |
| `-r`        | No       | Recurse into subdirectories when `PATTERN` is a directory           |
| `-y`        | No       | Skip the upload confirmation prompt                                 |
| `-c`        | No       | Number of concurrent uploads, 1–64 (default: 32)                    |
| `--wait`    | No       | Wait for processing; optionally up to a duration (e.g. `--wait 5m`) |
| `--dry-run` | No       | Preview which files would be uploaded without uploading             |

### list

List documents in a dataset:

```bash theme={null}
topk list --dataset my-dataset
```

Streams results as they arrive. In agent mode (`-o json`) outputs one JSON object per line (NDJSON).

| Flag        | Required | Description                                             |
| ----------- | -------- | ------------------------------------------------------- |
| `--dataset` | **Yes**  | Dataset to list documents from                          |
| `--field`   | No       | Metadata field to include (repeatable, e.g. `-f title`) |

### delete

Delete a document from a dataset:

```bash theme={null}
topk delete --dataset my-dataset --id my-doc-id
```

| Flag        | Required | Description                     |
| ----------- | -------- | ------------------------------- |
| `--dataset` | **Yes**  | Dataset containing the document |
| `--id`      | **Yes**  | Document ID to delete           |
| `-y`        | No       | Skip confirmation prompt        |

### dataset

Manage datasets

#### list

List all datasets:

```bash theme={null}
topk dataset list
```

This command has no subcommand-specific flags.

#### get

Get a dataset:

```bash theme={null}
topk dataset get my-dataset
```

| Argument  | Required | Description  |
| --------- | -------- | ------------ |
| `DATASET` | **Yes**  | Dataset name |

#### create

Create a dataset:

```bash theme={null}
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
```

| Argument        | Required | Description                                                                                                             |
| --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `DATASET`       | **Yes**  | Dataset name                                                                                                            |
| `--region`      | **Yes**  | Region to create the dataset in. List available regions at [https://docs.topk.io/regions](https://docs.topk.io/regions) |
| `--description` | No       | Dataset description                                                                                                     |

#### update

Update a dataset:

```bash theme={null}
topk dataset update my-dataset --description "My dataset description"
```

| Flag            | Required | Description         |
| --------------- | -------- | ------------------- |
| `DATASET`       | **Yes**  | Dataset name        |
| `--description` | No       | Dataset description |

#### delete

Delete a dataset:

```bash theme={null}
topk dataset delete my-dataset
```

| Argument  | Required | Description              |
| --------- | -------- | ------------------------ |
| `DATASET` | **Yes**  | Dataset name             |
| `-y`      | No       | Skip confirmation prompt |

### login

To authenticate, run:

```bash theme={null}
topk login
```

Alternatively, you can set `TOPK_API_KEY` environment variable and skip the `topk login` command.

```bash theme={null}
export TOPK_API_KEY=<your-api-key>
```

### logout

Log out and clear cache:

```bash theme={null}
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`:

```bash theme={null}
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:

```bash theme={null}
brew update
brew upgrade topk
```