Справочник Orca CLI

Команды, селекторы и приёмы управления Orca из оболочки и с помощью агентов.

Справочник описывает команды orca, селекторы объектов и форматы вывода для сценариев и агентов.

CLI orca обращается к запущенной среде выполнения Orca. Он позволяет сценарию или агенту проверять worktree, запускать терминалы, открывать файлы, автоматизировать встроенный браузер и передавать сведения о ходе работы обратно в Orca.

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

Зарегистрируйте CLI в разделе Настройки → Экспериментальные функции → CLI, затем проверьте подключение к Orca:

command -v orca
orca status --json

Если Orca ещё не запущена:

orca open --json
orca status --json

Используйте --json, если результат будет обрабатывать другая программа. Читаемый вывод подходит для быстрой проверки в терминале.

Селекторы

Большинство команд принимает короткие селекторы вместо длинных идентификаторов:

orca repo show --repo id:<repoId> --json
orca worktree show --worktree active --json
orca worktree show --worktree path:/abs/path/to/worktree --json
orca worktree show --worktree branch:feature-name --json
orca worktree show --worktree issue:123 --json

Значения active и current указывают на окружающий worktree под управлением Orca. Он определяется по текущему каталогу оболочки или контексту терминала. В сценариях, которые могут выполняться вне нужного worktree, задавайте селектор явно. Для удалённых сред используйте полные серверные селекторы наподобие id:<repoId>::<абсолютный-путь-worktree> или path:<абсолютный-путь-на-сервере>, поскольку текущего локального каталога может не существовать на сервере.

Команды среды выполнения

orca open --json
orca status --json
orca serve --port 6768 --pairing-address 100.64.1.20 --json

Команда orca serve запускает сервер среды выполнения на переднем плане без открытия окна приложения. Она подходит для удалённых серверов Orca и систем без графического интерфейса. Остановить сервер можно сочетанием Ctrl-C.

Репозитории

orca repo list --json
orca repo add --path /abs/path/to/repo --json
orca repo show --repo id:<repoId> --json
orca repo set-base-ref --repo id:<repoId> --ref origin/main --json
orca repo search-refs --repo id:<repoId> --query main --limit 10 --json

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

Worktree

orca worktree list --repo id:<repoId> --json
orca worktree ps --json
orca worktree current --json
orca worktree show --worktree active --json
orca worktree create --repo id:<repoId> --name fix-login --json
orca worktree create --name child-task --agent codex --prompt "Investigate the flaky login test" --json
orca worktree set --worktree active --comment "reproduced failure; testing token refresh fix" --json
orca worktree rm --worktree id:<worktreeId> --force --json

Если worktree create выполняется внутри worktree под управлением Orca, новый worktree по возможности регистрируется как дочерний. Для явного указания используйте --parent-worktree active, а для независимой работы добавьте --no-parent.

Параметры запуска агента:

orca worktree create --name review-api --agent claude --setup run --json
orca worktree create --name quick-check --agent codex --prompt "Summarize the diff" --setup skip --json
orca worktree create --name hidden-setup --setup inherit --json

Параметр --agent запускает выбранного агента в первом терминале, а --prompt отправляет ему исходную задачу. Значение --setup run|skip|inherit управляет хуками настройки репозитория. При inherit используется политика репозитория.

Терминалы

orca terminal list --worktree active --json
orca terminal show --terminal <handle> --json
orca terminal read --terminal <handle> --json
orca terminal read --terminal <handle> --cursor <cursor> --limit 1000 --json
orca terminal send --terminal <handle> --text "continue" --enter --json
orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 300000 --json
orca terminal create --worktree active --title "tests" --command "npm test" --json
orca terminal split --terminal <handle> --direction horizontal --command "npm run dev" --json
orca terminal rename --terminal <handle> --title "runner" --json
orca terminal switch --terminal <handle> --json
orca terminal close --terminal <handle> --json

Если параметр --terminal не указан, целью становится активный терминал текущего worktree. Если вы не уверены, чего ожидает терминал, прочитайте его состояние перед отправкой ввода.

Дескрипторы терминалов

Дескриптор действует только в текущей среде выполнения. Если Orca перезапустилась или команда сообщает об устаревшем дескрипторе, снова выполните orca terminal list --json.

Для длинного вывода используйте чтение с курсором. Сохраните nextCursor из результата и передайте его в следующую команду через --cursor, чтобы получить только новые данные.

Файлы

orca file open src/App.tsx --worktree active --json
orca file diff src/App.tsx --staged --worktree active --json
orca file open-changed --mode both --worktree active --json

Пути отсчитываются от выбранного worktree. Команда open-changed читает состояние Git и открывает изменённые файлы в режиме редактирования, просмотра diff или обоих режимах.

Встроенный браузер

Команды браузера управляют встроенной вкладкой Orca в выбранном worktree. Они не управляют Chrome, Safari или интерфейсом настольного приложения Orca.

Используйте цикл "снимок, действие, новый снимок":

orca goto --url http://localhost:3000 --worktree active --json
orca snapshot --worktree active --json
orca click --element @e3 --worktree active --json
orca fill --element @e1 --value "user@example.com" --worktree active --json
orca wait --text "Welcome" --worktree active --json
orca screenshot --worktree active --json

Ссылки наподобие @e3 возвращает команда snapshot. Делайте новый снимок после перехода, смены вкладки, изменяющего страницу нажатия или ошибки об устаревшей ссылке.

Команды для вкладок и записи:

orca tab list --worktree active --json
orca tab create --url http://localhost:3000 --worktree active --json
orca tab switch --index 1 --worktree active --json
orca capture start --worktree active --json
orca console --limit 50 --worktree active --json
orca network --limit 50 --worktree active --json
orca full-screenshot --worktree active --json
orca pdf --worktree active --json

Используйте orca exec --command "<команда agent-browser>" --json только для тех действий браузера, у которых пока нет отдельной типизированной команды Orca.

Эмуляция устройства в браузере:

orca set device --name "iPhone 12" --worktree active --json
orca screenshot --worktree active --json

Управление настольными приложениями

Для нативных приложений вне встроенного браузера используйте orca computer:

orca computer permissions --json
orca computer list-apps --json
orca computer get-app-state --app com.apple.Safari --json
orca computer click --app com.apple.Safari --element-index 12 --json
orca computer paste-text --app com.apple.Safari --text "hello" --json

Полный рабочий процесс и настройка разрешений описаны в статье Управление компьютером.

Мобильный эмулятор

Команды мобильного эмулятора управляют iOS Simulator через привязанный к worktree мост Orca. Если агент работает внутри Orca, используйте их вместо прямых команд serve-sim или simctl. Тогда жизненный цикл и состояние активного устройства останутся связанными с текущим worktree.

orca emulator list --worktree active --json
orca emulator attach "<device-name-or-udid>" --worktree active --json
orca emulator tap 0.5 0.7 --worktree active --json
orca emulator type "hello" --worktree active --json
orca emulator gesture '[{"type":"begin","x":0.5,"y":0.8},{"type":"move","x":0.5,"y":0.4},{"type":"end","x":0.5,"y":0.2}]' --worktree active --json
orca emulator button home --worktree active --json
orca emulator rotate landscape_left --worktree active --json
orca emulator exec --command "tap 0.5 0.7" --worktree active --json
orca emulator kill --worktree active --json
orca emulator shutdown --worktree active --json

Координаты нормализованы от 0 до 1. Для одиночного нажатия выбирайте tap, а для перетаскивания и последовательности касаний используйте gesture. Параметры --device <udid-или-имя> и --emulator <id> задают конкретный симулятор вместо активного эмулятора worktree.

Linear

Подкоманда orca linear предоставляет сценариям и агентам доступ к подключённому рабочему пространству Linear. Команды чтения возвращают контекст задачи в JSON, а команды записи изменяют данные. Если с worktree связана задача Linear, к ней можно обратиться через --current.

Чтение:

orca linear issue --current --full --json
orca linear issue ENG-123 --comments --children --json
orca linear search "auth bug" --workspace all --json
orca linear list --json
orca linear team list --json
orca linear team states --team <key|id> --json
orca linear team labels --team <key|id> --json

Запись:

orca linear status set --current --to "In Progress" --json
orca linear assignee set --current --me --json
orca linear priority set ENG-123 --to high --json
orca linear estimate set --current --to 3 --json
orca linear due-date set --current --to 2026-08-01 --json
orca linear label add --current --label backend --json
orca linear comment add --current --body "Investigating regression" --json
orca linear attach --current --url https://example.com/repro --title "Repro" --json
orca linear create --title "Flaky login test" --team ENG --priority high --json

Полный список параметров выводит orca linear <команда> --help. Среди них есть --workspace <id> для выбора одного из нескольких подключённых рабочих пространств. Если сценарий может выполняться вне связанного с Linear worktree, явно передавайте идентификатор задачи, например ENG-123, поскольку --current работает только при наличии связи.

Автоматизации, среды и хуки

Запросы по расписанию:

orca automations list --json
orca automations create --name "Daily review" --trigger daily --time 09:00 --prompt "Review open changes" --provider codex --repo id:<repoId> --disabled --json
orca automations run <automationId> --json

Удалённые среды выполнения:

orca environment add --name work-laptop --pairing-code "orca://pair?code=..." --json
orca environment list --json
orca environment rm --environment <selector> --json

Хуки состояния агента:

orca agent hooks status --json
orca agent hooks on --json
orca agent hooks off --json

Правила работы агента

Для автоматизации и вызовов агентов предпочитайте --json.
Используйте селекторы вместо разбора подписей интерфейса.
Перед отправкой ввода читайте состояние терминала, если следующий ввод не очевиден.
Отмечайте ход работы в комментариях worktree. Подробнее: Контрольные точки worktree.
Для отслеживаемых назначений между несколькими агентами используйте оркестрацию, а не разовые запросы в терминал.

Частые вопросы

Как узнать параметры конкретной команды Orca CLI?

Вызовите команду с флагом справки или найдите её раздел на этой странице.

Что такое селектор в Orca CLI?

Селектор указывает нужный worktree, терминал, вкладку или другой объект без ручного перехода в интерфейсе.

Как получить машиночитаемый результат?

Для поддерживаемых команд используйте JSON-вывод и обрабатывайте поля, а не текстовое оформление терминала.

Можно ли передавать длинные данные через стандартный ввод?

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

Как избежать действия не в том worktree?

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