Documentation
CLICommands

ox doctor

Run diagnostics on your ox installation, project configuration, git health, agent environment, and connected services. Use --fix to auto-repair common issues, or --fix-slug to target specific checks.

Usage

terminal
$

What it checks

Authentication

  • Valid session token
  • Token expiration
  • Correct permissions

Repository registration

  • Repository is registered with SageOx
  • Local configuration matches server
  • Repository exists on platform

Context injection

  • Context injection is configured
  • CLAUDE.md and context files are set up
  • Context can be retrieved from server

Session uploads

  • Coding sessions cached locally have reached the Ledger
  • Pending uploads left behind by an earlier failure are retried

This check repairs itself: when ox doctor finds sessions that never finished uploading, it retries them for you rather than only reporting the backlog. If SageOx has told you that your coding sessions stopped arriving, this is the check that clears it.

Output

By default, ox doctor lists the checks that need attention. Add --verbose to show every check, including passed and skipped ones.

Examples

terminal
# Auto-repair common issues
$
terminal
# Fix specific checks by slug
$
terminal
# Show all checks, including passed and skipped
$

Flags

FlagDescription
--fixAutomatically fix issues where possible
--fix-slugFix specific issues by slug (repeatable, for example --fix-slug=ledger-path)
--force-session-uploadsForce detection and upload of incomplete sessions
--gcForce garbage collection (reclone) of Team Contexts
-v, --verboseShow all checks, including passed and skipped
-y, --yesAnswer yes to all prompts (for non-interactive use)

Exit codes

CodeMeaning
0No check failed. Warnings and skipped checks alone exit 0.
1A check failed or required setup is missing, including with --json

With --json, the output is a single report. Read summary.has_failed for the result, and use the exit code for scripting.

Common issues

Not authenticated - Run ox login

Repository not registered - Run ox init

Expired token - Run ox login

Sessions not arriving - Run ox doctor --fix in the affected repository to retry pending uploads and repair what it can. To force detection and upload of incomplete sessions, run ox doctor --force-session-uploads. If sessions still don't arrive, share the output of ox doctor --json with SageOx support.

What's next