440 lines
24 KiB
TypeScript
440 lines
24 KiB
TypeScript
/* eslint-disable max-lines -- Why: root and generated command help text live together so CLI discovery stays greppable. */
|
|
import type { CommandSpec } from './args'
|
|
import { findCommandSpec, isCommandGroup, supportsBrowserPageFlag } from './args'
|
|
|
|
const ROOT_HELP_TEXT = `orca
|
|
|
|
Usage: orca <command> [options]
|
|
|
|
Startup:
|
|
open Launch Orca and wait for the runtime to be reachable
|
|
serve Start a headless Orca runtime server
|
|
status Show app/runtime/graph readiness
|
|
|
|
Diagnostics:
|
|
diagnostics memory Collect a memory snapshot for Orca and managed terminals
|
|
|
|
Environments:
|
|
environment add Save a remote Orca runtime from a pairing code
|
|
environment list List saved remote Orca runtimes
|
|
environment show Show one saved remote Orca runtime
|
|
environment rm Remove a saved remote Orca runtime
|
|
|
|
Automations:
|
|
automations list List scheduled Orca automations
|
|
automations show Show one Orca automation
|
|
automations create Create a scheduled Orca automation
|
|
automations edit Edit an Orca automation
|
|
automations remove Remove an Orca automation and its run history
|
|
automations run Run an Orca automation now
|
|
automations runs List automation run history
|
|
|
|
Repos:
|
|
repo list List repos registered in Orca
|
|
repo add Add a project to Orca by filesystem path
|
|
repo show Show one registered repo
|
|
repo set-base-ref Set the repo's default base ref for future worktrees
|
|
repo search-refs Search branch/tag refs within a repo
|
|
|
|
Worktrees:
|
|
worktree list List Orca-managed worktrees
|
|
worktree show Show one worktree
|
|
worktree current Show the Orca-managed worktree for the current directory
|
|
worktree create Create a new Orca-managed worktree
|
|
worktree set Update Orca metadata for a worktree
|
|
worktree rm Remove a worktree from Orca and git
|
|
worktree ps Show a compact orchestration summary across worktrees
|
|
|
|
Files:
|
|
file open Open a workspace file in the Orca editor
|
|
file diff Open a workspace file diff in the Orca editor
|
|
file open-changed Open all git-changed files for a workspace
|
|
|
|
Terminals:
|
|
terminal list List live Orca-managed terminals
|
|
terminal show Show terminal metadata and preview
|
|
terminal read Read bounded terminal output
|
|
terminal send Send input to a live terminal
|
|
terminal wait Wait for a terminal condition (exit, tui-idle)
|
|
terminal stop Stop terminals for a worktree
|
|
terminal create Create a terminal session in a worktree
|
|
terminal rename Set or clear the title of a terminal tab
|
|
terminal split Split an existing terminal pane
|
|
terminal switch Bring a terminal tab to the foreground
|
|
terminal focus Alias for terminal switch
|
|
terminal close Close a terminal pane (or tab if last pane)
|
|
|
|
Orchestration:
|
|
orchestration send Send an inter-agent message
|
|
orchestration check Check messages for a terminal
|
|
orchestration reply Reply to a message
|
|
orchestration inbox Show all messages across recipients
|
|
orchestration task-create Create an orchestration task
|
|
orchestration task-list List orchestration tasks
|
|
orchestration task-update Update a task status
|
|
orchestration dispatch Dispatch a task to a terminal
|
|
orchestration dispatch-show Show dispatch context for a task
|
|
orchestration run Start the coordinator loop
|
|
orchestration run-stop Stop the active coordinator run
|
|
orchestration gate-create Create a decision gate blocking a task
|
|
orchestration gate-resolve Resolve a pending decision gate
|
|
orchestration gate-list List decision gates
|
|
orchestration reset Reset orchestration state
|
|
|
|
Computer Use:
|
|
computer permissions Open the macOS permission setup for computer-use
|
|
computer list-apps List running apps available to computer-use
|
|
computer list-windows List visible windows for a target app
|
|
computer get-app-state Capture a compact accessibility snapshot of an app
|
|
computer click Click an app element or window coordinate
|
|
computer perform-secondary-action Run an advertised accessibility action
|
|
computer scroll Scroll an app element
|
|
computer drag Drag between app elements or window coordinates
|
|
computer type-text Type literal text at the current app focus
|
|
computer press-key Press a key using xdotool-style syntax
|
|
computer hotkey Press a shortcut combination such as CmdOrCtrl+A
|
|
computer paste-text Paste text through the native clipboard path
|
|
computer set-value Set the value of a settable app element
|
|
|
|
Browser Automation:
|
|
tab create Create a new browser tab (navigates to --url)
|
|
tab list List open browser tabs
|
|
tab show Show one browser tab by page id
|
|
tab current Show the current browser tab
|
|
tab profile list List browser session profiles
|
|
tab profile create Create a browser session profile
|
|
tab profile delete Delete a browser session profile
|
|
tab profile set Switch a browser tab to a different profile
|
|
tab profile show Show the profile bound to a browser tab
|
|
tab profile use-default Switch a browser tab back to the default profile
|
|
tab profile clone Clone a browser tab into another profile
|
|
tab switch Switch the active browser tab by --index or --page
|
|
tab close Close a browser tab by --index/--page or the current tab
|
|
snapshot Accessibility snapshot with element refs (e.g. @e1, @e2)
|
|
goto Navigate the active tab to --url
|
|
click Click element by --element ref
|
|
fill Clear and fill input by --element ref with --value
|
|
type Type --input text at the current focus (no element needed)
|
|
select Select dropdown option by --element ref and --value
|
|
hover Hover element by --element ref
|
|
keypress Press a key (e.g. --key Enter, --key Tab)
|
|
scroll Scroll --direction (up/down) by --amount pixels
|
|
back Navigate back in browser history
|
|
reload Reload the active browser tab
|
|
screenshot Capture viewport screenshot (--format png|jpeg)
|
|
eval Evaluate --expression JavaScript in the page context
|
|
wait Wait for page idle or --timeout ms
|
|
check Check a checkbox by --element ref
|
|
uncheck Uncheck a checkbox by --element ref
|
|
focus Focus an element by --element ref
|
|
clear Clear an input by --element ref
|
|
drag Drag --from ref to --to ref
|
|
upload Upload --files to a file input by --element ref
|
|
dblclick Double-click element by --element ref
|
|
forward Navigate forward in browser history
|
|
scrollintoview Scroll --element into view
|
|
get Get element property (--what: text, html, value, url, title)
|
|
is Check element state (--what: visible, enabled, checked)
|
|
inserttext Insert text without key events
|
|
mouse move Move mouse to --x --y coordinates
|
|
mouse down Press mouse button
|
|
mouse up Release mouse button
|
|
mouse wheel Scroll wheel --dy [--dx]
|
|
find Find element by locator (--locator role|text|label --value <v>)
|
|
set device Emulate device (--name "iPhone 12")
|
|
set offline Toggle offline mode (--state on|off)
|
|
set headers Set HTTP headers (--headers '{"key":"val"}')
|
|
set credentials Set HTTP auth (--user <u> --pass <p>)
|
|
set media Set color scheme (--color-scheme dark|light)
|
|
clipboard read Read clipboard contents
|
|
clipboard write Write --text to clipboard
|
|
dialog accept Accept browser dialog (--text for prompt response)
|
|
dialog dismiss Dismiss browser dialog
|
|
storage local get Get localStorage value by --key
|
|
storage local set Set localStorage --key --value
|
|
storage local clear Clear localStorage
|
|
storage session get Get sessionStorage value by --key
|
|
storage session set Set sessionStorage --key --value
|
|
storage session clear Clear sessionStorage
|
|
download Download file via --selector to --path
|
|
highlight Highlight --selector on page
|
|
exec Run any agent-browser command (--command "...")
|
|
|
|
Common Commands:
|
|
orca open [--json]
|
|
orca serve [--port <port>] [--pairing-address <host>] [--mobile-pairing] [--no-pairing] [--json]
|
|
orca status [--json]
|
|
orca diagnostics memory [--json]
|
|
orca environment add --name <name> --pairing-code <code> [--json]
|
|
orca environment list [--json]
|
|
orca environment show --environment <selector> [--json]
|
|
orca environment rm --environment <selector> [--json]
|
|
orca worktree list [--repo <selector>] [--limit <n>] [--json]
|
|
orca worktree create --name <name> [--repo <selector>] [--agent <id>] [--prompt <text>] [--setup run|skip|inherit] [--base-branch <ref>] [--issue <number>] [--comment <text>] [--parent-worktree <selector>] [--no-parent] [--run-hooks] [--activate] [--json]
|
|
orca worktree show --worktree <selector> [--json]
|
|
orca worktree current [--json]
|
|
orca worktree set --worktree <selector> [--display-name <name>] [--issue <number|null>] [--comment <text>] [--workspace-status <id>] [--parent-worktree <selector>|--no-parent] [--json]
|
|
orca worktree rm --worktree <selector> [--force] [--run-hooks] [--json]
|
|
orca worktree ps [--limit <n>] [--json]
|
|
orca file open <path> [--worktree <selector>] [--json]
|
|
orca file diff <path> [--staged] [--worktree <selector>] [--json]
|
|
orca file open-changed [--mode edit|diff|both] [--worktree <selector>] [--json]
|
|
orca terminal list [--worktree <selector>] [--limit <n>] [--json]
|
|
orca terminal show [--terminal <handle>] [--json]
|
|
orca terminal read [--terminal <handle>] [--cursor <n>] [--limit <n>] [--json]
|
|
orca terminal send [--terminal <handle>] [--text <text>] [--enter] [--interrupt] [--json]
|
|
orca terminal wait [--terminal <handle>] --for exit|tui-idle [--timeout-ms <ms>] [--json]
|
|
orca terminal stop --worktree <selector> [--json]
|
|
orca terminal create [--worktree <selector>] [--title <name>] [--command <text>] [--focus] [--json]
|
|
orca terminal split [--terminal <handle>] [--direction horizontal|vertical] [--json]
|
|
orca terminal switch [--terminal <handle>] [--json]
|
|
orca terminal close [--terminal <handle>] [--json]
|
|
orca repo list [--json]
|
|
orca repo add --path <path> [--json]
|
|
orca repo show --repo <selector> [--json]
|
|
orca repo set-base-ref --repo <selector> --ref <ref> [--json]
|
|
orca repo search-refs --repo <selector> --query <text> [--limit <n>] [--json]
|
|
|
|
Selectors:
|
|
--repo <selector> Registered repo selector such as id:<id>, name:<name>, or path:<path>
|
|
--worktree <selector> Worktree selector such as id:<id>, branch:<branch>, issue:<number>, path:<path>, or active/current
|
|
--terminal <handle> Runtime-issued terminal handle returned by \`orca terminal list --json\`
|
|
--parent-worktree <selector> Parent worktree selector; create infers a child of the caller/current worktree by default
|
|
--no-parent Force no parent lineage for unrelated worktree creation/update
|
|
|
|
Terminal Send Options:
|
|
--text <text> Text to send to the terminal
|
|
--enter Append Enter after sending text
|
|
--interrupt Send as an interrupt-style input when supported
|
|
|
|
Wait Options:
|
|
--for exit Wait until the target terminal exits
|
|
--timeout-ms <ms> Maximum wait time before timing out
|
|
|
|
Output Options:
|
|
--json Emit machine-readable JSON instead of human text
|
|
--pairing-code <code> Connect to a remote Orca runtime using an orca://pair?... code
|
|
--environment <selector> Connect using a saved environment id or name
|
|
--help Show this help message
|
|
|
|
Behavior:
|
|
Most commands require a running Orca runtime. If Orca is not open yet, run \`orca open\` first.
|
|
Remote runtime access can also be supplied with ORCA_PAIRING_CODE or ORCA_ENVIRONMENT.
|
|
Use selectors for discovery and handles for repeated live terminal operations.
|
|
|
|
Browser Workflow:
|
|
1. Create or navigate: orca tab create --url https://example.com
|
|
orca goto --url https://example.com
|
|
2. Inspect the page: orca snapshot
|
|
(Returns an accessibility tree with element refs like e1, e2, e3)
|
|
For concurrent workflows, prefer: orca tab list --json
|
|
then reuse tabs[].browserPageId with --page <id> on later commands.
|
|
3. Interact: orca click --element e2
|
|
orca fill --element e5 --value "search query"
|
|
orca keypress --key Enter
|
|
4. Re-inspect: orca snapshot
|
|
(Element refs change after navigation — always re-snapshot before interacting)
|
|
|
|
Browser Options:
|
|
--element <ref> Element ref from snapshot (e.g. @e3)
|
|
--url <url> URL to navigate to
|
|
--value <text> Value to fill or select
|
|
--input <text> Text to type at current focus (no element needed)
|
|
--expression <js> JavaScript expression to evaluate
|
|
--key <key> Key to press (Enter, Tab, Escape, Control+a, etc.)
|
|
--direction <dir> Scroll direction: up or down
|
|
--amount <pixels> Scroll distance in pixels (default: viewport height)
|
|
--index <n> Tab index (from \`tab list\`)
|
|
--page <id> Stable browser page id (preferred for concurrent workflows)
|
|
--profile <id> Browser profile id
|
|
--show-profile Include the tab's browser profile in text output
|
|
--format <png|jpeg> Screenshot image format
|
|
--from <ref> Drag source element ref
|
|
--to <ref> Drag target element ref
|
|
--files <path,...> Comma-separated file paths for upload
|
|
--timeout <ms> Wait timeout in milliseconds
|
|
--worktree <selector> Scope commands to a specific worktree's browser tabs
|
|
|
|
Examples:
|
|
$ orca open
|
|
$ orca status --json
|
|
$ orca diagnostics memory --json
|
|
$ orca repo list
|
|
$ orca worktree create --name agent-task --agent codex --prompt "hi"
|
|
$ orca worktree create --repo name:orca --name cli-test-1 --issue 273
|
|
$ orca worktree show --worktree branch:Jinwoo-H/cli
|
|
$ orca worktree current
|
|
$ orca worktree set --worktree active --comment "waiting on review"
|
|
$ orca worktree ps --limit 10
|
|
$ orca file open-changed --mode diff
|
|
$ orca file open src/App.tsx
|
|
$ orca terminal list --worktree path:/Users/me/orca/workspaces/orca/cli-test-1 --json
|
|
$ orca terminal send --terminal term_123 --text "hi" --enter
|
|
$ orca terminal wait --terminal term_123 --for exit --timeout-ms 60000 --json
|
|
$ orca tab current --json
|
|
$ orca tab show --page page_123 --json
|
|
$ orca tab create --url https://example.com --profile work
|
|
$ orca tab profile clone --page page_123 --profile work --json
|
|
$ orca snapshot
|
|
$ orca click --element e3
|
|
$ orca fill --element e5 --value "hello"
|
|
$ orca goto --url https://example.com/login
|
|
$ orca keypress --key Enter
|
|
$ orca eval --expression "document.title"
|
|
$ orca tab list --json`
|
|
|
|
export function printHelp(specs: CommandSpec[], commandPath: string[] = []): void {
|
|
const exactSpec = findCommandSpec(specs, commandPath)
|
|
if (exactSpec) {
|
|
console.log(formatCommandHelp(exactSpec))
|
|
return
|
|
}
|
|
|
|
if (isCommandGroup(commandPath)) {
|
|
console.log(formatGroupHelp(specs, commandPath[0]))
|
|
return
|
|
}
|
|
|
|
if (commandPath.length > 0) {
|
|
console.log(`Unknown command: ${commandPath.join(' ')}\n`)
|
|
}
|
|
|
|
console.log(ROOT_HELP_TEXT)
|
|
}
|
|
|
|
export function formatCommandHelp(spec: CommandSpec): string {
|
|
const lines = [`orca ${spec.path.join(' ')}`, '', `Usage: ${spec.usage}`, '', spec.summary]
|
|
const displayedFlags = supportsBrowserPageFlag(spec.path)
|
|
? [...spec.allowedFlags, 'page']
|
|
: spec.allowedFlags
|
|
|
|
if (displayedFlags.length > 0) {
|
|
lines.push('', 'Options:')
|
|
for (const flag of displayedFlags) {
|
|
lines.push(` ${formatFlagHelp(flag)}`)
|
|
}
|
|
}
|
|
|
|
if (spec.notes && spec.notes.length > 0) {
|
|
lines.push('', 'Notes:')
|
|
for (const note of spec.notes) {
|
|
lines.push(` ${note}`)
|
|
}
|
|
}
|
|
|
|
if (spec.examples && spec.examples.length > 0) {
|
|
lines.push('', 'Examples:')
|
|
for (const example of spec.examples) {
|
|
lines.push(` $ ${example}`)
|
|
}
|
|
}
|
|
|
|
return lines.join('\n')
|
|
}
|
|
|
|
export function formatGroupHelp(specs: CommandSpec[], group: string): string {
|
|
const groupSpecs = specs.filter((spec) => spec.path[0] === group)
|
|
const lines = [`orca ${group}`, '', `Usage: orca ${group} <command> [options]`, '', 'Commands:']
|
|
for (const spec of groupSpecs) {
|
|
lines.push(` ${spec.path.slice(1).join(' ').padEnd(18)} ${spec.summary}`)
|
|
}
|
|
lines.push('', `Run \`orca ${group} <command> --help\` for command-specific usage.`)
|
|
return lines.join('\n')
|
|
}
|
|
|
|
export function formatFlagHelp(flag: string): string {
|
|
const helpByFlag: Record<string, string> = {
|
|
agent: '--agent <id> Launch a known TUI agent in the first terminal',
|
|
'base-branch': '--base-branch <ref> Base branch/ref to create the worktree from',
|
|
command: '--command <text> Command to run in the terminal on startup',
|
|
comment: '--comment <text> Comment stored in Orca metadata',
|
|
cursor: '--cursor <n> Line cursor from a previous read (returns only new output)',
|
|
action: '--action <name> Secondary accessibility action name',
|
|
activate: '--activate Reveal the new worktree in the Orca app',
|
|
app: '--app <app> App name, bundle ID, or pid:N',
|
|
direction:
|
|
'--direction <dir> Direction: up|down|left|right for scroll, horizontal|vertical for split',
|
|
'display-name': '--display-name <name> Override the Orca display name',
|
|
'element-index': '--element-index <n> Element index from get-app-state',
|
|
title: '--title <text> Custom title for the terminal tab (omit to reset)',
|
|
enter: '--enter Append Enter after sending text',
|
|
force: '--force Force worktree removal when supported',
|
|
focus: '--focus Reveal the created terminal session in Orca',
|
|
for: '--for exit|tui-idle Wait condition to satisfy',
|
|
'from-element-index': '--from-element-index <n> Source element index from get-app-state',
|
|
'from-x': '--from-x <x> Source window-local x coordinate',
|
|
'from-y': '--from-y <y> Source window-local y coordinate',
|
|
help: '--help Show this help message',
|
|
interrupt: '--interrupt Send as an interrupt-style input when supported',
|
|
issue: '--issue <number|null> Linked GitHub issue number',
|
|
json: '--json Emit machine-readable JSON',
|
|
key: '--key <key> Key or combo to press, e.g. Escape or CmdOrCtrl+L',
|
|
limit: '--limit <n> Maximum number of rows to return',
|
|
mode: '--mode <mode> Mode such as edit, diff, or both',
|
|
'mouse-button': '--mouse-button <btn> Mouse button: left, right, or middle',
|
|
name: '--name <name> Name for the new worktree or automation',
|
|
'no-parent': '--no-parent Force no parent lineage for unrelated work',
|
|
'no-screenshot': '--no-screenshot Skip screenshot capture after the operation',
|
|
pages: '--pages <n> Number of scroll pages',
|
|
'parent-worktree':
|
|
'--parent-worktree <selector> Parent selector; create infers the caller/current worktree by default',
|
|
path: '--path <path> Path argument for the command',
|
|
prompt: '--prompt <text> Prompt text for agent-backed commands',
|
|
query: '--query <text> Search text for matching refs',
|
|
ref: '--ref <ref> Base ref to persist for the repo',
|
|
repo: '--repo <selector> Repo selector such as id:<id>, name:<name>, or path:<path>',
|
|
'restore-window':
|
|
'--restore-window Bring the target app/window forward before the operation',
|
|
session: '--session <id> Snapshot namespace for a related computer-use workflow',
|
|
setup: '--setup run|skip|inherit Setup policy for repo-defined setup hooks',
|
|
terminal: '--terminal <handle> Runtime-issued terminal handle',
|
|
text: '--text <text> Text payload to send or type',
|
|
'text-stdin': '--text-stdin Read text payload from stdin',
|
|
'task-id': '--task-id <id> Task id to include in orchestration payload JSON',
|
|
'dispatch-id': '--dispatch-id <id> Dispatch id to include in orchestration payload JSON',
|
|
'files-modified': '--files-modified <csv> Comma-separated files for orchestration payload JSON',
|
|
'report-path': '--report-path <path> Report path to include in orchestration payload JSON',
|
|
phase: '--phase <text> Worker phase to include in orchestration payload JSON',
|
|
'timeout-ms': '--timeout-ms <ms> Maximum wait time before timing out',
|
|
'to-element-index': '--to-element-index <n> Destination element index from get-app-state',
|
|
'to-x': '--to-x <x> Destination window-local x coordinate',
|
|
'to-y': '--to-y <y> Destination window-local y coordinate',
|
|
worktree:
|
|
'--worktree <selector> Worktree selector such as id:<id>, branch:<branch>, issue:<number>, path:<path>, or active/current',
|
|
workspace: '--workspace <selector> Existing worktree selector for automation runs',
|
|
'workspace-status':
|
|
'--workspace-status <id> Board status id (defaults: todo, in-progress, in-review, completed)',
|
|
staged: '--staged Open staged source-control changes',
|
|
provider: '--provider <agent> Agent id such as codex, claude, or gemini',
|
|
trigger: '--trigger <schedule> Automation schedule preset, cron, or RRULE',
|
|
schedule: '--schedule <schedule> Alias for --trigger',
|
|
time: '--time <HH:MM> Time used with daily/weekdays/weekly presets',
|
|
day: '--day <0-6> Day used with weekly preset, Sunday=0',
|
|
timezone: '--timezone <tz> IANA timezone for the automation',
|
|
enabled: '--enabled Enable the automation',
|
|
disabled: '--disabled Disable the automation',
|
|
'reuse-session':
|
|
'--reuse-session Reuse the previous live session for existing-workspace runs',
|
|
'fresh-session': '--fresh-session Disable session reuse for future runs',
|
|
'workspace-mode': '--workspace-mode <mode> existing or new-per-run',
|
|
'missed-run-grace-minutes': '--missed-run-grace-minutes <n> Missed-run grace window',
|
|
'value-stdin': '--value-stdin Read set-value payload from stdin',
|
|
'window-id': '--window-id <id> Target a window id from list-windows',
|
|
'window-index': '--window-index <n> Target a window index from list-windows',
|
|
// Browser automation flags
|
|
element: '--element <ref> Element ref from snapshot (e.g. e3)',
|
|
url: '--url <url> URL to navigate to',
|
|
value: '--value <text> Value to fill or select',
|
|
input: '--input <text> Text to type at current focus',
|
|
expression: '--expression <js> JavaScript expression to evaluate',
|
|
amount: '--amount <pixels> Scroll distance in pixels',
|
|
index: '--index <n> Tab index to switch to',
|
|
page: '--page <id> Stable browser page id from `orca tab list --json`',
|
|
profile: '--profile <id> Browser profile id',
|
|
'show-profile': '--show-profile Include tab profile in text output',
|
|
format: '--format <png|jpeg> Screenshot image format'
|
|
}
|
|
|
|
return helpByFlag[flag] ?? `--${flag}`
|
|
}
|