bt custom-views - Braintrust

bt custom-views manages 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.

The custom views CLI workflow is in public preview and can change before reaching general availability.

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 to write a trace or dataset view before previewing and pushing it.

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.

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.

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.

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.

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:

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:

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.

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:

# 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

​Subcommands

​bt custom-views push

​bt custom-views trace bootstrap

​bt custom-views dataset bootstrap

​bt custom-views trace preview

​bt custom-views dataset preview

​Example workflow

Subcommands

bt custom-views push

bt custom-views trace bootstrap

bt custom-views dataset bootstrap

bt custom-views trace preview

bt custom-views dataset preview

Example workflow