Skip to content

Commands

Pavel Erokhin edited this page Nov 21, 2026 · 12 revisions

Русская версия

Every command and option of the ctxray CLI. ctxray help <command> or ctxray <command> --help prints the same list in your language, and this page links to the pages that explain what a command does in depth.

ctxray <command> [subcommand] [options]
Command What it does
inspect Show what each harness loads here and how many tokens it costs
test Run the *.ctxray.ts tests and ctxray's own checks
baseline Write the findings of L1 and L2 to ctxray.baseline.json: later runs fail only on new ones
diff Show how the loadout changed against another revision, origin/master by default, or against a saved report.json
show-report Open the latest report in the browser, live while tests run
harness Install the harnesses ctxray.lock pins, or pin new ones
mcp Serve inspect, test, and diff to an agent over MCP, on stdin and stdout
cache Show or clean the harness cache this machine shares between projects
doctor Check what L4 and up need here: git, the network, the cache, and the pinned harnesses
gen-prompts Write L6 prompts from the descriptions of rules and skills, to a file for review
calibrate Measure how a provider's tokenizer counts against o200k, with your key
init Create ctxray.config.ts and an example test
config Show the config after extends and defaults
help Show help for ctxray or for one command: ctxray help inspect

Global options

Every command takes these:

Option Meaning
--lang <lang> Interface language: en, ru. Localization has the full order ctxray picks it in
--ci Run as in CI on any machine: plain line output, the CI reporters, and a frozen lockfile. ctxray also turns this on by itself when CI, GITLAB_CI, or GITHUB_ACTIONS is set
--plain Print plain lines instead of the live view
--no-color Turn colours off, same as --plain
-h, --help Show help
-v, --version Show the version

Most commands also take --config <file>: the config file to use instead of the one ctxray finds by itself. Without it, ctxray looks in the current folder and then up through its parents to the repository root, so a command works from a subfolder too. ctxray prints plain lines on its own when the output isn't a terminal, in CI, with NO_COLOR set, or with TERM=dumb. --json never goes through the live view.

Exit codes

The numbers stay the same across releases, so scripts and pipelines can branch on them.

Code Name When
0 ok Everything passed
1 failed A test or a check failed
2 usage An unknown command, flag, or argument
3 config The config is missing or invalid
4 environment A harness, the network, or the file system let the run down
5 internal A bug in ctxray. It prints the stack and the link to report it
130 interrupted Ctrl+C or SIGINT

inspect

Shows what each harness loads in this repository: rules, skills, commands, and MCP servers, each with its tokens and the reason it loaded. It only reads files and never launches a harness. Harnesses explains how each harness picks its files.

Option Meaning
--harness <ids> Harnesses, comma-separated, like claude-code,codex. The config's harnesses or the default set otherwise
--cwd <dir> Folder the agent starts in, the current one by default
--files <paths> Files the agent works with, comma-separated: rules for them load too
--json Print JSON instead of text
--ignore-harness-differences Don't warn when the harnesses get different instructions or skills
--config <file> Config file to use

Exit codes: 0, or 2 for an unknown harness or a missing folder. Problems in your files show as warnings and don't fail inspect: use ctxray test for that.

$ ctxray inspect --harness codex --cwd app --files app/src/main/kotlin/payments/Charge.kt

 …/payments · the agent starts in app
 and works with app/src/main/kotlin/payments/Charge.kt

 Codex                                      ≈ 61
   Rules                                    ≈ 24
     AGENTS.md                              ≈ 14  always · cwd
     app/AGENTS.md                          ≈ 10  always · cwd
   Skills                                   ≈ 37
     android-build                          ≈ 11  app/.agents/skills/android-build/SKILL.md
     payouts                                 ≈ 7  .agents/skills/payouts/SKILL.md
     refunds                                ≈ 12  .agents/skills/refunds/SKILL.md
     release                                 ≈ 7  .agents/skills/release/SKILL.md
   MCP servers                       after a run
     github                                       .codex/config.toml
     jira                                         .codex/config.toml
   System prompt and built-in tools  after a run

   ⚠ app/CLAUDE.md  Only Claude Code, Cursor CLI, and OpenCode read this file, and none of them is in the run  other-harness
   ⚠ app/src/main/kotlin/payments/CLAUDE.md  Only Claude Code, Cursor CLI, and OpenCode read this file, and none of them is in the run  other-harness
   and 6 problems elsewhere in the repository

 ≈ marks a local estimate with the o200k_base tokenizer
 The system prompt, built-in tools, and MCP tool schemas get counted once ctxray launches the harness

Codex has no path rules, so Charge.kt adds nothing: both AGENTS.md files load because they sit in the chain from the root to app.

test

Runs the *.ctxray.ts tests and ctxray's own checks (lint, policies, context) across the harnesses and layers you pick. Writing Tests covers the test API, The Loadout Stack the layers, and Reporters and Reports the output.

Option Environment Meaning
--harness <ids> CTXRAY_HARNESS Harnesses, comma-separated
--backend <name> CTXRAY_BACKEND Model backend: mock, replay, real, or a name from the config's backends. mock by default
--layer <layers> CTXRAY_LAYER Layers to run, like L1-L3 or L3,L5
--filter <text> Run only the tests whose name holds this text
-u, --update-snapshots Write new and changed loadout snapshots
--ignore-harness-differences CTXRAY_IGNORE_HARNESS_DIFFERENCES Don't warn when the harnesses get different instructions or skills
--error-on-warnings Fail the run on any L1 warning, as on an error
--frozen Fail when ctxray.lock doesn't match the config. On by itself in CI and with --ci
--no-install Don't install a pinned harness the cache lacks, fail instead
--record With --backend real, keep the model's answers as cassettes for --backend replay
--base <ref> The revision to compare with, like origin/master. The report gets a diff of the loadout
--reporter <names> CTXRAY_REPORTER Reporters, comma-separated: console, html, json, junit, allure, markdown
--report-lang <langs> CTXRAY_REPORT_LANG Languages of the HTML report, comma-separated, or all
--report-dir <dir> Where reports go, .ctxray/report by default
--concurrency <count> CTXRAY_CONCURRENCY Harness sessions an L6 or L7 test runs at once, 1 by default
--budget <usd> CTXRAY_BUDGET_USD US dollars a run with --backend real may spend
-w, --watch Run again after each change of the project's files. Press q to stop
--config <file> Config file to use

A harness the run needs but this machine doesn't have is skipped with the ctxray harness add that adds it, unless --layer named the layers that need it: then it fails. A flag beats its environment variable, which beats the config. Exit codes: 0 when everything passed, 1 when a test or a check failed, 2 for a bad option value (an unknown reporter, report language, layer, or --base revision, a negative budget), 4 for --backend real while ctxray is offline. With --watch, the code is the last run's.

ctxray test --layer L1-L3                        # files only, no harness launched
ctxray test --harness codex --filter payments
ctxray test --backend replay --reporter console,html

Harnesses explains --frozen and --no-install, CI Integration how they behave on a runner.

baseline

Runs L1 and L2 as they stand and writes their findings to ctxray.baseline.json at the project root. Commit it: from then on ctxray test drops the known findings and fails only on new ones. That lets you turn ctxray on in an old repository without fixing everything first.

Option Meaning
--harness <ids> Harnesses, comma-separated
--config <file> Config file to use

The file has no line numbers, so a finding stays known when you edit above it. Exit code 0. Policies has more on L2.

diff

Compares what L3 predicts at the project root on another revision with the working tree. It shows rules by path, listed skills by name, and MCP servers and commands by their presence.

With --file, it compares with a report.json instead: one a past ctxray test wrote here, or one you downloaded from a CI run. Every report from 0.1.1 on keeps the loadout L3 predicted at the root for each harness of the run, and diff takes those harnesses unless you name others. A report of 0.1.0 holds no loadout, so diff says so and exits with 2.

Besides the terminal view, diff writes diff.json for scripts and diff.html for people into the report folder, next to a test run's report.json.

Option Meaning
--base <ref> The revision to compare with, origin/master by default
--file <report.json> A report.json of a past run, here or from CI, to compare with instead of a revision
--harness <ids> Harnesses, comma-separated
--json Print JSON instead of text
--report-dir <dir> Where diff.json and diff.html go, .ctxray/report by default
--config <file> Config file to use

Exit codes: 0, or 2 when git knows no such revision, the file is missing or holds no loadout, or both --base and --file are given.

$ ctxray diff --base HEAD --harness claude-code,codex

 Against HEAD (399c8b5e), as L3 predicts at the project root

 Claude Code  ≈ 147 → ≈ 169 tokens of files  +22
   ~ CLAUDE.md  rules +16
   + .claude/rules/states.md  rules +25
   + sentry  mcp
   − changelog  commands

 Codex  ≈ 40 → ≈ 40 tokens of files  ±0
   Nothing changed
ctxray diff --file ci-report/report.json   # against the report a CI run left as an artifact

+ marks a new piece, − a removed one, ~ a changed one. A command or an MCP server has no tokens of its own, so its line shows no number. ctxray test --base <ref> puts the same comparison into the report.

show-report

Serves the latest report from the report folder at http://127.0.0.1:<port>/, on your machine only. When a test run writes a new report.json, every open page reloads. Stop it with Ctrl+C.

Option Meaning
--report-dir <dir> Where reports go, .ctxray/report by default
--port <port> Port to listen on, a free one by default
--open Open the page in the browser
--config <file> Config file to use

Exit codes: 0, or 2 when the folder has no report.json yet. Reporters and Reports has the details.

harness

Pins harness versions in ctxray.lock and installs them into ctxray's cache. Harnesses explains the lockfile, the cache, and source: "system".

Subcommand What it does
add <id>[@range] … Pin harnesses in ctxray.lock: add codex@0.169.x claude-code
install Install every harness ctxray.lock pins, for this machine
list Show the pinned harnesses and whether this machine has them
pack Pack the pinned builds into one archive for install --from
remove <id> … Unpin harnesses from ctxray.lock: remove codex
upgrade <id> … Move a pinned harness to its newest version and show how its loadout changes
Option Subcommand Meaning
--only <ids> install Only these harnesses, comma-separated
--frozen install Fail when ctxray.lock doesn't match the config. On by itself in CI and with --ci
--from <archive> install Install from an archive ctxray harness pack wrote, without a registry
-o, --output <file> pack File to write, ctxray-harnesses.tar by default
--platform <keys|all> pack Platforms to pack, like darwin-arm64,linux-x64-glibc, or all. This machine's by default
--dry-run upgrade Show the upgrade without writing ctxray.lock
--config <file> all Config file to use

Exit codes: 0, 2 for a missing harness name or an unknown harness, 4 when a download, the registry, or the lockfile fails. install also exits with 4 when a harness stays missing, or when --frozen finds a mismatch.

remove edits only ctxray.lock. When your config still names the harness, it says so: remove it there too, or --frozen fails on the mismatch. The builds stay in the cache until ctxray cache prune or ctxray cache clear.

ctxray harness add claude-code codex@0.169.x
ctxray harness install --only codex
ctxray harness pack --platform linux-x64-glibc,linux-x64-musl -o harnesses.tar
ctxray harness install --from harnesses.tar
ctxray harness upgrade claude-code --dry-run
ctxray harness remove opencode
$ ctxray harness list

 claude-code  2.1.325                      in the cache
 codex        0.169.0                      in the cache
 cursor-cli   2026.11.13-eacade1 (latest)  in the cache
 gemini-cli   0.68.0                       in the cache
 opencode     1.19.5                       in the cache

 ctxray.lock

mcp

Runs an MCP server on stdin and stdout with three tools: inspect, run (ctxray test), and diff. An agent can then check its own change for context bloat. The Claude Code Plugin starts it for you.

Connect it once with ctxray mcp add <agent>, and the agent starts it from then on. Run in a terminal, ctxray mcp prints these commands instead of waiting.

Subcommand What it does
serve Serve the tools on stdin and stdout. ctxray mcp alone does the same
add <agent> Connect ctxray to claude-code, codex, gemini-cli, opencode, or cursor-cli
Agent What ctxray mcp add does With --project
Claude Code Runs claude mcp add --scope user ctxray -- ctxray mcp Writes .mcp.json
Codex Runs codex mcp add ctxray -- ctxray mcp Writes .codex/config.toml
Gemini CLI Runs gemini mcp add --scope user ctxray ctxray mcp Writes .gemini/settings.json
OpenCode Writes ~/.config/opencode/opencode.json ($XDG_CONFIG_HOME when set) Writes opencode.json
Cursor CLI Writes ~/.cursor/mcp.json Writes .cursor/mcp.json

ctxray adds its own entry and keeps everything else in the file. When the config already has a server named ctxray, nothing changes, so running it twice is safe. Claude Code, Codex, and Gemini CLI must be on PATH for the global config: without them add says so, and --project still works. ctxray leaves a JSON file with comments as it is and prints the entry to add by hand, since a rewrite would lose them.

Option Meaning
--project With add: write the project's config instead of yours
--harness <ids> Harnesses a tool call looks at when it names none, like claude-code

Exit codes for add: 0 when ctxray is connected or already was, 2 for an unknown agent, 4 when the agent isn't on PATH, its mcp add fails, or the file has comments.

ctxray mcp add claude-code
ctxray mcp add cursor-cli --project
ctxray mcp --harness claude-code

cache

Shows or cleans the harness cache that every project on this machine shares. Harnesses explains where it lives and how layers work.

Subcommand What it does
dir Print the cache folder, for CI cache steps
ls List the harness builds in the cache
prune Remove builds unused for a while. The ones ctxray.lock pins stay
clear Remove every harness build from the cache, pinned ones too
Option Meaning
--older-than <days> Prune builds unused for this many days, 30 by default
--all Prune every build ctxray.lock doesn't pin, however recent
-y, --yes Clear for real. Without it, clear lists what would go and exits with 2
--config <file> Config file to use

Exit codes: 0, or 2 for a bad number of days and for clear without --yes. Read-only cache layers stay as they are: ctxray never deletes from them.

ctxray cache dir
ctxray cache prune --older-than 7
ctxray cache clear --yes

doctor

Checks what L4 and up need on this machine and prints each finding as ok (✓), info (·), a warning, or an error. Errors exit with 4, everything else with 0. Without flags it only reads, and never installs or changes anything.

ctxray doctor --fix first fixes what's safe: it creates the cache folder and installs the harnesses ctxray.lock pins that this machine lacks. Then it checks everything again and lists under “Fixed by --fix” what it did and what failed. --fix never touches git, the network, proxies, CA certificates, Node, or keys: the findings above say what to do about them.

Option Meaning
--fix Fix what's safe: create the cache folder and install the harnesses ctxray.lock pins
--config <file> Config file to use
Group Checks
System ctxray's version and platform key. git on PATH (an error without it: L4 and up copy the project with git). Node.js on PATH (MCP servers on Node need it). Settings an administrator put in /Library/Application Support/ClaudeCode, /etc/claude-code, /etc/codex, or their Windows twins, which ctxray can't isolate. On macOS, sandbox-exec. Elsewhere, a reminder to run L4 and up in a container
Network The proxy, with its credentials hidden. HTTP_PROXY set without HTTPS_PROXY. NO_PROXY entries that Bun reads differently from curl (*.corp.com, CIDR ranges). Each CA file exists and holds PEM certificates. The system certificate store. The npm registry, the CA certificates from .npmrc, and whether the registry answers (skipped offline)
Harnesses The cache folder, its builds and size, and whether it's writable. Read-only cache layers. The lockfile and its mismatches with the config. For each pinned harness: installed or not, a build for this platform, the runtime it needs (node for Gemini CLI), and for source: "system" whether it's on PATH with the locked version
$ ctxray doctor

 System
   · ctxray 0.1.0 on darwin-arm64
   ✓ git 2.54.0
   ✓ Node.js 26.13.1
   ✓ sandbox-exec runs the harnesses in a sandbox

 Network
   · No proxy: requests go out directly
   ✓ npm registry https://registry.npmjs.org/
   ✓ The registry answers (200)

 Harnesses
   ✓ Cache ~/Library/Caches/ctxray: 6 builds, 1,741 MB
   ✓ Lockfile ctxray.lock
   ✓ claude-code 2.1.325 installed
   ✓ codex 0.169.0 installed
   ✓ cursor-cli 2026.11.13-eacade1 installed
   ✓ gemini-cli 0.68.0 installed
   ✓ opencode 1.19.5 installed

 Everything L4 and up need is in place

Enterprise explains the proxy, CA, and registry settings doctor checks.

gen-prompts

Asks a model to write prompts for L6 tests from the description of each skill and each rule the model picks by description: some that should pick it and some borderline ones that shouldn't. It writes them to a JSON file for you to review, and a test reads it with corpus() (Writing Tests).

Option Meaning
--from-descriptions Write them from the description of each rule and skill the model picks by description. Required
--out <file> The JSON file to write, for corpus() in a test. Required
--model <id> The model that writes them, claude-opus-5-5 by default: not one under test
--count <n> Prompts of each kind per rule or skill, 5 by default
--harness <ids> Harnesses, comma-separated
--force Overwrite files that already exist
--config <file> Config file to use

It calls the model through your upstream and key, so it doesn't run offline. ctxray warns when a harness under test runs the same model, because a model grading its own prompts proves little. Exit codes: 0, 1 when some rule or skill failed, 2 for missing options or an existing file without --force, 4 offline.

ctxray gen-prompts --from-descriptions --out prompts/skills.json --count 8

calibrate

Measures how a provider's tokenizer counts compared with o200k, per class of text (prose, code, JSON, non-Latin, metadata), using the provider's count endpoint and your key. ctxray ships a measured Anthropic calibration, so you need this only to check it or to measure another model.

Option Meaning
--provider <anthropic|openai|google> Model provider. Required
--model <id> Model to count with. Required
--out <file> Write the factors to this file instead of printing them
--config <file> Config file to use

It sends about 40 requests, so it doesn't run offline either. Exit codes: 0, 2 for a missing provider or model, 4 offline or when the provider's count request fails.

ctxray calibrate --provider anthropic --model claude-sonnet-5-5 --out anthropic.json

init

Creates ctxray.config.ts with Claude Code and Codex, and ctxray/loadout.ctxray.ts, a test that checks each harness loads its root rules file. It adds .ctxray/ to an existing .gitignore. Getting Started walks through the result.

Option Meaning
--force Overwrite files that already exist

config

Prints the config after extends and defaults, with secrets redacted, by the built-in patterns and your own redact.patterns, and the files it came from. Use it when an inherited setting doesn't do what you expect. Configuration lists every key.

Option Meaning
--config <file> Config file to use

Clone this wiki locally