> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# bt sync

> Sync Braintrust logs, experiments, and datasets to and from local NDJSON files

`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`

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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>` | `BRAINTRUST_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>` | `BRAINTRUST_SYNC_PUSH_MAX_BATCH_BYTES` | Maximum input bytes per upload batch (default: `16777216`) |
| `--max-in-flight-bytes <N>` | `BRAINTRUST_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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.