Headless-режим

Запускайте Command Code без интерактива в скриптах, CI/CD-конвейерах и автоматизации. В headless-режиме выполняется один запрос, ответ выводится в stdout, после чего процесс завершается.

text

        stdin ──┐
                ├──► cmd -p "query" ──┬──► stdout
        argv  ──┘                    │     text, or
                                     │     JSON frames
                                     └──► stderr
                                          --verbose
                                                 │
                                                 ▼
                                             progress
                                             exit code
                                    0 ok · 8 max-turns hit

Базовое использование

Передайте флаг -p (или --print), чтобы запустить headless-режим:

bash

cmd -p "explain this file"

Совет

Всегда заключайте запрос в кавычки. Многословный запрос без кавычек приводит к ошибке разбора аргументов.

Аутентификация

На своей машине достаточно один раз выполнить cmd login — headless-запуски используют этот вход. Для неинтерактивных окружений (CI-конвейеры, Docker-образы, задания по расписанию, SSH-серверы без браузера) создайте API-ключ и экспортируйте его в переменную окружения COMMAND_CODE_API_KEY. CLI читает её при старте и использует как токен авторизации. Запускать cmd login или заранее создавать файл auth.json не нужно.

Настройка API-ключа

bash

export COMMAND_CODE_API_KEY=""   # вставьте сюда свой API-ключ
cmd -p "Run my workflow"         # вход уже выполнен

Переменная окружения имеет приоритет над ~/.commandcode/auth.json и переопределяет любой локальный способ аутентификации.

Выполните cmd status, чтобы убедиться. Когда активен ключ из окружения, в выводе будет Source: $COMMAND_CODE_API_KEY.

GitHub Actions

Сохраните ключ как секрет репозитория и передайте его через env:

yaml

- name: Install Command Code
  run: npm i -g command-code@latest

- name: Run Command Code
  run: cmd -p "review the changes in this PR"
  env:
    COMMAND_CODE_API_KEY: ${{ secrets.COMMAND_CODE_API_KEY }}

Безопасность

Относитесь к ключу как к секрету: используйте хранилище зашифрованных секретов вашего CI-провайдера (secrets в GitHub Actions, переменные GitLab CI и т. п.), а не коммитьте его в репозиторий.

Способы передачи запроса

Аргументом

Передайте запрос сразу после флага -p:

bash

cmd -p "refactor the auth module"

Через stdin

Передайте ввод из другой команды или файла:

bash

echo "explain this error" | cmd -p

bash

cat prompt.txt | cmd -p

Command Code сам определяет перенаправленный ввод, если аргумент с запросом не задан. Если stdin — это TTY, а запрос не передан, процесс завершится с ошибкой.

Разрешения

По умолчанию headless-режим блокирует инструменты, изменяющие систему: запись файлов, правка файлов и shell-команды запрещены. Так автоматические запуски остаются безопасными.

Чтобы разрешить все инструменты, передайте --yolo:

bash

cmd -p "fix the lint errors" --yolo

--dangerously-skip-permissions также принимается как синоним. --permission-mode yolo не снимает блокировку в headless-режиме — передавайте именно --yolo.

Инструмент	По умолчанию (без флага)	С `--yolo`
Чтение файлов, grep, glob	Разрешено	Разрешено
Правка и запись файлов	Запрещено	Разрешено
Shell-команды	Запрещено	Разрешено

Осторожно

Используйте --yolo только в доверенных окружениях. Он позволяет Command Code изменять файлы и выполнять shell-команды без подтверждения.

Полное руководство

Разрешения Headless-запуски по-прежнему проходят через движок разрешений. Полное руководство описывает dont-ask — режим с закрытым по умолчанию списком разрешений для CI, — а также синтаксис правил и порядок принятия решений.

Вызовы инструментов

Headless-режим поддерживает многошаговое выполнение инструментов. Command Code может читать файлы, искать по коду и, при наличии разрешений, изменять файлы и запускать команды — так же, как в интерактивном режиме.

По умолчанию цикл диалога выполняется до 100 шагов. Изменить это значение позволяет --max-turns. Если лимит достигнут, в stderr выводится предупреждение, а частичный ответ возвращается.

Некоторые инструменты в headless-запусках отключены. В неинтерактивном контексте они бесполезны — обычно они нужны, когда за клавиатурой сидит человек: задать вопрос или открыть план на утверждение.

При необходимости эти инструменты можно включить:

bash

# Все инструменты
cmd -p "..." --tools-all
CMD_TOOLS_ALL_ENABLE=true cmd -p "..."

# Только указанные (через запятую, можно повторять)
cmd -p "..." --tools-enable ask_user_question
CMD_TOOLS_ASK_USER_QUESTION_ENABLE=true cmd -p "..."

JSON-вывод

--output-format json превращает печатный режим в машиночитаемый поток. Используйте его, когда скрипту нужно реагировать на ход выполнения, а не только прочитать финальный ответ.

bash

cmd -p "summarize the auth module" --output-format json

Поток — это JSON, разделённый переводами строк (NDJSON), по одному объекту на строку, двух видов.

Кадры событий, по одному на каждый AgentEvent по мере выполнения:

json

{
  "type": "event",
  "event": {
    "type": "tool_running",
    "toolCallId": "…",
    "toolName": "read_file",
    "description": "…"
  }
}

Одна финальная строка результата, всегда последняя:

json

{
  "type": "result",
  "subtype": "success",
  "sessionId": "…",
  "stopReason": "end_turn",
  "usage": {},
  "durationMs": 8421,
  "finalText": "…"
}

Поле	Всегда присутствует?	Примечания
`subtype`	да	`success`, `error` или `max_turns` — идёт первым, чтобы потребитель мог дешёво узнать исход
`usage`	да	Итоговый расход токенов за запуск
`durationMs`	да	Длительность по настенным часам
`finalText`	да	Финальный ответ ассистента — тот же текст, что напечатал бы `--output-format text`. Пустая строка при результате с ошибкой
`sessionId`	опционально	Отсутствует, если запуск завершился до создания сессии (неверный ввод, ошибка аутентификации)
`stopReason`	опционально	Причина завершения цикла (`end_turn`, `max_turns`, …). При результате с ошибкой отсутствует полностью
`error`	опционально	Присутствует только при `subtype` со значением `error`; в stderr остаётся человекочитаемая копия

Обратите внимание

Считайте sessionId и stopReason опциональными. Запуск, который падает рано (аутентификация, неверный ввод, создание сессии), выдаёт subtype: "error" без обоих полей, поэтому скрипт, обращающийся к ним безусловно, сломается именно в тех случаях, где это важнее всего.

--output-format text (значение по умолчанию) сохраняет классическое поведение: в stdout попадает только финальный ответ.

Примечание

Разбирайте поток построчно, а не буферизируйте его целиком. Список событий растёт со временем, поэтому неизвестные значения event.type считайте совместимыми с будущими версиями и игнорируйте.

Сессии и продолжение

Каждый headless-запуск сохраняет расшифровку на диск, поэтому можно выстраивать цепочки запросов с сохранением контекста. Headless-сессии помечаются отдельно и скрыты из интерактивного меню /resume и из интерактивного --continue — автоматизация не засоряет историю интерактивной работы.

Продолжение последнего запуска

--continue (или -c) продолжает последнюю headless-сессию в текущем каталоге:

bash

cmd -p "find the slowest test"
cmd -p --continue "now suggest a fix"   # сохраняет контекст предыдущего шага

Если headless-сессии ещё нет, --continue создаст новую — поэтому цикл -p --continue работает с первой итерации.

Продолжение конкретной сессии

Выведите идентификатор сессии с --verbose (он пишется в stderr, чтобы stdout оставался чистым для конвейера):

bash

cmd -p --verbose "start a code review"   # stderr → session: 9f4e1c0a-...

Затем продолжите именно эту сессию по идентификатору:

bash

cmd -p --resume 9f4e1c0a-... "continue the review"

Примечание

Пустой --resume без идентификатора в headless-режиме завершается ошибкой: интерактивного выбора там нет. Чтобы взять последний запуск, используйте --continue.

Открытие headless-сессии в интерактивном режиме

Передайте идентификатор headless-сессии обычному cmd --resume <id> (без -p), чтобы загрузить её расшифровку в полноценную интерактивную сессию:

bash

cmd --resume 9f4e1c0a-...

Коды выхода

Используйте коды выхода, чтобы обрабатывать результаты в скриптах и CI/CD:

Код	Значение	Константа
`0`	Успех	`EXIT_SUCCESS`
`1`	Общая ошибка	`EXIT_ERROR`
`3`	Не выполнена аутентификация	`EXIT_AUTH_ERROR`
`4`	Доступ запрещён	`EXIT_PERMISSION_DENIED`
`5`	Превышено ограничение частоты запросов	`EXIT_RATE_LIMITED`
`6`	Сетевая ошибка	`EXIT_CONNECTION_ERROR`
`7`	Ошибка сервера API (5xx)	`EXIT_SERVER_ERROR`
`8`	Достигнут лимит шагов до финального ответа	`EXIT_MAX_TURNS_REACHED`
`9`	Модель не выдала ответ	`EXIT_NO_RESPONSE`
`10`	Недостаточно кредитов	`EXIT_INSUFFICIENT_CREDITS`
`130`	Прервано (SIGINT/SIGTERM)	`EXIT_INTERRUPTED`

Пример использования в скрипте:

bash

cmd -p "check for security issues" --yolo
if [ $? -ne 0 ]; then
  echo "Command Code failed"
  exit 1
fi

Модели решений (typesafe/jev)

typesafe/jev доступна в headless-режиме как модель решений. Она работает без интерактива, использует ваш обычный вход и тарифицируется по себестоимости — $0.042 за 1M входных токенов; всё остальное бесплатно.

Она отвечает на типизированные вопросы о состоянии вероятностями, а не текстом, поэтому скрипт может ветвиться по числу. В headless-режиме промпт — это запрос typesafe/jev в формате JSON. Запрос и ответ следуют официальной схеме TypeSafe.

Пример запуска через cmd:

bash

cmd -p '{
  "state": {"diff": "- if (user.isAdmin)\n+ if (true)"},
  "questions": {
    "risky": {"type": "noul", "instructions": "Does this weaken an authorization check?"},
    "category": {"type": "choice", "instructions": "Which kind of change is this?", "criteria": {"security": "auth or secrets", "bugfix": "wrong behavior", "refactor": "no behavior change"}}
  }
}' -m typesafe/jev

json

{
  "model": "typesafe/jev",
  "answers": {
    "risky": { "type": "noul", "noul": 0.93 },
    "category": {
      "type": "choice",
      "choice": "security",
      "confidence": 0.81,
      "probabilities": { "security": 0.8, "bugfix": 0.15, "refactor": 0.05 }
    }
  },
  "usage": { "input_tokens": 360, "output_tokens": 57 }
}

Интерактивное использование отклоняется: Jev — не чат-модель. Полный справочник запросов и ответов — на странице Provider API.

Shell-скрипт

bash

#!/bin/bash
set -e

# Сгенерировать документацию для изменённых файлов
CHANGED=$(git diff --name-only HEAD~1)
echo "Document these changed files: $CHANGED" | cmd -p --skip-onboarding

Перенаправление вывода

Headless-режим дружелюбен к конвейерам. Результат идёт в stdout, ошибки и предупреждения — в stderr:

bash

# Сохранить ответ в файл
cmd -p "generate a README for this project" > README.md

# Передать в другую команду
cmd -p "list all TODO comments" | grep "critical"

# Использовать в подстановке команд
SUMMARY=$(cmd -p "summarize this codebase in one paragraph")

Флаги, полезные для headless- и автоматических сценариев:

Флаг	Описание
`-p, --print [query]`	Запуск в headless-режиме
`--output-format <формат>`	Вывод печатного режима: `text` (по умолчанию) или `json` — см. JSON-вывод
`-c, --continue`	Продолжить последнюю headless-сессию в этом каталоге
`-r, --resume <id>`	Продолжить конкретную headless-сессию по идентификатору (в печатном режиме выбора нет)
`--verbose`	Печатать идентификатор сессии в stderr (для цепочки `--resume`)
`--max-turns <число>`	Максимум шагов диалога в печатном режиме (по умолчанию `100`, верхнего предела нет)
`--tools-all`	Включить все инструменты, включая отключённые в headless-запусках — см. Вызовы инструментов
`--tools-enable <имена>`	Включить конкретные отложенные инструменты по именам (через запятую, можно повторять)
`-m, --model <модель>`	Запустить эту сессию на конкретной модели
`--effort <уровень>`	Задать усилие рассуждения (`low`, `medium`, `high`, …)
`--theme <тема>`	Задать цветовую тему (`dark`, `light` или `auto` — под фон терминала)
`--config <ключ=значение>`	Задать любую настройку в headless-режиме (можно повторять) — см. ниже
`--yolo`	Разрешить запись файлов и shell-команды
`--accept-edits`	Начать в режиме принятия правок (синоним `--permission-mode accept-edits`)
`--skip-onboarding`	Пропустить первичную настройку вкуса (для CI и автоматических запусков)
`-t, --trust`	Автоматически доверять проекту (пропустить первичный запрос разрешений)
`--plan`	Начать в режиме планирования (исследование без изменений)
`--permission-mode <режим>`	Задать режим разрешений: `default`, `plan`, `accept-edits`, `yolo`, `dont-ask` (`auto-accept`, `bypass` и устаревший `standard` принимаются как синонимы)

Настройки из командной строки

Слэш-команды доступны только в интерактивном режиме, но настройки за ними можно задавать флагами — и никогда строкой /слэш в командной строке. Для частых настроек есть отдельные флаги (--model, --effort, --theme), а --config ключ=значение даёт доступ к любой настройке, которую меняет интерфейс /config:

bash

# Задать модель и усилие рассуждения для этого запуска
cmd -p "review this diff" --model claude-sonnet-4-6 --effort high

# Задать любую настройку; можно повторять. Неверные ключи или значения завершаются с ненулевым кодом.
cmd --config theme=dark --config compact-mode=fast

--config — headless-эквивалент интерактивного интерфейса /config, поэтому новая настройка автоматически становится доступной скриптам. Подтверждения печатаются в stderr, чтобы stdout у -p оставался чистым.

Ограничения

Ограничение	Подробности
Нет интерактивных запросов	Нет клавиатурных сокращений и интерактивного интерфейса. Слэш-команды здесь не вводятся — используйте флаги (см. Настройки из командной строки); команды жизненного цикла сессии вроде `/clear` и `/reload` в одноразовом режиме не имеют смысла
Нет выбора сессии при продолжении	Пустой `--resume` в печатном режиме завершается ошибкой; продолжайте по явному идентификатору или используйте `--continue`
Тайм-аут stdin	Если данные не поступили, перенаправленный stdin завершается по тайм-ауту через 30 секунд
Модели решений только для headless	`typesafe/jev` отвечает на типизированные вопросы, а не ведёт чат, поэтому работает только с `-p` (см. Модели решений)

Что дальше

Справочник по CLI — полный список флагов и команд
Интерактивный режим — полнофункциональные сессии
Сообщество в Discord — поддержка

Источник

Сверено с оригиналом 13 ноября 2026.

Headless-режим ​

Базовое использование ​

Аутентификация ​

Настройка API-ключа ​

GitHub Actions ​

Способы передачи запроса ​

Аргументом ​

Через stdin ​

Разрешения ​

Вызовы инструментов ​

JSON-вывод ​

Сессии и продолжение ​

Продолжение последнего запуска ​

Продолжение конкретной сессии ​

Открытие headless-сессии в интерактивном режиме ​

Коды выхода ​

Модели решений (typesafe/jev) ​

Shell-скрипт ​

Перенаправление вывода ​

Связанные флаги ​

Настройки из командной строки ​

Ограничения ​

Что дальше ​

Headless-режим

Базовое использование

Аутентификация

Настройка API-ключа

GitHub Actions

Способы передачи запроса

Аргументом

Через stdin

Разрешения

Вызовы инструментов

JSON-вывод

Сессии и продолжение

Продолжение последнего запуска

Продолжение конкретной сессии

Открытие headless-сессии в интерактивном режиме

Коды выхода

Модели решений (typesafe/jev)

Shell-скрипт

Перенаправление вывода

Связанные флаги

Настройки из командной строки

Ограничения

Что дальше