Skip to content

Commands RU

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

English version

Все команды и параметры CLI ctxray. ctxray help <команда> или ctxray <команда> --help печатает тот же список на вашем языке, а эта страница ссылается на страницы, где подробно разобрано, что делает команда.

ctxray <команда> [подкоманда] [параметры]
Команда Что делает
inspect Показать, что загружает каждый ИИ-харнесс и сколько это стоит в токенах
test Запустить тесты *.ctxray.ts и собственные проверки ctxray
baseline Записать находки L1 и L2 в ctxray.baseline.json: дальше прогон падает только на новых
diff Показать, как loadout изменился относительно другой ревизии, по умолчанию origin/master, или сохранённого report.json
show-report Открыть последний отчёт в браузере, с обновлением во время прогона
harness Поставить харнессы из ctxray.lock или закрепить новые
mcp Отдать inspect, test и diff агенту по MCP через stdin и stdout
cache Показать или почистить кеш харнессов, общий для всех проектов на машине
doctor Проверить, что нужно для L4 и выше: git, сеть, кеш и закреплённые харнессы
gen-prompts Написать промпты для L6 по описаниям правил и скиллов, в файл для ревью
calibrate Измерить, как токенайзер провайдера считает относительно o200k, вашим ключом
init Создать ctxray.config.ts и пример теста
config Показать итоговый конфиг с учётом extends и значений по умолчанию
help Показать справку по ctxray или по одной команде: ctxray help inspect

Общие параметры

Их принимает каждая команда:

Параметр Значение
--lang <lang> Язык интерфейса: en, ru. Полный порядок, в котором ctxray его выбирает, — на странице Localization
--ci Работать как в CI на любой машине: построчный вывод, репортеры CI и замороженный lockfile. ctxray включает это и сам, если задана CI, GITLAB_CI или GITHUB_ACTIONS
--plain Печатать простые строки вместо живого вывода
--no-color Выключить цвета, то же, что --plain
-h, --help Показать справку
-v, --version Показать версию

Большинство команд принимает и --config <file>: файл конфига вместо того, который ctxray находит сам. Без флага ctxray ищет конфиг в текущей папке, а затем в родительских вплоть до корня репозитория, поэтому команды работают и из подпапки. Простые строки ctxray печатает и сам, когда вывод идёт не в терминал, в CI, при заданной NO_COLOR или при TERM=dumb. --json никогда не идёт через живой вывод.

Коды выхода

Номера не меняются от версии к версии, так что скрипты и пайплайны могут на них опираться.

Код Имя Когда
0 ok Всё прошло
1 failed Упал тест или проверка
2 usage Неизвестная команда, флаг или аргумент
3 config Конфига нет или он неверный
4 environment Подвели харнесс, сеть или файловая система
5 internal Ошибка в самом ctxray. Он печатает стек и ссылку, куда о ней сообщить
130 interrupted Ctrl+C или SIGINT

inspect

Показывает, что загружает каждый харнесс в этом репозитории: правила, скиллы, команды и MCP-серверы, у каждого — токены и причина загрузки. Команда только читает файлы и никогда не запускает харнесс. Как каждый харнесс выбирает файлы, описано на странице Harnesses.

Параметр Значение
--harness <ids> ИИ-харнессы через запятую, например claude-code,codex. Иначе — харнессы из конфига или набор по умолчанию
--cwd <dir> Папка, в которой стартует агент, по умолчанию текущая
--files <paths> Файлы, с которыми работает агент, через запятую: правила для них тоже загрузятся
--json Вывести JSON вместо текста
--ignore-harness-differences Не предупреждать, если ИИ-харнессы получают разные инструкции или скиллы
--config <file> Файл конфига

Коды выхода: 0, или 2 для неизвестного харнесса или несуществующей папки. Проблемы в ваших файлах показываются предупреждениями и inspect не валят: для этого есть ctxray test.

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

 …/payments · агент стартует в app
 и работает с app/src/main/kotlin/payments/Charge.kt

 Codex                                                 ≈ 61
   Правила                                             ≈ 24
     AGENTS.md                                         ≈ 14  always · cwd
     app/AGENTS.md                                     ≈ 10  always · cwd
   Скиллы                                              ≈ 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-серверы                                после запуска
     github                                                  .codex/config.toml
     jira                                                    .codex/config.toml
   Системный промпт и встроенные инструменты  после запуска

   ⚠ app/CLAUDE.md  Этот файл читают только Claude Code, Cursor CLI и OpenCode, а в прогоне нет ни одного из них  other-harness
   ⚠ app/src/main/kotlin/payments/CLAUDE.md  Этот файл читают только Claude Code, Cursor CLI и OpenCode, а в прогоне нет ни одного из них  other-harness
   и ещё 6 проблем в других частях репозитория

 ≈ — локальная оценка токенайзером o200k_base
 Системный промпт, встроенные инструменты и схемы MCP-инструментов ctxray посчитает, когда запустит ИИ-харнесс

У Codex нет правил по путям, поэтому Charge.kt ничего не добавляет: оба AGENTS.md загружаются, потому что лежат в цепочке от корня до app.

test

Запускает тесты *.ctxray.ts и собственные проверки ctxray (lint, политики, контекст) на выбранных харнессах и слоях. API тестов описан на странице Writing Tests, слои — на The Loadout Stack, вывод — на Reporters and Reports.

Параметр Переменная окружения Значение
--harness <ids> CTXRAY_HARNESS ИИ-харнессы через запятую
--backend <name> CTXRAY_BACKEND Бэкенд модели: mock, replay, real или имя из backends в конфиге. По умолчанию mock
--layer <layers> CTXRAY_LAYER Слои для прогона, например L1-L3 или L3,L5
--filter <text> Запустить только тесты, в имени которых есть этот текст
-u, --update-snapshots Записать новые и изменившиеся снапшоты loadout
--ignore-harness-differences CTXRAY_IGNORE_HARNESS_DIFFERENCES Не предупреждать, если ИИ-харнессы получают разные инструкции или скиллы
--error-on-warnings Считать любое предупреждение L1 ошибкой
--frozen Падать, если ctxray.lock не совпадает с конфигом. Включается сам в CI и с --ci
--no-install Не ставить закреплённый харнесс, которого нет в кеше, а падать
--record С --backend real сохранить ответы модели кассетами для --backend replay
--base <ref> Ревизия для сравнения, например origin/master. В отчёт попадёт разница loadout
--reporter <names> CTXRAY_REPORTER Репортеры через запятую: console, html, json, junit, allure, markdown
--report-lang <langs> CTXRAY_REPORT_LANG Языки HTML-отчёта через запятую или all
--report-dir <dir> Куда класть отчёты, по умолчанию .ctxray/report
--concurrency <число> CTXRAY_CONCURRENCY Сколько сессий харнесса тест L6 или L7 запускает одновременно, по умолчанию одну
--budget <usd> CTXRAY_BUDGET_USD Сколько долларов может потратить прогон с --backend real
-w, --watch Запускать заново после каждого изменения файлов проекта. Остановить — клавишей q
--config <file> Файл конфига

Харнесс, которого нет на машине, пропускается с подсказкой ctxray harness add, если только --layer не назвал уровни, которым он нужен: тогда он падает. Флаг сильнее переменной окружения, а она сильнее конфига. Коды выхода: 0, если всё прошло, 1, если упал тест или проверка, 2 для неверного значения параметра (неизвестный репортер, язык отчёта, слой или ревизия --base, отрицательный бюджет), 4 для --backend real, когда ctxray работает офлайн. С --watch код — от последнего прогона.

ctxray test --layer L1-L3                        # только файлы, харнесс не запускается
ctxray test --harness codex --filter payments
ctxray test --backend replay --reporter console,html

Про --frozen и --no-install рассказано на странице Harnesses, про их поведение на раннере — на CI Integration.

baseline

Прогоняет L1 и L2 как есть и записывает их находки в ctxray.baseline.json в корне проекта. Закоммитьте файл: дальше ctxray test отбрасывает известные находки и падает только на новых. Так ctxray можно включить в старом репозитории, не исправляя всё сразу.

Параметр Значение
--harness <ids> ИИ-харнессы через запятую
--config <file> Файл конфига

В файле нет номеров строк, поэтому находка остаётся известной, даже если вы правите текст выше неё. Код выхода 0. Подробнее про L2 — на странице Policies.

diff

Сравнивает, что L3 предсказывает в корне проекта на другой ревизии и в рабочем дереве. Показывает правила по пути, перечисленные скиллы по имени, MCP-серверы и команды — по факту наличия.

С --file сравнивает с report.json: тем, что записал прошлый ctxray test здесь, или тем, что вы скачали из прогона CI. Каждый отчёт начиная с 0.1.1 хранит loadout, который L3 предсказал в корне для каждого харнесса прогона, и diff берёт эти харнессы, если вы не назвали другие. В отчёте 0.1.0 loadout нет: diff так и скажет и выйдет с кодом 2.

Кроме вывода в терминал diff пишет diff.json для скриптов и diff.html для людей в папку отчётов, рядом с report.json прогона тестов.

Параметр Значение
--base <ref> Ревизия для сравнения, по умолчанию origin/master
--file <report.json> report.json прошлого прогона, локального или из CI, с которым сравнить вместо ревизии
--harness <ids> ИИ-харнессы через запятую
--json Вывести JSON вместо текста
--report-dir <dir> Куда писать diff.json и diff.html, по умолчанию .ctxray/report
--config <file> Файл конфига

Коды выхода: 0, или 2, если git не знает такой ревизии, файла нет или в нём нет loadout, или если заданы и --base, и --file.

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

 Относительно HEAD (399c8b5e), как предсказывает L3 в корне проекта

 Claude Code  ≈ 147 → ≈ 169 токенов файлов  +22
   ~ CLAUDE.md  rules +16
   + .claude/rules/states.md  rules +25
   + sentry  mcp
   − changelog  commands

 Codex  ≈ 40 → ≈ 40 токенов файлов  ±0
   Ничего не изменилось
ctxray diff --file ci-report/report.json   # относительно отчёта, который прогон CI оставил артефактом

+ — новая часть, − — удалённая, ~ — изменённая. У команды и MCP-сервера нет своих токенов, поэтому в их строке нет числа. ctxray test --base <ref> кладёт то же сравнение в отчёт.

show-report

Отдаёт последний отчёт из папки отчётов по адресу http://127.0.0.1:<port>/, только на вашей машине. Когда прогон тестов пишет новый report.json, каждая открытая страница обновляется. Остановить — Ctrl+C.

Параметр Значение
--report-dir <dir> Куда класть отчёты, по умолчанию .ctxray/report
--port <port> Порт, по умолчанию свободный
--open Открыть страницу в браузере
--config <file> Файл конфига

Коды выхода: 0, или 2, если в папке ещё нет report.json. Подробности — на странице Reporters and Reports.

harness

Закрепляет версии харнессов в ctxray.lock и ставит их в кеш ctxray. Lockfile, кеш и source: "system" описаны на странице Harnesses.

Подкоманда Что делает
add <id>[@range] … Закрепить харнессы в ctxray.lock: add codex@0.169.x claude-code
install Поставить на эту машину все харнессы из ctxray.lock
list Показать закреплённые харнессы и есть ли они на этой машине
pack Собрать закреплённые сборки в один архив для install --from
remove <id> … Убрать харнессы из ctxray.lock: remove codex
upgrade <id> … Обновить закреплённый харнесс до новой версии и показать, как меняется его loadout
Параметр Подкоманда Значение
--only <ids> install Только эти харнессы, через запятую
--frozen install Падать, если ctxray.lock не совпадает с конфигом. Включается сам в CI и с --ci
--from <archive> install Поставить из архива ctxray harness pack, без registry
-o, --output <file> pack Файл, куда писать, по умолчанию ctxray-harnesses.tar
--platform <keys|all> pack Платформы для архива, например darwin-arm64,linux-x64-glibc, или all. По умолчанию — платформа этой машины
--dry-run upgrade Показать обновление, не записывая ctxray.lock
--config <file> все Файл конфига

Коды выхода: 0, 2, если не назван харнесс или он неизвестен, 4, если подвели загрузка, registry или lockfile. install выходит с 4 и тогда, когда харнесс так и не нашёлся, или когда --frozen нашёл расхождение.

remove правит только ctxray.lock. Если конфиг всё ещё называет харнесс, команда об этом скажет: уберите его и там, иначе --frozen упадёт на расхождении. Сборки остаются в кеше до ctxray cache prune или 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                      в кеше
 codex        0.169.0                      в кеше
 cursor-cli   2026.11.13-eacade1 (latest)  в кеше
 gemini-cli   0.68.0                       в кеше
 opencode     1.19.5                       в кеше

 ctxray.lock

mcp

Запускает MCP-сервер на stdin и stdout с тремя инструментами: inspect, run (ctxray test) и diff. Так агент может сам проверить, не раздувает ли его изменение контекст. Claude Code Plugin запускает его за вас.

Подключите его один раз через ctxray mcp add <агент>, дальше агент запускает его сам. В терминале ctxray mcp не ждёт, а печатает эти команды.

Подкоманда Что делает
serve Отдавать инструменты через stdin и stdout. Просто ctxray mcp делает то же
add <агент> Подключить ctxray к claude-code, codex, gemini-cli, opencode или cursor-cli
Агент Что делает ctxray mcp add С --project
Claude Code Запускает claude mcp add --scope user ctxray -- ctxray mcp Пишет .mcp.json
Codex Запускает codex mcp add ctxray -- ctxray mcp Пишет .codex/config.toml
Gemini CLI Запускает gemini mcp add --scope user ctxray ctxray mcp Пишет .gemini/settings.json
OpenCode Пишет ~/.config/opencode/opencode.json ($XDG_CONFIG_HOME, если задана) Пишет opencode.json
Cursor CLI Пишет ~/.cursor/mcp.json Пишет .cursor/mcp.json

ctxray добавляет только свою запись, остальное в файле остаётся как было. Если в конфиге уже есть сервер с именем ctxray, ничего не меняется, так что повторный запуск безопасен. Для глобального конфига Claude Code, Codex и Gemini CLI должны быть в PATH: без них add об этом скажет, а --project работает и так. JSON-файл с комментариями ctxray не трогает и печатает запись, которую нужно добавить вручную: перезапись потеряла бы комментарии.

Параметр Значение
--project С add: записать в конфиг проекта, а не в ваш
--harness <ids> Харнессы, на которые смотрит вызов инструмента, если сам их не назвал, например claude-code

Коды выхода add: 0, если ctxray подключён сейчас или был подключён раньше, 2 для неизвестного агента, 4, если агента нет в PATH, его mcp add не сработал или в файле есть комментарии.

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

cache

Показывает или чистит кеш харнессов, общий для всех проектов на машине. Где он лежит и как работают слои, рассказано на странице Harnesses.

Подкоманда Что делает
dir Напечатать папку кеша, для шагов кеширования в CI
ls Показать сборки харнессов в кеше
prune Удалить сборки, которыми давно не пользовались. Закреплённые в ctxray.lock остаются
clear Удалить из кеша все сборки харнессов, в том числе закреплённые
Параметр Значение
--older-than <days> Удалять сборки, которыми не пользовались столько дней, по умолчанию 30
--all Удалить все сборки, которых нет в ctxray.lock, даже свежие
-y, --yes Удалить по-настоящему. Без него clear показывает, что уйдёт, и выходит с 2
--config <file> Файл конфига

Коды выхода: 0, или 2 для неверного числа дней и для clear без --yes. Слои кеша только для чтения ctxray не трогает.

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

doctor

Проверяет, что нужно для L4 и выше на этой машине, и печатает каждую находку как ok (✓), информацию (·), предупреждение или ошибку. С ошибками код выхода 4, иначе 0. Без флагов команда только читает: ничего не ставит и не меняет.

ctxray doctor --fix сначала чинит безопасное: создаёт папку кеша и ставит харнессы из ctxray.lock, которых на машине нет. Потом проверяет всё заново и в разделе «Исправлено через --fix» перечисляет, что сделал и что не получилось. git, сеть, прокси, CA-сертификаты, Node и ключи --fix не трогает: находки выше говорят, что с ними сделать.

Параметр Значение
--fix Исправить безопасное: создать папку кеша и поставить харнессы из ctxray.lock
--config <file> Файл конфига
Группа Проверки
Система Версия ctxray и ключ платформы. git в PATH (без него ошибка: L4 и выше копируют проект через git). Node.js в PATH (он нужен MCP-серверам на Node). Настройки, которые администратор положил в /Library/Application Support/ClaudeCode, /etc/claude-code, /etc/codex или их аналоги на Windows: их ctxray изолировать не может. На macOS — sandbox-exec. На других системах — напоминание запускать L4 и выше в контейнере
Сеть Прокси со скрытыми учётными данными. HTTP_PROXY без HTTPS_PROXY. Записи NO_PROXY, которые Bun понимает не так, как curl (*.corp.com, диапазоны CIDR). Существует ли каждый файл CA и есть ли в нём сертификаты PEM. Системное хранилище сертификатов. npm registry, сертификаты CA из .npmrc и отвечает ли registry (без сети проверка пропускается)
Харнессы Папка кеша, её сборки и размер, можно ли в неё писать. Слои кеша только для чтения. Lockfile и его расхождения с конфигом. Для каждого закреплённого харнесса: установлен ли он, есть ли сборка для этой платформы, есть ли нужная ему среда (node для Gemini CLI), а для source: "system" — есть ли он в PATH и та ли у него версия
$ ctxray doctor

 Система
   · ctxray 0.1.0 на darwin-arm64
   ✓ git 2.54.0
   ✓ Node.js 26.13.1
   ✓ sandbox-exec запускает харнессы в песочнице

 Сеть
   · Прокси нет: запросы идут напрямую
   ✓ npm registry https://registry.npmjs.org/
   ✓ Registry отвечает (200)

 Харнессы
   ✓ Кеш ~/Library/Caches/ctxray: 6 сборок, 1 741 МБ
   ✓ Lockfile ctxray.lock
   ✓ claude-code 2.1.325 установлен
   ✓ codex 0.169.0 установлен
   ✓ cursor-cli 2026.11.13-eacade1 установлен
   ✓ gemini-cli 0.68.0 установлен
   ✓ opencode 1.19.5 установлен

 Всё, что нужно для L4 и выше, на месте

Настройки прокси, CA и registry, которые проверяет doctor, описаны на странице Enterprise.

gen-prompts

Просит модель написать промпты для тестов L6 по описанию каждого скилла и каждого правила, которое модель выбирает по описанию: такие, что должны его выбрать, и пограничные, что не должны. Результат ложится в JSON-файл для вашего ревью, а тест читает его через corpus() (Writing Tests).

Параметр Значение
--from-descriptions Писать по описанию каждого правила и скилла, которые модель выбирает по описанию. Обязателен
--out <file> JSON-файл, куда писать, для corpus() в тесте. Обязателен
--model <id> Модель, которая пишет, по умолчанию claude-opus-5-5: не та, что под тестом
--count <n> Сколько промптов каждого вида на правило или скилл, по умолчанию 5
--harness <ids> ИИ-харнессы через запятую
--force Перезаписать уже существующие файлы
--config <file> Файл конфига

Модель вызывается через ваш upstream и ваш ключ, поэтому без сети команда не работает. ctxray предупреждает, если харнесс под тестом работает на той же модели: модель, которая проверяет собственные промпты, мало что доказывает. Коды выхода: 0, 1, если для какого-то правила или скилла не получилось, 2 при нехватке параметров или существующем файле без --force, 4 в режиме офлайн.

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

calibrate

Измеряет, как токенайзер провайдера считает по сравнению с o200k, для каждого класса текста (проза, код, JSON, нелатиница, метаданные), через эндпоинт подсчёта провайдера и ваш ключ. В ctxray уже есть измеренная калибровка для Anthropic, так что команда нужна, только чтобы её проверить или измерить другую модель.

Параметр Значение
--provider <anthropic|openai|google> Провайдер модели. Обязателен
--model <id> Модель, которой считать. Обязателен
--out <file> Записать коэффициенты в этот файл, а не выводить их
--config <file> Файл конфига

Команда отправляет около 40 запросов, поэтому офлайн тоже не работает. Коды выхода: 0, 2, если не указаны провайдер или модель, 4 в режиме офлайн или когда запрос подсчёта к провайдеру не удался.

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

init

Создаёт ctxray.config.ts с Claude Code и Codex и ctxray/loadout.ctxray.ts — тест, который проверяет, что каждый харнесс загружает свой корневой файл правил. Добавляет .ctxray/ в существующий .gitignore. Что получилось, разобрано на странице Getting Started.

Параметр Значение
--force Перезаписать уже существующие файлы

config

Печатает конфиг с учётом extends и значений по умолчанию, со скрытыми секретами (по встроенным шаблонам и по вашим redact.patterns) и файлы, из которых он собран. Пригодится, когда унаследованная настройка ведёт себя не так, как вы ждёте. Все ключи перечислены на странице Configuration.

Параметр Значение
--config <file> Файл конфига

Clone this wiki locally