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

# bt topics

> Inspect and manage Topics automations from the CLI

`bt topics` manages [Topics automations](/docs/observe/topics) for the active project.

Running `bt topics` with no subcommand is equivalent to `bt topics status`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt topics
bt topics status
bt topics status --full
bt topics status --watch
bt topics config
bt topics config <automation-or-topic-map-id>
bt topics config enable
bt topics config delete
bt topics config set --topic-window 1h --generation-cadence 1d
bt topics config topic-map <topic-map-id>
bt topics config topic-map set Task --embedding-model brain-embedding-1
bt topics report fn_123
bt topics report fn_123 --version 0000000000000001
bt topics btmap fn_123
bt topics btmap fn_123 --output topic-map.btmap
bt topics poke
bt topics rewind 7d
bt topics open
```

## bt topics status

Show the Topics automation status for the active project.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt topics status
bt topics status --full
bt topics status --progress-window 7d
bt topics status --watch
```

**Flags**

| Flag                         | Description                                                 |
| ---------------------------- | ----------------------------------------------------------- |
| `--full`                     | Show expanded diagnostics and progress counts               |
| `--progress-window <WINDOW>` | Window for status progress counts, for example `1h` or `7d` |
| `--watch`                    | Refresh every 2 seconds until interrupted                   |
| `--json`                     | Output as JSON (incompatible with `--watch`)                |

## bt topics poke

Queue Topics to run on the next executor pass. Use this to queue a readiness check without waiting for the next scheduled run.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt topics poke
```

Output lists all topic automations queued for processing, showing each automation's name, ID, and scheduled timing.

## bt topics rewind

Rewind recent Topics history and queue it to reprocess. Traces in the specified window will have their facets and topic labels recomputed on the next executor pass.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt topics rewind 7d                       # Rewind the last 7 days
bt topics rewind 1h                       # Rewind the last hour
bt topics rewind 30m --automation-id <ID> # Rewind a specific automation
```

### Arguments

| Argument     | Description                                                                                                                                                     |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<DURATION>` | Time window to rewind. Format: `<NUMBER><UNIT>` where unit is `s` (seconds), `m` (minutes), `h` (hours), `d` (days), or `w` (weeks). Example: `7d`, `1h`, `30m` |

**Flags**

| Flag                   | Description                        |
| ---------------------- | ---------------------------------- |
| `--automation-id <ID>` | Rewind a specific automation by ID |

## bt topics open

Open the Topics page for the active project in the browser.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt topics open
```

## bt topics config

View or edit Topics automation configuration.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt topics config                          # View all automations
bt topics config --automation-id <ID>     # View a specific automation
bt topics config <automation-or-topic-map-id>
bt topics config delete                   # Delete the Topics automation for this project
```

**Flags**

| Flag                   | Description                        |
| ---------------------- | ---------------------------------- |
| `--automation-id <ID>` | Target a specific automation by ID |
| `--json`               | Output as JSON                     |

### bt topics config enable

Enable Topics for the active project with the provided configuration.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt topics config enable
bt topics config enable --name "My automation" --topic-window 1d --generation-cadence 1h
bt topics config enable --filter "span_type = 'llm'" --sampling-rate 25
```

| Flag                              | Description                                                            |
| --------------------------------- | ---------------------------------------------------------------------- |
| `--name <NAME>`                   | Human-friendly automation name                                         |
| `--description <DESC>`            | Human-friendly automation description                                  |
| `--topic-window <DURATION>`       | Topic window duration (e.g., `1h`, `1d`)                               |
| `--generation-cadence <DURATION>` | How often to generate fresh topic maps (e.g., `1h`, `1d`)              |
| `--relabel-overlap <DURATION>`    | Relabel overlap duration (e.g., `1h`)                                  |
| `--idle-time <DURATION>`          | Trace idle wait duration before processing (e.g., `30s`)               |
| `--sampling-rate <PERCENT>`       | Percent of matching traces to sample (e.g., `25` or `25%`)             |
| `--filter <EXPR>`                 | BTQL filter used to select which traces get facets and topics          |
| `--clear-filter`                  | Clear the top-level BTQL filter                                        |
| `--facet <NAME>`                  | Facet labels to enable (repeatable; uses built-in defaults if omitted) |
| `--embedding-model <MODEL>`       | Embedding model for new topic maps                                     |

### bt topics config delete

Permanently delete the Topics automation for the active project.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt topics config delete
bt topics config delete --automation-id <ID>
bt topics config delete --force
```

<Warning>
  Deleting an automation is irreversible. Its configuration and scheduling settings cannot be recovered. Existing topic maps and topic labels already written to traces are preserved.
</Warning>

| Flag                   | Description                        |
| ---------------------- | ---------------------------------- |
| `--automation-id <ID>` | Target a specific automation by ID |
| `--force` / `-f`       | Skip the confirmation prompt       |

### bt topics config set

Update editable Topics configuration fields for an existing automation. Only the fields you specify are changed.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt topics config set --topic-window 2d
bt topics config set --sampling-rate 50 --automation-id <ID>
bt topics config set --clear-filter
```

| Flag                              | Description                                                   |
| --------------------------------- | ------------------------------------------------------------- |
| `--automation-id <ID>`            | Specific automation ID to update                              |
| `--name <NAME>`                   | Human-friendly automation name                                |
| `--description <DESC>`            | Human-friendly automation description                         |
| `--topic-window <DURATION>`       | Topic window duration (e.g., `1h`, `1d`)                      |
| `--generation-cadence <DURATION>` | How often to generate fresh topic maps (e.g., `1h`, `1d`)     |
| `--relabel-overlap <DURATION>`    | Relabel overlap duration (e.g., `1h`)                         |
| `--idle-time <DURATION>`          | Trace idle wait duration before processing (e.g., `30s`)      |
| `--sampling-rate <PERCENT>`       | Percent of matching traces to sample (e.g., `25` or `25%`)    |
| `--filter <EXPR>`                 | BTQL filter used to select which traces get facets and topics |
| `--clear-filter`                  | Clear the top-level BTQL filter                               |

### bt topics config topic-map

View or edit per-topic-map settings by topic map name or function ID.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt topics config topic-map <TOPIC_MAP>
bt topics config topic-map show <TOPIC_MAP>
bt topics config topic-map set <TOPIC_MAP>
bt topics config topic-map --automation-id <ID> <TOPIC_MAP>
```

| Argument/Flag          | Description                         |
| ---------------------- | ----------------------------------- |
| `<TOPIC_MAP>`          | Topic map name or function ID       |
| `--automation-id <ID>` | Search within a specific automation |

### bt topics config topic-map set

Update a configured topic map by name or function ID.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt topics config topic-map set <TOPIC_MAP>
bt topics config topic-map set my-map --algorithm kmeans --n-clusters 10
```

| Argument/Flag                     | Description                                             |
| --------------------------------- | ------------------------------------------------------- |
| `<TOPIC_MAP>`                     | Topic map name or function ID (required)                |
| `--name <NAME>`                   | Human-friendly topic map name                           |
| `--description <DESC>`            | Human-friendly topic map description                    |
| `--source-facet <FACET>`          | Facet field this topic map clusters                     |
| `--embedding-model <MODEL>`       | Embedding model for clustering                          |
| `--distance-threshold <FLOAT>`    | Maximum centroid distance before returning `no_match`   |
| `--algorithm <ALGO>`              | Clustering algorithm: `hdbscan` or `kmeans`             |
| `--dimension-reduction <METHOD>`  | Dimension reduction method: `umap`, `pca`, or `none`    |
| `--sample-size <NUM>`             | Maximum rows sampled during topic map generation        |
| `--n-clusters <NUM>`              | Number of clusters (kmeans only)                        |
| `--min-cluster-size <NUM>`        | Minimum cluster size (hdbscan only)                     |
| `--min-samples <NUM>`             | Minimum samples (hdbscan only)                          |
| `--hierarchy-threshold <NUM>`     | Hierarchy threshold for naming hierarchical clusters    |
| `--naming-model <MODEL>`          | LLM model used to name generated topics                 |
| `--disable-reconciliation <BOOL>` | Disable reconciliation against previously saved reports |

## bt topics report

<Note>
  This is an advanced debugging command. Use it to share a topic map's output with Braintrust when troubleshooting clustering behavior.
</Note>

Download the saved report for a [topic map](/docs/observe/topics) as JSON. The report is the generated clustering result, including topic names and cluster structure. It's the saved output that Topics reconciles against when re-generating, so topic names stay stable across runs (see [Tune clustering settings](/docs/observe/topics/manage#tune-clustering-settings)).

Identify the topic map by its function ID, which you can find with `bt topics config`. The report writes to stdout unless you pass `--output`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
# Print the latest report to stdout
bt topics report fn_123

# Download a specific version to a file
bt topics report fn_123 --version 0000000000000001 --output report.json
```

**Flags**

| Flag                  | Description                                                    |
| --------------------- | -------------------------------------------------------------- |
| `--id <FUNCTION_ID>`  | Topic map function ID (also accepted as a positional argument) |
| `--version <XACT_ID>` | Download a specific topic map version (default: the latest)    |
| `--output <PATH>`     | Write the report JSON to a file (default: stdout)              |

## bt topics btmap

<Note>
  This is an advanced debugging command. Use it to share a topic map's raw artifact with Braintrust when troubleshooting clustering behavior.
</Note>

Download the raw `.btmap` artifact for a [topic map](/docs/observe/topics). This is the low-level binary topic map that underlies the [report](#bt-topics-report). Most users want `bt topics report` instead, which returns human-readable JSON.

Identify the topic map by its function ID, which you can find with `bt topics config`. The artifact writes to stdout unless you pass `--output`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
# Write the latest .btmap artifact to a file
bt topics btmap fn_123 --output topic-map.btmap

# Download a specific version
bt topics btmap fn_123 --version 0000000000000001 --output topic-map.btmap
```

**Flags**

| Flag                  | Description                                                    |
| --------------------- | -------------------------------------------------------------- |
| `--id <FUNCTION_ID>`  | Topic map function ID (also accepted as a positional argument) |
| `--version <XACT_ID>` | Download a specific topic map version (default: the latest)    |
| `--output <PATH>`     | Write the `.btmap` bytes to a file (default: stdout)           |