# ox sync (/docs/cli/commands/sync)



ox sync [#ox-sync]

Manually synchronize your Ledger and Team Context repositories with the server. The ox daemon handles this automatically in most cases — you rarely need this command.

Usage [#usage]

<Terminal>
  <TerminalCommand>
    ox sync [flags]
  </TerminalCommand>
</Terminal>

Flags [#flags]

| Flag                 | Description                           |
| -------------------- | ------------------------------------- |
| `--team <id>`        | Sync a specific Team Context by ID    |
| `--all-teams`        | Sync all configured Team Contexts     |
| `--remove-team <id>` | Remove a Team Context from local sync |

What gets synced [#what-gets-synced]

The sync command pulls the latest changes from two git repositories:

| Repository       | Contains                                             | Location                |
| ---------------- | ---------------------------------------------------- | ----------------------- |
| **Ledger**       | Commit history, code observations, project decisions | `.sageox/ledger/`       |
| **Team Context** | Conventions, distilled discussions, team knowledge   | `.sageox/teams/<team>/` |

Both repositories use `git pull --rebase` to incorporate server changes while preserving any local commits (like uncommitted observations).

When you need manual sync [#when-you-need-manual-sync]

The daemon syncs automatically every 5 minutes. Manual sync is useful when:

* **Network was down** — Force a sync after reconnecting
* **Need latest context immediately** — Before starting a session that needs recent team decisions
* **Debugging sync issues** — Verify that sync works before running `ox doctor`
* **After changing team membership** — Pull new Team Context access

Examples [#examples]

<Terminal>
  <TerminalComment>
    Sync everything (Ledger + all Team Contexts)
  </TerminalComment>

  <TerminalCommand>
    ox sync
  </TerminalCommand>
</Terminal>

<Terminal>
  <TerminalComment>
    Sync only a specific team
  </TerminalComment>

  <TerminalCommand>
    ox sync --team team_01JQ2X3Y4Z
  </TerminalCommand>
</Terminal>

<Terminal>
  <TerminalComment>
    Sync all Team Contexts (but not Ledger)
  </TerminalComment>

  <TerminalCommand>
    ox sync --all-teams
  </TerminalCommand>
</Terminal>

<Terminal>
  <TerminalComment>
    Remove a team you no longer need locally
  </TerminalComment>

  <TerminalCommand>
    ox sync --remove-team team_01JQ2X3Y4Z
  </TerminalCommand>
</Terminal>

Automatic sync (daemon) [#automatic-sync-daemon]

The ox daemon (`oxd`) runs in the background and syncs automatically. The sync interval is controlled by your team's manifest (default: 5 minutes).

Check daemon status:

<Terminal>
  <TerminalCommand>
    ox daemon status
  </TerminalCommand>
</Terminal>

If the daemon isn't running, start it:

<Terminal>
  <TerminalCommand>
    ox daemon start
  </TerminalCommand>
</Terminal>

<Callout type="info">
  Most users never need `ox sync` — the daemon handles everything. If you find yourself running it often, check that your daemon is running with `ox daemon status`.
</Callout>

Troubleshooting [#troubleshooting]

**"Not authenticated"** — Run `ox login` first.

**"Repository not initialized"** — Run `ox init` in your project directory.

**"Sync failed: network error"** — Check your internet connection and try again.

**"Merge conflict"** — This shouldn't happen (files use UUIDv7 names to avoid conflicts). If it does, the command will log an error and flag it for manual resolution.

What's next [#whats-next]

* [Team Context](/docs/features/team-context) — Understand what's in your Team Context
* [ox doctor](/docs/cli/doctor) — Diagnose sync and configuration issues
* [ox init](/docs/cli/init) — Initialize a repository with SageOx