CLI Overview
ctxo is both a Model Context Protocol (MCP) server and a CLI. Running ctxo with no arguments starts the stdio MCP server; any other argument dispatches to a subcommand.
Command summary
| Command | Purpose |
|---|---|
ctxo install | Install language plugins (auto-detects if omitted) |
ctxo init | Interactive setup: AI tool rules, git hooks, plugin install |
ctxo index | Build the codebase index (symbols, edges, history) |
ctxo watch | File watcher for incremental re-indexing |
ctxo sync | Rebuild the SQLite cache from committed JSON |
ctxo status | Show index manifest, symbol counts, per-file freshness |
ctxo doctor | Health check every subsystem (with optional --fix) |
ctxo visualize | Generate an interactive dependency graph HTML |
ctxo verify-index | CI gate: fail if index drifts from source |
ctxo stats | Show MCP usage statistics (--json, --days N, --clear) |
ctxo version | Verbose version report (--json, --short) |
ctxo --help | Print compact help |
Global flags
| Flag | Meaning |
|---|---|
--version, -v, -V | Print core version. Combine with --verbose or --json |
--help, -h | Print the bundled help block |
Related references
- .ctxo/config.yaml reference — project config for index ignore globs and opt-out flags.
- Environment variables —
DEBUG=ctxo:*namespaces,CTXO_RESPONSE_LIMIT, and more.
Debug output
Every subcommand honors DEBUG=ctxo:*. Narrow the namespace (for example DEBUG=ctxo:git,ctxo:storage) when you only want to see one subsystem.
Exit codes
Most commands exit 0 on success and 1 on failure. Two commands have richer semantics:
| Command | Exit | Meaning |
|---|---|---|
ctxo index --check | 0 | Index up to date |
ctxo index --check | 1 | Stale or missing files — run ctxo index |
ctxo doctor | 0 | All checks passed |
ctxo doctor | 1 | One or more checks failed |
ctxo doctor --fix | 2 | Remediation halted before completing |