Commands

CtxCtl has six commands. Every invocation is self-contained: parse, print, exit.

Command	Purpose
outline <file>	Symbol outline with token-savings stats
symbol <file> --name <s>	Original-source slice of one symbol (--compact, --signature, --lines)
read <file> --lines 100-150,200-210	Raw line-range slices (no AST)
deps <file>	Import/module dependency graph (local / external / ignored)
exec <cmd> [--keep <pat>]	Run a command, compress its output
mcp	Serve all commands as MCP tools over stdio (optional adapter)

Global flags

• --json — machine contract: fixed envelope, stable schema version, errors on stdout. Shorthand for --format json.
• --config <path> — explicit config file (highest precedence).
• --no-saved — suppress the saved N% metrics.
• --output <path> — write the full payload to <path> instead of stdout; a wrote <path> confirmation goes to stderr and stdout stays empty.

Config resolution

Config files store only default-behavior preferences — never indexes, state, or sessions. Lookup precedence, high to low:

1. --config <path> (explicit)
2. .ctxctl/config.toml (project-level, discovered walking up like .git)
3. $XDG_CONFIG_HOME/ctxctl/config.toml (XDG global)
4. Built-in defaults

Exit codes

Code	Meaning
0	Success / wrapped command succeeded
1	File or command read failure
2	Unsupported extension / invalid line range
3	Parse failure
4	Symbol not found
non-zero passthrough	exec passes through the child’s exit code
128 + signal	exec when the child was killed by a signal (Unix)

Byte stability

Output bodies never contain timestamps, counters, random values, machine-specific paths, or PIDs. Same input + same config → byte-identical output, which is what keeps provider prompt caches hot after the first token savings. saved% is computed deterministically with the cl100k_base BPE tokenizer — never an external measurement.

The complete behavioral contract — JSON envelopes, folding rules, stream merging, streaming compression — lives in the public CLI contract specification.