[brynnclaw]

ELI5

When you asked the Orca CLI for help on a command like orca terminal send --help, four of the options were listed as bare names, with nothing after them saying what they do or what value they take. This change gives each of them a one-line description, so --help alone tells you what to pass.

What Changed

Before, orca terminal send --help:

Options:
  --help                 Show this help message
  --json                 Emit machine-readable JSON
  --pairing-code
  --environment
  --terminal <handle>  Runtime-issued terminal handle
  --text <text>          Text payload to send or type
  --enter                Append Enter after sending text
  --interrupt            Send as an interrupt-style input when supported
  --wait-submit
  --retry-request

After:

Options:
  --help                 Show this help message
  --json                 Emit machine-readable JSON
  --pairing-code <code>  Connect to a remote Orca runtime using an orca://pair?... code
  --environment <selector> Connect using a saved environment id or name
  --terminal <handle>  Runtime-issued terminal handle
  --text <text>          Text payload to send or type
  --enter                Append Enter after sending text
  --interrupt            Send as an interrupt-style input when supported
  --wait-submit <seconds> Observe this accepted prompt without resending it (max 3600; needs --text --enter, no --interrupt)
  --retry-request <id>   Resume the request Orca reported this ID for instead of starting a new one; idempotent

--pairing-code and --environment are global flags, so every command's --help listed them bare. They now carry a description in every command's local --help. --retry-request gains one on terminal send and on every orchestration command that accepts it.

The SSH remote CLI shim keeps its own static copy of the help for linear issue and linear search (src/main/ssh/ssh-remote-linear-read-help.ts). That copy still prints the two selection flags bare. It is generated separately and is left for a follow-up.

Mechanism. Per-command help is rendered by formatCommandHelp in src/cli/help.ts. For each allowed flag it first checks per-command overrides (src/cli/command-scoped-flag-help.ts and the inline chain in help.ts), then falls back to the shared map FLAG_HELP_TEXT in src/cli/flag-help-text.ts, and prints just --<flag> when the flag is in neither. None of these four flags had an entry, so they hit that bare fallback.

• src/cli/flag-help-text.ts: four new entries, each checked against the code.
  • --pairing-code and --environment use the same wording as the root orca --help, so the two help screens agree.
  • --wait-submit starts from the root help's phrase ("Observe this accepted prompt without resending it"). It adds what src/cli/handlers/terminal-send.ts enforces: at most 3600 seconds, and only with --text and --enter, without --interrupt.
  • --retry-request does not reuse the root help's wording ("Resume the same durable prompt request after an ambiguous transport failure"). That wording names only one of the cases where Orca asks for the flag. The CLI also asks for it when a submitted prompt was not observed (src/cli/terminal-format.ts), and the orchestration commands share the flag. The new row says what holds in every case: it resumes the request Orca issued the ID for, idempotently (src/cli/retry-request-flag.ts, src/shared/orchestration-retry-request-id.ts).
• src/cli/command-scoped-flag-help.ts: some commands only ever run on this machine and never route to a remote runtime, so the global "Connect ..." wording would be wrong there.
  • environment add, show and rm: the flag the command reads gets its own meaning. --pairing-code on add is the code to save; --environment on show/rm is the saved environment to show or remove. The flag the command ignores says "Not used".
  • Fifteen commands throw an error on either flag through rejectRemoteSelectionFlags, so they share one pair of rows that says "Rejected; this command only runs on this machine": environment list, host list, account add/list, artifacts list/share/update/unshare/delete, profile state exports/rollback and agent hooks prepare-codex/status/off/on. For example, orca account list --help used to print the global "Connect using a saved environment id or name" row next to Notes saying the flag is rejected.
  • Three commands, serve, vm recipe doctor and agent-context, drop both flags without an error (src/cli/index.ts turns them to null for these commands) and run on this machine. They share one pair of rows that says "Not used; this command only runs on this machine".

No parsing, validation, routing or RPC behaviour changes; this is help text only.

Why

The linked issue reports that a user whose terminal send to another server failed could not learn from --help that --environment was the missing piece, because the flag was printed with no description. The same bare rendering applied to --pairing-code, --wait-submit and --retry-request.

Adding entries to the existing FLAG_HELP_TEXT map is the smallest change that follows how every other flag is described today. A larger alternative, moving per-flag descriptions into each command spec, is a design change of its own and is not needed to fix these four rows. Scoped overrides are used only where a global description would be untrue.

Linked Issue

Part of #19016 (part 1: the missing --help descriptions). The issue also suggests showing --environment in the usage line. That half is left out on purpose: usage lines across the CLI list [--json] but none of the global selection flags, so adding them is a separate, CLI-wide change. The other parts of the issue are not addressed here: the terminal_handle_stale error wording, and terminal create returning before the shell accepts input.

Related open PR: #17403 moves per-flag help into the command specs and backfills the orchestration commands. The two PRs change different files: this one touches neither help.ts nor any spec file, and #17403 touches neither file changed here. Whichever lands second only needs to check that each flag keeps one description.

Visual Proof

N/A: CLI help text only, no UI. The before/after --help output is shown above.

Testing

• I manually tested these changes locally (rendered the help output before and after, shown above)
• Automated tests added/updated, or explained why not below

New src/cli/flag-help-text.test.ts (10 tests). 9 of them fail on main (every row above rendered bare); the tenth checks the test's own row reader. All 10 pass with this change:

• every global flag (--help, --json, --pairing-code, --environment) has a description;
• terminal send --help describes all four flags, with the value placeholders its usage line uses;
• the four new rows are asserted verbatim: the 3600-second cap, no resend, and the --text / --enter / --interrupt conditions for --wait-submit; idempotent resume for --retry-request; the selector kind for --environment; and the code format for --pairing-code. Any change to what a row states fails the test and has to be made on purpose;
• every command that accepts one of the four flags renders a description for it (passthrough commands, which render no Options block, are skipped);
• environment add, show and rm show their own meaning for the flag they read, and "Not used" for the one they ignore;
• all fifteen commands that throw on the selection flags say so in both rows;
• serve, vm recipe doctor and agent-context say "Not used" in both rows;
• the row reader the tests use returns no description for a row that has only a value placeholder (such as --environment <selector>), so a row like that cannot pass as described.

For the latest revision (the "Not used" rows and the row-reader fix), on the same machine and limits as below: the test file passes (10 of 10); the "Not used" test fails on the previous revision, and the row-reader test fails with the previous reader. The type check of the three changed files passes, as does pnpm run typecheck:cli. oxlint with each of the repo's lint configs (default, react-doctor, code-quality native, anti-slop, type-aware code-quality), oxfmt --check on the changed files, and check:max-lines-ratchet all pass. That revision only touches src/cli/command-scoped-flag-help.ts and the test file. The wider runs below were made on the revision before it.

Verified on Linux with Node 24 and pnpm 12, on a shared machine where every command ran under a 4 GB memory and 580 s time limit. Two pieces did not fit, and both need more than 4 GB: the full node/web typecheck (the repo's own runner budgets 7 GiB for the node project) and the whole-repo type-aware lint. The narrowed runs below cover everything this change touches.

• pnpm lint: all 16 sub-steps pass. The type-aware oxlint step was run on all of src/cli with the repo's config, because the whole-repo run needs more than 4 GB.
• pnpm typecheck: pnpm run typecheck:cli passes. That is the only TypeScript project that includes src/cli, and nothing outside src/cli imports the changed modules.
• pnpm test: all of src/cli passes (134 files, 1423 passed, 4 skipped), as do src/main/ssh and src/main/cli, which cover the SSH remote CLI shim (212 files, 2982 passed, 37 skipped). The full suite does not finish within the 4 GB / 580 s limits here. The only failures it reported were in unrelated test files. Account-auth, skills and relay tests fail identically on main on this machine because of local host configuration. A few load-sensitive timing tests (which ones varies by run) timed out under load and pass when run alone.
• pnpm build: every step except its opening full typecheck passes: build:relay, build:cli, build:electron-vite, verify:built-skills-cli, build:web-from-renderer, build:mobile-web (after installing mobile/) and build:native. build:electron-vite sits at the 4 GB edge on this machine: one run was stopped by the memory limit while other work was running, and the retries passed. The built CLI prints the help shown above.

CI runs the full commands.

AI Disclosure

Claude Opus 5.5 (claude-opus-5-5), Anthropic. The change, the tests and this description were written by the model in an automation session.

Review

AI coding-agent review summary:

• Cross-platform (macOS, Linux, Windows): only string constants and a pure-function unit test; no paths, shells or platform branches.
• SSH / remote / local: no routing change. The new text describes the existing remote-selection behaviour (--environment and --pairing-code pick the runtime that answers). Commands pinned to the local runtime keep their current behaviour. Where such a command throws on either flag, drops both without an error (serve, vm recipe doctor, agent-context), or on the environment commands ignores one, the help now says so.
• Agent and integration support: provider-neutral. --wait-submit and --retry-request apply to any agent prompt sent through terminal send, and --retry-request to the orchestration mutations that already accept it.
• Performance: none; help strings are static and are only read when --help is rendered.
• Security: no new input handling. Descriptions contain no secrets or examples of real pairing codes.
• Known limit, out of scope: the SSH shim's static help copy mentioned above still prints the two selection flags bare.

Agent skill upstream boundary

• Not applicable, or this change follows docs/reference/agent-skill-sharing-upstream-boundary.md and copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.

Notes

No impact on security, cross-platform support, remote SSH, mobile, backwards compatibility or performance: the change is limited to help text and a unit test.

Checklist

• This PR is small and focused
• I explained what changed and why (ELI5, the user-facing before/after, the mechanism, and why over the alternatives)
• Before/after screenshots or videos attached for UI changes, or N/A with reason
• Self-reviewed for correctness, security, and performance
• Cross-platform, SSH/remote, and path/shortcut impact considered (or N/A)
• pnpm lint, pnpm typecheck, pnpm test, and pnpm build pass (or CI will cover; local preferred) (locally: the parts that fit this machine, listed under Testing; CI covers the rest)

🤖 Generated with Claude Code

[greptile-apps]

Confidence Score: 5/5

[Low risk] Adds help text for four command-line flags.

The PR appears safe to merge; no outstanding or new actionable findings remain.

Summary

The PR adds descriptions for four CLI flags and command-specific wording where remote selection is rejected or ignored. The changes since the previous review address both earlier findings; no new actionable issue was identified.

_{Reviews (2) · Last reviewed commit: "fix(cli): mark the selection flags on lo..."}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: fe341fb2-0cf6-4be0-af98-13957772ac1a

---

📥 Commits

Reviewing files that changed from the base of the PR and between 42ea8d160bdd86aeb6a0255991d750bd41fc1acc and 160f81a.

---

📒 Files selected for processing (3)

• src/cli/command-scoped-flag-help.ts
• src/cli/flag-help-text.test.ts
• src/cli/flag-help-text.ts

---

🚧 Files skipped from review as they are similar to previous changes (2)

• src/cli/command-scoped-flag-help.ts
• src/cli/flag-help-text.ts

---

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

---

📝 Walkthrough

Walkthrough

CLI flag help now includes shared descriptions for --environment, --pairing-code, --retry-request, and --wait-submit. Command-specific help describes pairing-code and environment flags as rejected, unused, or selectors for locally saved environments. Tests check flag descriptions, value placeholders, and command-specific wording.

---

Priority: ⬇️ Low

Merge Risk: ⚪ Minimal · up to 160f8

The help updates are mergeable after normal checks; no actionable behavior regression is established.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 3 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check		The title clearly and concisely identifies the main change: adding help text for four CLI flags.
Description check		The description is complete and aligned with the template. It explains the user impact, implementation, rationale, linked issue, testing, scope, limitations, and checklist status.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

---

---

• Fix all pre-merge checks with AI

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}

[pullfrog]

✅ No new issues found.

Reviewed changes

• Flag descriptions — FLAG_HELP_TEXT gains one-line entries for --environment, --pairing-code (global, matching the root orca --help wording), --wait-submit, and --retry-request, fixing the bare-name rendering reported in #19016.
• Scoped overrides — command-scoped-flag-help.ts now gives the 15 commands whose handlers call rejectRemoteSelectionFlags a "Rejected; this command only runs on this machine" pair, and gives environment add/show/rm a local meaning for the flag each reads plus "Not used" for the flag it ignores.
• Tests — new flag-help-text.test.ts (8 tests) pins every global flag's description, the four new rows verbatim, their value placeholders, and the scoped meanings; it would fail on main, where those rows render bare.

The mechanism is right: formatCommandHelp resolves scoped → inline → FLAG_HELP_TEXT → bare, and the four flags had no map entry. I verified every command in the rejecting list actually throws via rejectRemoteSelectionFlags (artifacts.ts:165/178/187/196/207, account.ts:319/326, profile-state.ts:97/102, agent-hooks.ts:200/225/237/242, environment.ts:68/106), that the global wording matches the root help (root-help-text-secondary.ts:107-108, :95-96), and that the new plus related spec/flag tests pass locally.

The two boundaries the PR calls out — the SSH shim's static linear help copy and the three silently-pinned commands (serve, vm recipe doctor, agent-context) that still show the general "Connect…" row — are accurately described as follow-ups and out of scope here.

  ^{｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

[brynnclaw]

Re: greptile summary

Thanks. Both findings are fixed in 42ea8d1; the details are in the two inline threads.

[brynnclaw]

Re: coderabbit summary, pre-merge check "Docstring Coverage"

Thanks. Orca doesn't set a docstring threshold: AGENTS.md asks for short comments only where the code isn't obvious, and the three functions here are small test helpers, so we're leaving them as they are.

[brynnclaw]

Re: pullfrog review, "No new issues"

Thanks for checking the handler list. One update since this review: the three commands you noted as a follow-up (serve, vm recipe doctor, agent-context) now say "Not used; this command only runs on this machine" for both selection flags (42ea8d1).

[pullfrog]

✅ No new issues found.

Reviewed changes

• Scoped selection-flag help for the pinned commands — command-scoped-flag-help.ts now derives one shared "Rejected; this command only runs on this machine" pair for all 15 handlers that call rejectRemoteSelectionFlags, and a "Not used; …" pair for the three commands (serve, vm recipe doctor, agent-context) that shouldIgnoreRemoteSelection drops the flags for without an error. The lists match the pinned families exactly, and no other pinned command is left on the global "Connect …" wording.
• Verbatim row pinning — the test now asserts the four new descriptions with toBe instead of substring matches, so a row that keeps a keyword but states the opposite fails.
• Placeholder-only rows read as undescribed — optionDescription no longer lets --environment <selector> capture <selector> as a description, with a self-test covering the bare, trailing-space, and described cases.

This addresses both greptile-apps threads from the prior round (misleading global rows on the silently-pinned commands; the placeholder passing the description check), and the new test passes at head 42ea8d16.

  ^{｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}