ox sync
Manually synchronize your Ledger and Team Context repositories with the server, then converge the current repository with applicable Team Context artifacts. The ox daemon handles this automatically in most cases, you rarely need this command.
Usage
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 (clears config and optionally deletes the repo) |
--read-only | Refresh one Ledger using the selected team token, without the daemon |
--repo <repo_uuid> | Repository ID for --read-only (repo_<uuid>) |
--check | Check local read-only readiness without contacting the server |
--timeout <duration> | Maximum duration of a read-only operation, including lock wait and hydration |
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).
Convergence delivers Add-on-managed and hand-authored Team Context content through the same path. It does not check the Add-on Catalog for newer releases; use ox addons update for catalog updates.
When you need manual sync
The daemon syncs automatically on file changes in your project, at periodic intervals, and on session start and end events. 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
Headless read-only mode
Read-only mode runs a bounded Ledger refresh without the daemon. It uses SAGEOX_TOKEN and SAGEOX_ENDPOINT, independent of the current project.
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).
Ordinary sync requires the daemon, which handles pull operations for consistent sync behavior and proper locking. Check daemon status:
If the daemon isn't running, start it:
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.
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
- Team Context: Understand what's in your Team Context
- ox doctor: Diagnose sync and configuration issues
- ox init: Initialize a repository with SageOx