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 thread and waterfall subcommands render a single trace non-interactively, which is useful for scripting and coding agents.

bt view logs                                    # Browse project logs
bt view logs --window 30m                       # Last 30 minutes
bt view logs --list-mode spans                  # One row per span instead of per trace
bt view logs --search "error"                   # Full-text search
bt view logs --url <braintrust-url>             # Jump to a specific view
bt view trace --url <braintrust-url>            # Open a specific trace
bt view span --url <braintrust-url>             # Open a specific span
bt view thread --url <braintrust-url>           # Print a trace's LLM conversation transcript
bt view waterfall --url <braintrust-url>        # Render a trace waterfall (timing, tokens, cost, cache)

Keyboard shortcuts

Key	Action
`↑` / `↓`	Navigate rows
`Enter`	Open trace
`/`	Edit search
`r`	Refresh
`t`	Toggle span / thread view
`←` / `→`	Switch detail panes
`Ctrl+k`, `Enter`	Open current item in browser
`Backspace` / `Esc`	Go back
`q`	Quit

Flags

Flag	Description
`--window <DURATION>`	Relative time window (e.g. `30m`, `3d`; default: `1h`)
`--since <TIMESTAMP>`	Absolute lower bound (overrides `--window`)
`--search <TEXT>`	Free-text search
`--filter <EXPR>`	SQL filter expression
`--list-mode <MODE>`	`summary` (default) or `spans` — one row per span
`--limit <N>`	Rows to fetch (default: 50)
`--url <URL>`	Open a specific Braintrust URL directly
`--non-interactive`	Print results without the interactive interface
`--json`	Output as JSON (available on `bt view logs`, `bt view trace`, and `bt view span`)
`--object-ref <REF>`	Target a specific object (`project_logs:<id>`, `experiment:<id>`, `dataset:<id>`)

bt view thread

Print a trace’s LLM conversation as a single ordered transcript. 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 the same options as bt view trace: --trace-id <ID> (alias --root-span-id), --url <URL> (or a positional URL), or --object-ref <REF> with --project-id.

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

Flags

bt view thread

bt view waterfall

​Keyboard shortcuts

​Flags

​bt view thread

​bt view waterfall

Keyboard shortcuts

Flags

bt view thread

bt view waterfall