bt sync

bt sync downloads Braintrust data to local NDJSON files and uploads it back. Use it for offline analysis, backup, or migrating data between projects and orgs. Object ref format: object_type:name_or_id Supported object types: project_logs, experiment, dataset

# Pull the last 24 hours of logs to ./bt-sync/
bt sync pull project_logs:my-project --window 24h

# Pull a specific experiment
bt sync pull experiment:my-experiment --project my-project

# Push local files back to Braintrust
bt sync push project_logs:my-project --in bt-sync/project_logs

# Check local sync state
bt sync status project_logs:my-project

Pull flags

Flag	Env var	Description
`--window <DURATION>`	`BT_SYNC_WINDOW`	Time window (default: `3d`; e.g. `1h`, `7d`)
`--filter <EXPR>`		SQL filter expression
`--traces <N>`		Max root traces to fetch
`--spans <N>`		Max spans to fetch
`--page-size <N>`		SQL pagination page size (default: `1000`)
`--cursor <CURSOR>`		Initial cursor for spans mode (implies a fresh run)
`--fresh`		Ignore previous state, start over
`--root <PATH>`		Output directory (default: `bt-sync`)
`--workers <N>`		Concurrent fetch workers
`--include-vectors`		Include embeddings (needed for re-ingestion via push)
`--verbose` / `-v`	`BRAINTRUST_VERBOSE`	Print SQL queries and timing

Push flags

Flag	Env var	Description
`--in <PATH>`		Input file or directory (defaults to latest pull output)
`--filter <EXPR>`		SQL filter expression (used in spec hashing and pull auto-resolution)
`--traces <N>`		Upload at most N distinct root traces
`--spans <N>`		Upload at most N span rows
`--page-size <N>`		Rows per upload batch (default: `1000`)
`--fresh`		Ignore previous state, start over
`--root <PATH>`		Root directory for sync artifacts (default: `bt-sync`)
`--workers <N>`		Concurrent upload workers
`--max-batch-bytes <N>`	`BT_SYNC_PUSH_MAX_BATCH_BYTES`	Maximum input bytes per upload batch (default: `16777216`)
`--max-in-flight-bytes <N>`	`BT_SYNC_PUSH_MAX_IN_FLIGHT_BYTES`	Maximum input bytes held by in-flight upload batches (default: `134217728`)

API

CLI

SQL

Pull flags

Push flags

​Pull flags

​Push flags

Pull flags

Push flags