Skip to main content

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 datasets manages remote Braintrust datasets directly from the CLI.

​
Subcommands

SubcommandDescription
bt datasets listList all datasets in the current project
bt datasets create <name>Create a dataset, optionally seeding it with records
bt datasets update <name>Upsert records into a dataset (aliases: add, refresh)
bt datasets view <name>Display dataset metadata and preview records
bt datasets delete <name>Delete a dataset and all its records

​
bt datasets list

bt datasets list
Lists all datasets in the current project.

​
bt datasets create

Create a dataset, optionally seeding it with records from a file, stdin, or inline JSON. 
# Create an empty dataset
bt datasets create my-dataset

# Create with a description
bt datasets create my-dataset --description "Dataset for smoke tests"

# Seed from a JSONL file
bt datasets create my-dataset --file records.jsonl

# Seed from stdin
cat records.jsonl | bt datasets create my-dataset

# Seed with inline JSON rows
bt datasets create my-dataset --rows '[{"id":"case-1","input":{"text":"hi"},"expected":"hello"}]'

# Rows without id fields get auto-generated stable IDs
bt datasets create my-dataset --rows '[{"input":{"text":"hi"},"expected":"hello"}]'

​
Flags

FlagDescription
--description <TEXT>Dataset description
--file <PATH>Seed from a JSONL file
--rows <JSON>Seed with an inline JSON array of rows
When rows omit an id field, bt datasets auto-generates stable record IDs.

​
bt datasets update

Upsert records into an existing dataset. Also available as bt datasets add and bt datasets refresh. 
bt datasets update my-dataset --file records.jsonl
bt datasets add my-dataset --rows '[{"id":"case-2","input":{"text":"bye"},"expected":"goodbye"}]'
bt datasets refresh my-dataset --file records.jsonl --id-field metadata.case_id

​
Flags

FlagDescription
--file <PATH>Input JSONL file
--rows <JSON>Inline JSON array of rows
--id-field <PATH>Dot-separated path to use as the record ID instead of the id field
Each row must have a stable ID via the id field or --id-field. Rows without IDs are rejected.update, add, and refresh upsert rows directly — rows not in the input are not deleted. refresh fails if the dataset does not exist.--id-field uses dot-separated paths (e.g., metadata.case_id). Escape literal dots as \. and literal backslashes as \\.Input may also be a JSON object with a top-level rows array (matching bt datasets view --json output). Each row in rows is validated against the accepted fields: id, input, expected, metadata, tags, and origin.

​
bt datasets view

Display dataset metadata and preview records in the terminal. 
bt datasets view my-dataset            # up to 200 rows by default
bt datasets view my-dataset --limit 50
bt datasets view my-dataset --all-rows
bt datasets view my-dataset --full     # exact values, no truncation
bt datasets view my-dataset --json     # machine-readable JSON output

​
Flags

FlagDescription
--limit <N>Maximum rows to show (default: 200)
--all-rowsShow all rows regardless of dataset size
--fullShow exact values without truncation
--jsonOutput as JSON (compatible as input to bt datasets update)

​
bt datasets delete

Permanently delete a dataset and all its records. 
bt datasets delete my-dataset
This operation is irreversible. All records in the dataset are permanently deleted.