bt view

bt view is an interactive terminal UI for browsing logs, traces, and spans. Use it to inspect individual requests, drill into LLM conversation threads, and navigate span hierarchies. The logs, trace, thread, and span subcommands open the TUI by default when output is a TTY. Pass --non-interactive or --json to print without the TUI. waterfall always prints non-interactively.

bt view logs --limit 25
bt view trace --trace-id <ROOT_SPAN_ID>
bt view span --id <SPAN_ROW_ID>
bt view thread --trace-id <ROOT_SPAN_ID>
bt view waterfall --trace-id <ROOT_SPAN_ID>

Keyboard shortcuts

Key	Action
`↑` / `↓`	Navigate rows
`Enter`	Open trace
`/`	Edit search
`r`	Refresh
`t`	Toggle span / thread view
`←` / `→`	Switch detail panes
`Ctrl+k`	Prompt for a Braintrust URL and open that location in the TUI
`Backspace` / `Esc`	Go back
`q`	Quit

bt view logs flags

Flag	Description
`--project-id <PROJECT_ID>`	Project ID to query. Overrides `--project`
`--object-ref <REF>`	Target a specific object: `project_logs:<selector>`, `experiment:<selector>`, or `dataset:<selector>`. Interactive mode supports project logs only. Experiments and datasets require `--non-interactive` or `--json`
`--url <URL>`	Open a specific Braintrust URL directly. Also accepted as a positional argument
`--window <DURATION>`	Relative time window, e.g. `30m` or `3d` (default: `1h`)
`--since <TIMESTAMP>`	Absolute lower bound (overrides `--window`)
`--search <TEXT>`	Free-text search
`--filter <EXPR>`	Additional BTQL filter expression
`--list-mode <MODE>`	`summary` (default) or `spans` — one row per span
`--limit <N>`	Rows to fetch (default: 50)
`--cursor <CURSOR>`	Cursor returned from a previous list call
`--preview-length <N>`	Preview length for list rows (default: 125)
`--non-interactive`	Print results without the interactive interface
`--print-queries`	Print each BTQL query and invoke payload before execution
`--json`	Output as JSON

Trace and span flags

Use bt view trace, bt view thread, or bt view waterfall to render a full trace. Use bt view span to fetch one span.

Command	Flag	Description
`trace`, `thread`, `waterfall`	`--trace-id <TRACE_ID>`	Root span ID for the trace
`trace`, `thread`, `waterfall`	`--url <URL>`	Braintrust app URL to resolve to a trace. Also accepted as a positional argument
`trace`	`--object-ref <REF>`	Target object: `project_logs:<selector>`, `experiment:<selector>`, or `dataset:<selector>`. Interactive mode supports project logs only. Experiments and datasets require `--non-interactive` or `--json`
`waterfall`	`--object-ref <REF>`	Target object: `project_logs:<selector>`, `experiment:<selector>`, or `dataset:<selector>`
`thread`	`--object-ref <REF>`	Target object: `project_logs:<selector>` (thread supports project logs only)
`trace`, `thread`, `waterfall`	`--project-id <PROJECT_ID>`	Project ID to query. Overrides `--project` for project logs
`trace`, `thread`, `waterfall`	`--limit <N>`	Number of spans to fetch (default: 100)
`trace`, `thread`, `waterfall`	`--preview-length <N>`	Preview length for span rows (default: 125)
`trace`	`--cursor <CURSOR>`	Cursor returned from a previous trace fetch
`trace`, `thread`, `waterfall`	`--print-queries`	Print each BTQL query and invoke payload before execution
`trace`, `thread`, `waterfall`	`--non-interactive`	Force non-interactive mode
`trace`, `thread`, `waterfall`	`--json`	Output as JSON
`span`	`--id <ID>`	Span row ID
`span`	`--url <URL>`	Braintrust app URL to resolve to a span. Also accepted as a positional argument
`span`	`--object-ref <REF>`	Target object: `project_logs:<selector>`, `experiment:<selector>`, or `dataset:<selector>`. Interactive mode supports project logs only. Experiments and datasets require `--non-interactive` or `--json`
`span`	`--project-id <PROJECT_ID>`	Project ID to query. Overrides `--project` for project logs
`span`	`--print-queries`	Print each BTQL query before execution
`span`	`--non-interactive`	Force non-interactive mode
`span`	`--json`	Output as JSON

bt view thread

Show a trace’s LLM conversation as a single ordered transcript. In a terminal, bt view thread opens the TUI by default. Pass --non-interactive or --json to print the transcript directly. Braintrust’s trace preprocessor collapses repeated messages across LLM spans into one thread, so you can inspect a conversation without opening each span individually.

bt view thread --trace-id <ROOT_SPAN_ID>
bt view thread --url <braintrust-url>

Select the trace with --trace-id <ID>, --url <URL> (or a positional URL), or --project-id. Thread only supports project logs sources.

bt view waterfall

Render a trace waterfall showing each span’s offset and duration within the trace, along with model, token, cost, and cache details such as prompt cache hit percentage when available. Use the timeline alias for parity with the Braintrust app’s Timeline tab.

bt view waterfall --trace-id <ROOT_SPAN_ID>
bt view timeline --url <braintrust-url>

Select the trace with the same options as bt view trace.

API

CLI

SQL

Keyboard shortcuts

bt view logs flags

Trace and span flags

bt view thread

bt view waterfall

​Keyboard shortcuts

​bt view logs flags

​Trace and span flags

​bt view thread

​bt view waterfall

Keyboard shortcuts

bt view logs flags

Trace and span flags

bt view thread

bt view waterfall