CLI claude: флаги, которые меняют результат
Большинство людей узнают о командной строке Claude Code три вещи — claude, claude -c и claude -p — и на этом останавливаются. Это разумная остановка, если вы всегда работаете сидя перед экраном. Но как только вы ставите Claude Code в скрипт, задачу CI, фоновую очередь или отдаёте его в руки коллеги, флаги перестают быть удобством и становятся разницей между запуском за доллар и запуском, который висит час.
Эта страница — не вторая копия таблицы из справочника. Это порядок, в котором стоит изучать поверхность, флаги, которые реально меняют происходящее, и четыре ловушки, стоящие людям реального времени.
- Шесть видов сессий, которые можно запустить, и какой флаг выбирает каждый
- Контракт из пяти флагов, который делает запуск без присмотра ограниченным, отвечаемым и разбираемым
- Почему правка --append-system-prompt и повторный --continue, кажется, ничего не меняют — правило записанного промпта
- Чем различаются --bare, --safe-mode и --restricted и что выбрать когда
- Управление фоновыми сессиями из оболочки: agents, attach, logs, respawn, rm, daemon
- Пары флагов, которые путают: --tools против --allowedTools против --disallowedTools
Начните с вопроса: что это за сессия?
Все остальные решения вытекают из этого. Claude Code может запустить шесть существенно разных вещей, и флаг, выбирающий одну из них, обычно набирается первым.
| Вам нужно | Флаг | Вы получаете |
|---|---|---|
| Разговор, за которым вы следите | (нет) | Интерактивную сессию в этом терминале |
| Один ответ и выход | -p / --print | Неинтерактивный запуск, вывод в stdout |
| Работу, которая переживёт этот терминал | --bg / --background | Фоновую сессию; она печатает свой ID и способ управления |
| Изолированную ветку для экспериментов | -w / --worktree | Git worktree в <repo>/.claude/worktrees/<name> |
| Работу на машинах Anthropic | --cloud | Облачную сессию или продолжение, поставленное в очередь в существующую |
| Управлять этой сессией с телефона | --rc / --remote-control | Интерактивную сессию, которой можно также управлять из claude.ai или приложения Claude |
Две из них несовместимы: --bg и -p взаимоисключающие, потому что одна возвращается сразу, а другая ждёт ответа. Если вам нужна в фоне shell-команда, а не сессия Claude, сочетайте --bg с --exec:
Запустить набор тестов как фоновое задание, а не как сессию Claude
claude --bg --exec 'pytest -x'
А --bg перед стартом проверяет доверие к рабочему пространству для этого каталога — поэтому фоновая сессия в недоверенном репозитории падает сразу, а не на полпути.
Контракт из пяти флагов для запусков без присмотра
Это самое ценное на этой странице. У запуска claude -p без присмотра есть три способа пойти не так, которых у интерактивной сессии просто нет: он может застрять на запросах разрешений, на которые некому ответить, может зациклиться гораздо дольше, чем вы ожидали, и может выдать прозу, когда вашему скрипту нужны были данные. Пять флагов закрывают все три риска.
- `claude -p "query"` печатает ответ и завершается. Всё остальное ниже работает только в режиме print, поэтому этот флаг — вход ко всему прочему.
- По умолчанию `host`: запросы уходят хосту Agent SDK или в `--permission-prompt-tool`. Передайте `--permission-prompts none`, когда ответить некому — например, в cron-задаче или шаге CI: запуск перестаёт обращаться к хосту и ждать его, всё, что потребовало бы запроса, отклоняется, если только его не разрешит хук `PermissionRequest`, а Claude получает указание не повторять попытку. Запуск `-p` вообще без хоста и так отклоняет такие запросы; в этом случае флаг в основном останавливает повторные попытки. Требует v2.1.259 или новее. Сочетайте с узкими правилами `--allowedTools`, чтобы отказы были редкими, а не постоянными.
- По умолчанию лимита ходов нет. `--max-turns 3` завершается с ошибкой, когда лимит достигнут. Используйте его как растяжку против вышедших из-под контроля агентных циклов, а не как бюджет.
- `--max-budget-usd 5.00` останавливает работу, когда клиентская оценка стоимости достигает лимита. Расходы субагентов учитываются; после достижения лимита попытка запустить ещё одного субагента завершается ошибкой `Budget limit reached`, а работающие фоновые субагенты останавливаются. Применение лимита требует v2.1.217 или новее.
- `--output-format json` даёт структурированную обёртку. `--json-schema '<schema>'` идёт дальше: Claude Code проверяет финальный ответ по вашей JSON-схеме и сразу сообщает об ошибке, если схема недопустима, так что вашему скрипту никогда не придётся разбирать прозу регулярками.
Шаг CI, который не может повиснуть, бесконечно зациклиться или перерасходовать
claude -p "Review the staged diff and list bugs" \ --permission-prompts none \ --allowedTools "Read" "Bash(git diff *)" \ --max-turns 6 \ --max-budget-usd 2.00 \ --output-format json
- Claude Code сверяет лимит со своей клиентской оценкой стоимости, которая может отличаться от того, что вам выставят.
- Когда вы возвращаетесь к разговору через --continue или --resume, суммы, восстановленные из прошлых запусков, не засчитываются в лимит — поэтому три возобновлённых запуска при лимите $2 могут потратить в сумме больше $2.
- Считайте это автоматом защиты для одного запуска. Настоящий потолок для всего аккаунта или проекта — в Hard Spend Caps.
Об общей позиции, когда запуск идёт без человека — что разрешать, что маскировать, что логировать — см. Защита автономных запусков и Headless-режим и Agent SDK. О потолках на уровне провайдера — Hard Spend Caps.
Семейство системного промпта и ловушка в нём
Пять флагов формируют системный промпт. Четыре задают его текст; пятый решает, сохранит ли разговор тот текст, с которого начал.
| Флаг | Что делает |
|---|---|
--system-prompt | Заменяет весь промпт по умолчанию вашим текстом |
--system-prompt-file | Заменяет его содержимым файла |
--append-system-prompt | Дописывает ваш текст к промпту по умолчанию |
--append-system-prompt-file | Дописывает содержимое файла к промпту по умолчанию |
--system-prompt-snapshot | off пересобирает промпт при каждом запросе; on (по умолчанию) использует записанный |
Выбор между дописать и заменить — это выбор об идентичности. Дописывание сохраняет стандартные указания Claude Code по инструментам, инструкции безопасности и соглашения по написанию кода и накладывает ваши правила сверху — подходит для инструкций на конкретный запуск, форматирования вывода или контекста проекта. Замена отбрасывает всё это, включая указания по инструментам, и потому правильна лишь тогда, когда поверхность действительно не ассистент для кода: некодовый агент в конвейере, за которым никто не следит. Если вы заменяете, всё, что ещё нужно задаче, — на вас.
Их можно сочетать. Флаг дописывания вместе с флагом замены заменяет промпт по умолчанию, а затем дописывает ваш текст. Начиная с v2.1.283 можно также передать флаг вместе с его файловой формой — --append-system-prompt и --append-system-prompt-file — и Claude Code использует оба, причём содержимое файла идёт первым независимо от порядка, в котором вы их набрали.
- Claude Code строит системный промпт один раз, при первом запросе разговора, и записывает его в сессию.
- Пока разговор не сжат, каждый следующий запрос использует этот записанный промпт — в том числе после --resume или --continue.
- Так что вы правите текст --append-system-prompt, снова запускаете claude --continue, и ничего не меняется. Флаг не сломан; разговор всё ещё использует запись.
- Новый текст вступает в силу после сжатия разговора или в совершенно новом разговоре.
- Чтобы подбирать формулировку между запусками --continue, передайте --system-prompt-snapshot off, и промпт будет пересобираться при каждом запросе. Требует v2.1.257 или новее.
Есть ещё один приём, полезный в заменяющем промпте, где смешаны стабильные инструкции и контекст конкретного запуска. Поставьте между ними строку, содержащую только __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__: Claude Code делит промпт по первой такой строке и удаляет её, так что часть выше остаётся в кэше, а часть ниже меняется. Требует v2.1.275 или новее. Почему это важно для вашего счёта, рассказано в Prompt Caching.
А для скриптовых нагрузок с несколькими пользователями --exclude-dynamic-system-prompt-sections переносит контекст конкретного пользователя, например расположение автопамяти, из системного промпта в первое пользовательское сообщение — так одна и та же задача на разных машинах делит один кэшируемый префикс. Он применяется только к промпту по умолчанию и игнорируется, если вы задали --system-prompt или --system-prompt-file.
Три флага, которые что-то отключают, и это не одно и то же
Их часто берут взаимозаменяемо, а потом удивляются, что симптом не сдвинулся. Они решают три разные проблемы.
--bare | --safe-mode | --restricted | |
|---|---|---|---|
| Проблема, которую решает | Запуск слишком медленный для скриптового вызова | Моя конфигурация сломана, и я не знаю, какая часть | Оценочный стенд не должен трогать эту общую машину |
| CLAUDE.md, навыки, команды, субагенты, плагины, MCP, автопамять | Не обнаруживаются | Не загружаются | Загружаются только управляемые настройки и --settings |
| Встроенные инструменты | Bash, чтение файла, правка файла | Работают как обычно | Инструменты запуска команд/кода и WebFetch удалены, если не названы по отдельности в --tools |
| Доступ к файлам | Обычный | Обычный | Ограничен рабочими каталогами |
bypassPermissions | Разрешён | Разрешён | Отклоняется |
| Управляемая политика | Применяется | Продолжает применяться, включая хуки политик и строку состояния | Применяется |
| Побочный эффект | Устанавливает CLAUDE_CODE_SIMPLE | Устанавливает CLAUDE_CODE_SAFE_MODE | Отказывается создавать облачные сессии |
Читайте таблицу как последовательность намерений: --bare — про скорость, --safe-mode — про диагностику, --restricted — про изоляцию. Полезная деталь: навыки из каталога, переданного через --add-dir, загружаются и под --bare, так вы сохраняете ровно одну возможность в остальном урезанном запуске.
--safe-mode — то, за что стоит браться первым, когда что-то работает не так и вы не можете понять, виноват Claude Code или ваша собственная конфигурация, — в том числе когда вы выясняете, не вызывает ли автоматический откат модели какая-то из ваших настроек. Сочетайте его с claude doctor, который выводит диагностику установки и настроек только для чтения, вообще не запуская сессию. (Команда /doctor внутри сессии — другое: она может и применять исправления.) Больше отладки по симптомам — в Устранение неполадок Claude Code. --restricted требует v2.1.248 или новее.
Управление фоновыми сессиями из оболочки
Когда вы запускаете сессии через --bg, терминал становится плоскостью управления. У всего жизненного цикла есть команда, и ничто из этого не требует открывать интерактивный интерфейс.
- Открывает вид агентов для мониторинга и распределения параллельных фоновых сессий. Для скриптов `--json` печатает активные сессии как JSON-массив, а `--json --all` включает завершённые. `--cwd <path>` сужает выбор до сессий, запущенных в этом каталоге. Для открытия самого вида нужен интерактивный терминал; для JSON-формы — нет.
- `claude logs <id|name>` печатает недавний вывод фоновой сессии. Начиная с v2.1.290 вместо ID можно передать часть имени работающей сессии — так что обычно хватает `claude logs auth`.
- `claude attach <id|name>` приносит фоновую сессию в этот терминал. Сопоставление по части имени тоже требует v2.1.290 или новее.
- `claude respawn <id>` перезапускает сессию, работающую или остановленную, с сохранением разговора. `--all` перезапускает все работающие сессии — то, что нужно сделать после обновления бинарника Claude Code.
- `claude stop <id>` (также `claude kill`) останавливает сессию. `claude rm <id>` убирает её из списка; транскрипт остаётся на вашей машине и по-прежнему доступен через `claude --resume`. Если удаление отклонено из-за worktree сессии, в отказе напечатан точный флаг для следующей попытки — `--discard-unpushed` (v2.1.260+) или `--force-remove-worktree` (v2.1.268+).
- Фоновые сессии размещает процесс-супервизор. `claude daemon status` печатает его состояние, версию, каталог сокета и число воркеров и завершается с кодом 1, если он не запущен. `claude daemon logs` следит за `~/.claude/daemon.log`. `claude daemon stop --any --keep-workers` перезапускает супервизор, оставляя сессии живыми, чтобы следующий к ним переподключился.
Парная тема изнутри сессии — как работа уходит в фон и что при этом переносится — разобрана в Фоновые задачи, /loop и планирование.
Пары флагов, которые понимают неверно
- --tools ограничивает, какие встроенные инструменты вообще существуют. --allowedTools говорит, какие вызовы пропускают запрос разрешения. --disallowedTools отклоняет вызовы. Это три разные задачи, и передача не того флага — самая частая причина вопроса «почему он всё ещё спрашивает».
- --tools вообще не влияет на инструменты MCP. Чтобы убрать и их, добавьте --disallowedTools "mcp__*".
- Голое имя в --disallowedTools убирает инструмент из контекста Claude; правило с областью вроде Bash(rm *) оставляет инструмент доступным и отклоняет только подходящие вызовы.
- --dangerously-skip-permissions запускается в bypassPermissions. --allow-dangerously-skip-permissions лишь добавляет этот режим в цикл Shift+Tab, так что можно стартовать в plan mode и переключиться позже. Почти всегда вам на самом деле нужен второй.
- --add-dir даёт доступ к файлам, но Claude Code не обнаруживает большую часть конфигурации .claude/ из этих каталогов. Добавить каталог — не значит принять его конфигурацию.
- --desktop не принимает ни промпт, ни другие флаги, кроме --verbose и флагов --debug, потому что сессию запускает само приложение Desktop. Требует v2.1.285 или новее.
Одна небольшая деталь для удобства: если опечататься в подкоманде, Claude Code предложит ближайшую и завершится, не запуская сессию — claude udpate печатает Did you mean claude update? вместо того, чтобы открывать ненужный вам разговор.
Проверьте себя
Check yourself
0/3- Сначала выберите вид сессии — флаг, который это делает, ограничивает все остальные флаги, которые можно передать.
- Запуску без присмотра нужны пять флагов, а не один: -p, --permission-prompts none, --max-turns, --max-budget-usd и структурированный формат вывода.
- Считайте --max-budget-usd автоматом защиты для одного запуска, а не потолком счёта. Это клиентская оценка, и возобновлённые суммы от неё ускользают.
- Разговоры записывают свой системный промпт при первом запросе. Если правка промпта кажется проигнорированной, дело в этом — используйте --system-prompt-snapshot off, пока подбираете формулировку.
- --bare — скорость, --safe-mode — диагностика, --restricted — изоляция. Выбрав не тот, вы потеряете целый день.
- --help неполон по замыслу. Источник истины — справочник по CLI, а минимальные версии важны — проверьте claude -v, прежде чем винить флаг.
Дальше
- Headless-режим и Agent SDK — что строить, когда одного вызова
-pуже мало - settings.json: система конфигурации — постоянное место для флагов, которые вы всё время набираете заново
- Устранение неполадок Claude Code — отладка по симптомам, начиная с
--safe-mode