Command reference

Every command accepts the same global flags listed below. Paths can be project-relative or absolute. This page is generated to match the real ctx <command> --help output — run that yourself to confirm the exact behavior on your build.

Global flags

-R, --root <DIR>	Project root (defaults to the nearest directory containing .ctx)
-j, --json	Emit machine-readable JSON instead of human text
-q, --quiet	Suppress non-essential output
-v, --verbose	Enable verbose diagnostics on stderr
--no-color	Disable ANSI colors
-h, --help	Print help
-V, --version	Print version

`ctx init`

Create .ctx, write a default config, and index the project.

ctx init [OPTIONS] [PATH]

ctx init            # index the current directory
ctx init src/       # index a specific directory
ctx init --force    # rebuild index + config even if they exist

[PATH]	Directory to initialize (default: current directory)
--force	Recreate the index and config even if they exist

`ctx search`

Search the graph for symbols or files.

ctx search [OPTIONS] <QUERY>

ctx search "rate limit"         # symbols whose name matches
ctx search --files "auth"        # file paths instead of symbols
ctx search --kind struct "user"  # restrict to a symbol kind
ctx search "token" --limit 20    # cap the number of results

Kind aliases: fn → function, const → constant, alias → type. An invalid kind is rejected.

<QUERY>	Case-insensitive name query
--kind <KIND>	Restrict to a symbol kind (function, method, class, interface, type, enum, constant, variable, struct, trait, module, field, constructor, impl — plus aliases fn, const, alias)
--files	Search file paths instead of symbols
--limit <LIMIT>	Maximum number of results [default: 50]

`ctx symbol`

Details about a symbol: definition, references, dependencies.

ctx symbol <NAME>

ctx symbol UserService.updateUser

Accepts a bare name (updateUser) or a qualified name (UserService.updateUser). References are symbol-level, not just file-level, for parsed languages.

`ctx deps`

Show what a file imports and what imports it.

ctx deps [OPTIONS] <PATH>

ctx deps src/models/user.py       # both directions
ctx deps --outgoing src/main.rs    # imports only
ctx deps --incoming src/api.rs     # dependents only

--outgoing	Only show outgoing dependencies
--incoming	Only show incoming dependents

`ctx impact`

Analyze the impact of changing a symbol or file.

ctx impact [OPTIONS] <TARGET>

ctx impact UserService.updateUser --depth 5
ctx impact src/worker.rs

Traversal is a cycle-safe breadth-first search over the inverted graph, grouped into direct, indirect, test-file, and unknown buckets. When a name exists as both a production symbol and a test double, the production definition is preferred.

<TARGET>	Symbol name or file path to change
--depth <DEPTH>	How deep to traverse dependent graphs [default: 3]

`ctx context`

Build a relevance-ranked context package for a task.

ctx context [OPTIONS] <TASK>

ctx context "add Google OAuth"
ctx context "fix the payment retry bug" --include-bodies
ctx context "add rate limiting" --max-tokens 12000
ctx context "refactor the CLI" --no-git

CautionRanking is name-based, not semantic. It scores symbol names, paths, hub centrality, recency, and git activity. Words in the task that do not appear in any symbol or path will not match anything.

<TASK>	Natural-language description of the task
--include-bodies	Include full function/type bodies in the suggested context
--max-tokens <N>	Token budget for the suggested context (overrides config; default 12000)
--no-git	Ignore working-tree git changes when ranking files

`ctx changed`

Show symbols changed in the working tree or between refs.

ctx changed [OPTIONS]

ctx changed               # working tree vs HEAD
ctx changed --ref main     # diff against main
ctx changed --sync         # update the graph before comparing

--ref <REF>	Git ref to diff against (default: working tree vs HEAD)
--sync	Update the graph with current files before comparing

`ctx diff`

Semantic diff of symbols between two git refs.

ctx diff [OPTIONS] [BASE] [HEAD]

ctx diff HEAD~3 HEAD
ctx diff main

The base defaults to the merge-base with HEAD, so ctx diff main shows everything your branch changed, not everything main did since the fork. Reports Added, Removed, and Modified symbol-level entries — not just file status.

[BASE]	Base ref (default: HEAD; a single base is resolved to its merge-base with HEAD)
[HEAD]	Head ref (default: working tree when omitted)

`ctx skeleton`

Show a body-less structural skeleton of a source file.

ctx skeleton [OPTIONS] <PATH>

ctx skeleton src/models.py
ctx skeleton src/models.py --stats

Bodies are elided but signatures, types, and exports are preserved. Malformed code yields a bounded declaration-only skeleton and never leaks body lines.

<PATH>	Path to the file (project-relative or absolute)
--stats	Include sizes and symbol counts

`ctx mcp`

Run the Model Context Protocol server over stdio.

ctx mcp [OPTIONS]

ctx mcp -R /path/to/project

`ctx doctor`

Inspect the project and report the health of the ctx index.

ctx doctor [OPTIONS]

ctx doctor
ctx doctor --json

Reports stale, missing, or corrupt indexes, invalid config, and other problems without crashing. Exits non-zero when the index is unhealthy — useful in CI.

`ctx stats`

Show index statistics (files, symbols, dependencies, db size).

ctx stats [OPTIONS]

ctx stats
ctx stats --json

`ctx version`

Print version information.

ctx version [OPTIONS]

ctx version
ctx version --json

`ctx schema`

Print the SQLite graph schema.

ctx schema [OPTIONS]

ctx schema

`ctx benchmark`

Re-run an index pass and print incremental timing.

ctx benchmark [OPTIONS]

ctx benchmark

`ctx watch`

Watch the project and keep the graph in sync.

ctx watch [OPTIONS]

ctx watch

Re-indexes changed files as they are edited. Debounce and on/off are controlled by the [watch] config section.

Running ctx with no arguments prints a quick overview of the tool.