Аргументы CLI¶

Команда запуска называется koda. Справочник описывает флаги запуска, значения по умолчанию и связанные переменные окружения. Общие настройки и их приоритет — на странице настройки, команды внутри сессии — в справочнике команд.

Приоритет настроек¶

От низшего к высшему:

1. Значения по умолчанию — встроены в код;
2. settings.json — файлы настроек;
3. Переменные окружения — переопределяют настройки (если заданы);
4. CLI-флаги — переопределяют переменные окружения и настройки (если заданы явно).

Основной запуск¶

Глобальные флаги --help/-h и --version/-v предоставляются самим парсером аргументов и доступны для koda и всех подкоманд.

Опции¶

Каждый аргумент ниже описан отдельной секцией с указанием значения по умолчанию и связанных переменных окружения.

Модель и контекст¶

--model¶

v0.1.6 koda-base KODA_MODEL

Модель для диалога. Значение по умолчанию применяется, если модель не задана настройками или переменными окружения.

--all-files¶

v0.1.10 false

Включить все найденные файлы в контекст.

--include-directories¶

v0.1.16

Добавить каталоги в рабочую область. Каталоги можно передавать через запятую или повторяя флаг.

Режим запуска¶

--prompt¶

v0.1.6

Prompt для неинтерактивного режима. Содержимое stdin добавляется к prompt.

--prompt-interactive¶

v0.1.12

Выполнить prompt и продолжить в интерактивном режиме.

--show-reasoning¶

v1.1.1 false

В неинтерактивном режиме выводить reasoning модели в stderr. В stdout остаётся только ответ.

Неинтерактивный режим¶

Флаги этой секции действуют, когда CLI работает без интерфейса: с --prompt, с вводом из stdin или с --input-format stream-json. Подробное описание режима, форматов и кодов завершения — на странице headless-режим.

--output-format¶

v1.3.0 text

Формат вывода неинтерактивного прогона:

• text — только ответ модели в stdout;
• json — один JSON-объект с результатом, метриками и отчётом об использовании;
• stream-json — поток событий NDJSON: одно событие в строке.

--input-format¶

v1.3.0 text

Формат ввода неинтерактивного прогона:

• text — весь stdin и --prompt как один запрос;
• stream-json — построчный поток сообщений пользователя для многовиткового диалога в одном процессе.

Флаг --input-format stream-json включает неинтерактивный режим, даже когда stdin подключён к терминалу.

--show-usage¶

v1.3.0 false

В текстовом режиме печатать отчёт об использовании в stderr после завершения прогона: витки, длительность, токены и вызовы инструментов. В режимах json и stream-json отчёт всегда входит в поле usage, и флаг не нужен.

--max-turns¶

v1.3.0

Лимит витков агента в неинтерактивном режиме. Принимает целое число не меньше 1.

Перекрывает настройку maxSessionTurns. Упор в лимит даёт код выхода 2 и stop_reason: "limit".

--allowed-tools¶

v1.3.0

Оставить модели только перечисленные встроенные инструменты. Действует как настройка coreTools, но на один запуск.

Список можно передавать через запятую или повторяя флаг.

--disallowed-tools¶

v1.3.0

Исключить перечисленные инструменты. Применяется поверх --allowed-tools и пользовательских исключений.

Список можно передавать через запятую или повторяя флаг.

--append-system-prompt¶

v1.3.0

Дописать текст в конец системного промпта после памяти проекта из KODA.md. Файлы проекта при этом не меняются.

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

--approval-mode¶

v0.1.20

Режим подтверждения вызова инструментов:

• default — запрашивать подтверждение;
• auto_edit — автоматически подтверждать инструменты редактирования;
• yolo — автоматически подтверждать все инструменты.

--yolo¶

v0.1.6 false

Алиас для --approval-mode=yolo.

Песочница¶

--sandbox¶

v0.1.6 false KODA_SANDBOX

Запустить CLI в песочнице. Значением может быть true, false или одна из команд: docker, podman, sandbox-exec.

!!! info "Переменная окружения" KODA_SANDBOX имеет приоритет над флагом и настройками.

--sandbox-image¶

v0.1.6 KODA_SANDBOX_IMAGE

Образ для Docker/Podman sandbox. По умолчанию используется образ, заданный в конфигурации пакета.

Отладка и мониторинг¶

--debug¶

v0.1.6 false DEBUG, DEBUG_MODE

Включить debug-режим.

--show-memory-usage¶

v0.1.10 false

Показывать использование памяти в статусной строке.

Сеть¶

--proxy¶

v0.1.13 HTTPS_PROXY, HTTP_PROXY

Строка подключения к прокси-серверу в формате schema://user:password@host:port. Имеет приоритет над переменными окружения и настройками.

--ca-file¶

v1.1.1

Путь к PEM-набору корневых сертификатов для HTTP-запросов CLI. Имеет приоритет над настройкой network.caFile.

Checkpointing¶

--checkpointing¶

v0.1.6 false

Включить checkpointing изменений файлов. Эквивалентен настройке checkpointing.enabled.

MCP и расширения¶

--allowed-mcp-server-names¶

v0.1.10

Ограничить набор MCP-серверов, которые могут использоваться. Переопределяет настройки allowMCPServers и excludeMCPServers.

--extensions¶

v0.1.10

Включить только указанные расширения. Значение none отключает все расширения.

--list-extensions¶

v0.1.10 false

Вывести доступные расширения и выйти.

Телеметрия¶

--telemetry¶

v0.1.6

Включить отправку телеметрии. Другие флаги --telemetry-* задают отдельные значения, но сами по себе телеметрию не включают.

--telemetry-target¶

v0.1.6

Цель телеметрии: local или gcp. Переопределяет настройки.

--telemetry-otlp-endpoint¶

v0.1.6 OTEL_EXPORTER_OTLP_ENDPOINT

OTLP-адрес для телеметрии. Переопределяет переменную окружения и настройки.

--telemetry-log-prompts¶

v0.1.6

Включить или отключить логирование пользовательских промптов для телеметрии. Переопределяет настройки.

--telemetry-outfile¶

v0.1.14

Перенаправить весь вывод телеметрии в указанный файл.

IDE-интеграция¶

--acp¶

v1.1.1

Запустить агент в ACP-режиме для IDE-клиента, например JetBrains AI Assistant. Алиас: --experimental-acp.

Подкоманды верхнего уровня¶

Помимо основного запуска koda поддерживает встроенные подкоманды для управления MCP-серверами, языком интерфейса, расширениями, навыками и интеграциями с терминалами. Все подкоманды выполняются однократно, выводят результат в терминал и завершают процесс, не открывая сессию.

Общий синтаксис:

koda <подкоманда> <действие> [аргументы] [опции]

Неизвестные опции и подкоманды приводят к ошибке разбора: CLI работает в строгом режиме.

MCP¶

v1.1.1

Подкоманда koda mcp управляет MCP-серверами: добавляет, удаляет и показывает настроенные серверы.

koda mcp <add|remove|list> [аргументы] [опции]

Без указания действия koda mcp показывает справку.

koda mcp add¶

Добавляет или обновляет MCP-сервер в настройках.

koda mcp add [options] <name> <commandOrUrl> [args...]

Позиционные аргументы:

Опции:

Если сервер с таким именем уже существует, команда обновляет его конфигурацию.

Примеры:

koda mcp add my-server npx @some/mcp-server
koda mcp add remote --transport sse --header "X-Api-Key: abc123" https://example.com/sse
koda mcp add gated --transport http --include-tools list,read --trust https://example.com/mcp

koda mcp remove¶

Удаляет MCP-сервер из настроек.

koda mcp remove [options] <name>

Позиционные аргументы:

Опции:

Если сервер не найден в выбранной области, команда сообщает об этом и завершается без изменений.

koda mcp list¶

Показывает настроенные MCP-серверы и их статус подключения.

koda mcp list

Команда не принимает аргументов. Для каждого сервера выводится имя, команда или URL, тип транспорта и статус после попытки реального подключения:

• ✓ Connected — сервер ответил на ping;
• ✗ Disconnected — подключиться не удалось;
• … Connecting — подключение ещё выполняется.

Language¶

v1.1.1

Подкоманда koda language управляет языком интерфейса.

koda language <set> <language>

koda language set¶

Устанавливает язык интерфейса в пользовательских настройках.

koda language set <language>

Позиционные аргументы:

Примеры:

koda language set ru
koda language set en

После изменения перезапустите другие запущенные экземпляры koda, чтобы язык применился.

Extensions¶

v1.1.1

Подкоманда koda extensions управляет расширениями.

koda extensions <install|uninstall|list|update|enable|disable> [аргументы] [опции]

koda extensions install¶

Устанавливает расширение из git-репозитория или локальной директории.

koda extensions install [options] [source]

Позиционные аргументы:

Опции:

Аргументы source и --path взаимоисключающие: должен быть указан ровно один из них. После установки расширение включается автоматически.

Примеры:

koda extensions install https://github.com/example/my-extension
koda extensions install --path ./local-extension

koda extensions uninstall¶

Удаляет установленное расширение.

koda extensions uninstall <name>

Позиционные аргументы:

koda extensions list¶

Показывает установленные расширения.

koda extensions list

Команда не принимает аргументов. Если расширений нет, выводится No extensions installed.

koda extensions update¶

Обновляет расширение до последней версии.

koda extensions update <name>

Позиционные аргументы:

При успехе выводится сообщение о смене версии: старая → новая.

koda extensions enable¶

Включает расширение в указанной области настроек.

koda extensions enable [options] <name>

Позиционные аргументы:

Опции:

koda extensions disable¶

Отключает расширение в указанной области настроек.

koda extensions disable [options] <name>

Позиционные аргументы:

Опции:

Skills¶

v1.1.1

Подкоманда koda skills управляет навыками агента: установкой, удалением и состоянием включения.

koda skills <list|install|uninstall|enable|disable> [аргументы] [опции]

Область настроек (--scope) во всех подкомандах принимает user, project или workspace. Области project и workspace эквивалентны: обе соответствуют настройкам рабочего каталога.

koda skills list¶

Показывает обнаруженные навыки.

koda skills list

Команда не принимает аргументов. Для каждого навыка выводятся имя, описание и метки: disabled — отключён, builtin — встроенный.

koda skills install¶

Устанавливает навыки из git-репозитория, локальной директории или .skill-пакета.

koda skills install [options] [source]

Позиционные аргументы:

Опции:

Источником служит source либо --path. Если source указывает на репозиторий, а --path задан, устанавливается навык из указанной поддиректории репозитория. Установка копирует каталог навыка в ~/.kodacli/skills (область user) или <проект>/.kodacli/skills (область project).

Примеры:

koda skills install https://github.com/example/my-skills
koda skills install --path ./my-skill
koda skills install https://github.com/example/mono-repo --path packages/skill-a --scope project
koda skills install ./skill-package.skill

koda skills uninstall¶

Удаляет установленный навык.

koda skills uninstall [options] <name>

Позиционные аргументы:

Опции:

koda skills enable¶

Включает навык в указанной области настроек.

koda skills enable [options] <name>

Позиционные аргументы:

Опции:

Команда удаляет навык из списка отключённых skills.disabled выбранной области. Если навык не найден среди обнаруженных, выводится список доступных навыков.

koda skills disable¶

Отключает навык в указанной области настроек.

koda skills disable [options] <name>

Позиционные аргументы:

Опции:

Integrations¶

v1.2.0

Подкоманда koda integrations kitty управляет интеграцией с терминалом Kitty: чатом об истории терминала и подсказками после неудачных команд.

koda integrations kitty <install|status|uninstall|suggest|chat|configure|auto|service> [опции]

Опции install:

Опции configure совпадают с --chat-* из install.

Удалённый доступ через Telegram¶

Удалённый доступ через Telegram управляется слеш-командами внутри сессии, а не подкомандой CLI:

/telegram status
/telegram setup <bot-token>
/telegram link
/telegram relink
/telegram unlink
/telegram disable

/telegram setup сохраняет токен бота в пользовательских настройках и включает удалённый доступ через Telegram. Ссылка привязки владельца появляется в /stats, когда бот подключился. Сценарий рассчитан на одного владельца: один Telegram-пользователь управляет текущим CLI, а удалённые сессии живут только пока этот CLI запущен.

Со стороны Telegram доступны /start <code> для привязки, /new, /model, /stats, /compress, /revert, /delete, /stop, /commit и /unlink.