Headless-режим¶

Headless-режим Koda CLI выполняет запрос без интерактивного интерфейса и возвращает результат в stdout. Он предназначен для скриптов, пайплайнов CI/CD и любой автоматизации, где диалог в терминале не нужен.

В этом режиме интерфейс не рендерится: CLI принимает запрос, работает с моделью и инструментами, а затем завершает процесс.

Все флаги запуска перечислены в аргументах CLI.

Когда включается headless-режим¶

Headless-режим активируется автоматически, если соблюдено одно из условий:

передан флаг -p (или --prompt) с текстом запроса;
ввод подаётся через stdin, когда процесс запущен не в TTY-окружении (например, через конвейер).

В следующем примере команда передаётся через echo, а результат выводится в терминал:

echo "Что такое тонкая настройка?" | koda

Тот же результат достигается флагом --prompt:

koda -p "Что такое тонкая настройка?"

Совместимость способов запуска

Содержимое stdin добавляется к тексту --prompt с разделителем в виде пустой строки. Так можно комбинировать директиву из скрипта с динамическим вводом из конвейера.

Headless-режим запускается и тогда, когда окружение не является интерактивным. В таких случаях CLI автоматически переходит к обработке ввода из stdin без флага --prompt.

Ввод¶

Источники ввода для headless-режима:

флаг --prompt;
stdin, если процесс запущен не в TTY и ввод не пуст;
комбинация: stdin добавляется к запросу из --prompt.

Лимит объёма stdin — 8 МБ. При превышении ввод усекается до лимита, а в stderr выводится предупреждение.

Проброс ввода через конвейер

Флаг --prompt-interactive (-i) нельзя использовать вместе с вводом из stdin. Если -i передан, а процесс не запущен в TTY, CLI завершается с ошибкой и кодом 1.

Для работы без интерактивного интерфейса настройте способ аутентификации заранее через переменные окружения: KODA_AUTH_ACCESS_TOKEN, KODA_AUTH_REFRESH_TOKEN или KODA_API_KEY. Подробнее — в разделе аутентификации.

Вывод¶

В headless-режиме stdout и stderr разделены:

Поток	Что попадает
`stdout`	итоговый ответ модели без служебной информации
`stderr`	reasoning модели и сообщения об ошибках

Reasoning выводится в stderr только при флаге --show-reasoning. По умолчанию в stdout остаётся только итоговый ответ.

Последовательные переводы строк в ответе схлопываются до двух подряд, чтобы вывод оставался компактным.

Если вывод направлен в команду, которая завершилась раньше, обрыв канала считается штатным завершением: процесс выходит с кодом 0, не порождая ошибку EPIPE.

Коды завершения¶

CLI использует два основных кода завершения в headless-режиме:

Код	Значение
`0`	успешное выполнение
`1`	ошибка: сбой API, некорректные флаги, отсутствие ввода или ошибка аутентификации

Некорректная комбинация флагов (например, одновременные --prompt и --prompt-interactive) приводит к ошибке и завершению с кодом 1. Отсутствие ввода (промпта и данных stdin) также завершает процесс с кодом 1.

Ограничение числа шагов

Максимальное число ходов модели регулируется настройкой maxSessionTurns в settings.json (по умолчанию выключено). При превышении лимита CLI сообщает об этом в stderr и завершает выполнение. Остальные настройки — на странице настройки.

Подтверждение действий¶

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

Выбор режима подтверждения задаётся флагом --approval-mode:

Режим	Что происходит
`default`	инструменты с подтверждением отключены
`auto_edit`	автоматически подтверждаются инструменты редактирования файлов
`yolo`	автоматически подтверждаются все инструменты

Допустимо использовать -y (--yolo) вместо --approval-mode yolo, но не одновременно.

Примеры автоматизации¶

Простой запрос с флагом --prompt:

koda -p "Опиши структуру каталога src/"

Отправка вывода конвейером, reasoning не показывается:

cat service.log | koda -p "Найди ошибки в этом логе"

Запрос с заданной моделью и подтверждением правок:

koda -p "Почини линтер" --approval-mode=auto_edit -m my-model

Использование в CI: выполнить запрос и считать результат из stdout:

RESULT=$(koda -p "Сгенерируй git-сообщение для этих изменений")
echo "$RESULT"

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

Структурированный вывод (JSON, JSONL) не поддерживается — CLI возвращает только текстовый ответ в stdout.
Интерактивные возможности TUI в headless-режиме недоступны.
Подтверждение инструментов по умолчанию выключено, что защищает от нежелательных действий.