bt sync - Braintrust

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

bt sync pull project_logs:my-project --window 24h
bt sync push project_logs:my-project --in bt-sync/project_logs
bt sync status project_logs:1234-uuid

Pull flags

Flag	Env var	Description
`--window <DURATION>`	`BT_SYNC_WINDOW`	Relative time window (for example, `1h` or `7d`). Defaults to `3d` for project logs; experiment and dataset pulls are unbounded
`--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 forced restart)
`--force`		Ignore previous state, start over
`--root <PATH>`		Output directory (default: `bt-sync`)
`--workers <N>`		Concurrent fetch workers (defaults to the OS-reported number of available CPU threads)
`--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`)
`--force`		Ignore previous state, start over
`--root <PATH>`		Root directory for sync artifacts (default: `bt-sync`)
`--workers <N>`		Concurrent upload workers (defaults to the OS-reported number of available CPU threads)
`--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`)

Status flags

bt sync status looks up local state for an object ID and a set of sync options.

Flag	Description
`--direction <DIRECTION>`	Sync direction: `pull` or `push` (default: `pull`)
`--filter <EXPR>`	SQL filter expression used by the sync spec
`--traces <N>`	Trace limit used by the sync spec
`--spans <N>`	Span limit used by the sync spec
`--page-size <N>`	Page size used by the sync spec (default: `1000`)
`--root <PATH>`	Root directory for sync artifacts (default: `bt-sync`)
`--in <PATH>`	Input path used by a push spec. Required with `--direction push`
`--include-vectors`	Include vector-aware pull specs when resolving status. Pull only