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