> ## 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"}}
# 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`) |