> ## 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 custom-views

> Bootstrap, preview, and push custom trace and dataset view definitions to Braintrust

export const feature_0 = "The custom views CLI workflow"

export const verb_0 = "is"

`bt custom-views` manages [custom views](/docs/annotate/custom-views) defined in local TypeScript files. Use it to scaffold starter files, preview views against real data, and publish them to Braintrust without going through the browser editor.

<Warning>
  {feature_0} {verb_0} in [public preview](/docs/feature-lifecycle) and can change before reaching general availability.
</Warning>

Each custom view file default-exports a definition containing its configuration and React component, using `customTraceView()` or `customDatasetView()` from `braintrust/custom-views`. See the [TypeScript examples](/docs/annotate/custom-views#push-views-from-the-cli) to write a trace or dataset view before previewing and pushing it.

<Note>
  `bt` v0.22.0 or later is required. `bt custom-views push` requires Node.js. Preview assets and SDK helpers are embedded in the CLI.

  React and the `braintrust/custom-views` helpers are provided by the CLI. You do not need to install them locally to bootstrap, preview, or push a view. Install any additional packages your view imports in your local project.
</Note>

## Subcommands

| Subcommand | Description |
| - | - |
| `bt custom-views push <PATH>` | Push local custom view definitions to Braintrust |
| `bt custom-views trace bootstrap <NAME>` | Create a starter trace custom view file |
| `bt custom-views trace preview <PATH>` | Preview a trace custom view locally in a browser |
| `bt custom-views dataset bootstrap <NAME>` | Create a starter dataset custom view file |
| `bt custom-views dataset preview <PATH>` | Preview a dataset custom view locally in a browser |

## bt custom-views push

Push one or more custom view definitions to Braintrust. `bt` scans the path for files matching the pattern `*.view.tsx`, `*.view.ts`, `*.view.jsx`, `*.view.js`, `*-view.tsx`, `*-view.ts`, `*-view.jsx`, or `*-view.js`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt custom-views push ./braintrust-custom-views --project my-project
bt custom-views push ./conversation.trace-view.tsx --project my-project
```

If a view with the same slug already exists, the command fails by default. Add `--if-exists replace` to update it.

**Flags**

| Flag | Env var | Default | Description |
| - | - | - | - |
| `<PATH>` | — | `.` | File or directory path(s) to scan for custom view definitions |
| `--file <PATH>` | `BT_CUSTOM_VIEWS_PUSH_FILES` | — | File or directory path (alternative to the positional argument; comma-separated) |
| `--if-exists <MODE>` | `BT_CUSTOM_VIEWS_PUSH_IF_EXISTS` | `error` | Conflict behavior when a view with the same slug already exists: `error`, `replace`, or `ignore` |
| `--yes`, `-y` | `BT_CUSTOM_VIEWS_PUSH_YES` | `false` | Skip the confirmation prompt |

Set `project` in each view definition, or pass `--project` to use the same project for all views.

## bt custom-views trace bootstrap

Create a starter trace custom view file in the `braintrust-custom-views/` directory (created if it does not exist). The file uses `customTraceView` from `braintrust/custom-views` and exports a React component that receives `trace` and `span` props.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt custom-views trace bootstrap 'Trace Review'
bt custom-views trace bootstrap 'Conversation' --file ./my-views/conversation.trace-view.tsx
```

**Flags**

| Flag | Env var | Default | Description |
| - | - | - | - |
| `<NAME>` | — | — | Custom view name (required unless `--name` is used) |
| `--name <NAME>` | `BT_CUSTOM_VIEWS_BOOTSTRAP_NAME` | — | Custom view name (alternative to the positional argument) |
| `--file <PATH>` | `BT_CUSTOM_VIEWS_BOOTSTRAP_FILE` | `braintrust-custom-views/<name>.trace-view.tsx` | Output file path |
| `--force`, `-f` | `BT_CUSTOM_VIEWS_BOOTSTRAP_FORCE` | `false` | Overwrite an existing file |

## bt custom-views dataset bootstrap

Create a starter dataset custom view file in the `braintrust-custom-views/` directory. The file uses `customDatasetView` from `braintrust/custom-views` and exports a React component that receives `input`, `expected`, `metadata`, and `update` props.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt custom-views dataset bootstrap 'Dataset Review'
bt custom-views dataset bootstrap 'Dataset Review' --dataset my-dataset
```

**Flags**

| Flag | Env var | Default | Description |
| - | - | - | - |
| `<NAME>` | — | — | Custom view name (required unless `--name` is used) |
| `--name <NAME>` | `BT_CUSTOM_VIEWS_BOOTSTRAP_NAME` | — | Custom view name (alternative to the positional argument) |
| `--file <PATH>` | `BT_CUSTOM_VIEWS_BOOTSTRAP_FILE` | `braintrust-custom-views/<name>.dataset-view.tsx` | Output file path |
| `--force`, `-f` | `BT_CUSTOM_VIEWS_BOOTSTRAP_FORCE` | `false` | Overwrite an existing file |
| `--dataset <NAME>` | `BT_CUSTOM_VIEWS_BOOTSTRAP_DATASET` | — | Dataset name to reference in the starter file |
| `--dataset-id <ID>` | `BT_CUSTOM_VIEWS_BOOTSTRAP_DATASET_ID` | — | Dataset ID to reference in the starter file |

## bt custom-views trace preview

Preview a trace custom view in a local browser window using a full trace and selected span from Braintrust. The preview server serves the bundled component and hot-reloads on file changes. Edits applied from the preview stay local and are discarded on reload. They do not write to Braintrust.

Open a trace in Braintrust's logs or an experiment and copy the URL from your browser's address bar. Pass it to `--url` in quotes to preserve its query parameters:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt custom-views trace preview ./conversation.trace-view.tsx --url "<BRAINTRUST_TRACE_URL>"
```

The CLI resolves the trace and selected span from the URL. If the URL does not include a project, also pass `--project`. You can also select a trace by root span ID and optionally select a span:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt custom-views trace preview ./conversation.trace-view.tsx --trace-id <ROOT_SPAN_ID> --project my-project
bt custom-views trace preview ./conversation.trace-view.tsx --trace-id <ROOT_SPAN_ID> --span-id <SELECTED_SPAN_ID> --project my-project
```

When resolving a URL, the preview server searches the last 30 days by default. Use `--lookup-window` to search further back.

**Flags**

| Flag | Env var | Default | Description |
| - | - | - | - |
| `<PATH>` | — | — | Custom view file to preview (required unless `--file` is used) |
| `--file <PATH>` | `BT_CUSTOM_VIEWS_PREVIEW_FILE` | — | Custom view file (alternative to the positional argument) |
| `--view <NAME>` | `BT_CUSTOM_VIEWS_PREVIEW_VIEW` | — | View slug or name to preview (when the file defines multiple views) |
| `--url <URL>` | `BT_CUSTOM_VIEWS_PREVIEW_URL` | — | Braintrust app URL to resolve trace data from |
| `--project-id <ID>` | `BT_CUSTOM_VIEWS_PREVIEW_PROJECT_ID` | — | Project ID to query for trace data |
| `--trace-id <ID>` | `BT_CUSTOM_VIEWS_PREVIEW_TRACE_ID` | — | Root span ID for the trace (alias: `--root-span-id`) |
| `--span-id <ID>` | `BT_CUSTOM_VIEWS_PREVIEW_SPAN_ID` | — | Selected span ID or row ID |
| `--lookup-window <DURATION>` | `BT_CUSTOM_VIEWS_PREVIEW_LOOKUP_WINDOW` | `30d` | Lookback window when resolving a URL's span ID (for example, `7d`, `90d`) |
| `--port <PORT>` | `BT_CUSTOM_VIEWS_PREVIEW_PORT` | ephemeral | Local port to bind |
| `--no-open` | `BT_CUSTOM_VIEWS_PREVIEW_NO_OPEN` | `false` | Do not open a browser automatically |

## bt custom-views dataset preview

Preview a dataset custom view in a local browser window using one row's `input`, `expected`, `metadata`, and `tags`. Select the dataset by name or ID with `--dataset`, or use the dataset configured in the view definition. Dataset previews do not accept `--url`. Edits stay local, are discarded on reload, and are not written to Braintrust.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt custom-views dataset preview ./dataset.dataset-view.tsx --project my-project --dataset my-dataset --row-index 0
bt custom-views dataset preview ./dataset.dataset-view.tsx --project my-project --dataset my-dataset --row-id <ROW_ID>
```

`--row-index` selects a row by its zero-based position in the dataset rows returned by the API: `0` selects the first row, `1` the second, and so on. Use `--row-id` to select a specific row independently of ordering. If both flags are supplied, `--row-id` takes precedence.

**Flags**

| Flag | Env var | Default | Description |
| - | - | - | - |
| `<PATH>` | — | — | Custom view file to preview (required unless `--file` is used) |
| `--file <PATH>` | `BT_CUSTOM_VIEWS_PREVIEW_FILE` | — | Custom view file (alternative to the positional argument) |
| `--view <NAME>` | `BT_CUSTOM_VIEWS_PREVIEW_VIEW` | — | View slug or name to preview (when the file defines multiple views) |
| `--dataset <NAME>` | `BT_CUSTOM_VIEWS_PREVIEW_DATASET` | — | Dataset name or ID |
| `--row-id <ID>` | `BT_CUSTOM_VIEWS_PREVIEW_ROW_ID` | — | Dataset row ID |
| `--row-index <N>` | `BT_CUSTOM_VIEWS_PREVIEW_ROW_INDEX` | `0` | Zero-based position in the dataset rows returned by the API, used when `--row-id` is omitted |
| `--port <PORT>` | `BT_CUSTOM_VIEWS_PREVIEW_PORT` | ephemeral | Local port to bind |
| `--no-open` | `BT_CUSTOM_VIEWS_PREVIEW_NO_OPEN` | `false` | Do not open a browser automatically |

## Example workflow

With `bt` v0.22.0 or later and Node.js installed, bootstrap, preview, and push a trace custom view. Copy a trace URL from your browser's address bar for the preview step:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
# 1. Create a starter file in braintrust-custom-views/
bt custom-views trace bootstrap 'Trace Review'

# 2. Preview against a real trace
bt custom-views trace preview ./braintrust-custom-views/trace-review.trace-view.tsx \
  --url "<BRAINTRUST_TRACE_URL>"

# 3. Push to Braintrust when you're satisfied
bt custom-views push ./braintrust-custom-views --project my-project
```