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.
Calling ctxo
@ctxo/cli ships as a scoped npm package; the binary name inside the package is ctxo. Three equivalent invocation forms:
| Form | When to use |
|---|---|
ctxo <subcommand> (Recommended) | After npm install -g @ctxo/cli. Works from any directory |
pnpm ctxo <subcommand> / npx ctxo <subcommand> | When @ctxo/cli is in the project's devDependencies (for example after ctxo init). Resolves via node_modules/.bin/ctxo |
npx -y @ctxo/cli <subcommand> | Ad-hoc / CI / one-off, no install needed |
All three forms run the same binary. State always lives in <project>/.ctxo/ regardless of how ctxo is invoked - there is no user-level or system-level config.
Examples below assume ctxo is on your PATH from a global install (or a local node_modules/.bin/ctxo).
Command summary
| Command | Purpose |
|---|---|
ctxo install | Install language plugins (auto-detects if omitted) |
ctxo update | Check the npm registry for newer ctxo releases and apply them |
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 blast-radius | Blast radius for one symbol, JSON to stdout |
ctxo gate --preview | Preview which symbols the safe-edit guard would block |
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 |