feat(cli): select the Claude or Codex account from orca account select

[pawel-kotowski]

ELI5

The goal: run any of your Claude (or Codex) subscriptions on any workspace, on one machine or several, picked from the terminal.

This PR adds the missing terminal command for that: orca account select. Before, only the account menu in the Orca app could switch accounts, so a script that creates workspaces could not choose which subscription they run on.

How much of the goal this reaches depends on per-account Claude folders. They were reverted before release in #26638 and are being re-landed in #26801 (with the upgrade fixes from #26769). Until that merges, this PR covers different subscriptions on different machines, but not different subscriptions in parallel on one machine. See "What this gives today, and later" below.

What Changed

Before: orca account list showed Claude and Codex accounts by email only, and orca account select accepted only OpenCode or Devin.

After:

orca account list
#   system  System default
#   e694…  me@work.example (active)
#   4ea0…  me@other.example
orca account select --agent claude --account me@other.example   # id, email, or `system`
orca worktree create --name task --agent claude --prompt "..."   # starts on me@other.example

• orca account select --agent claude|codex --account <id|email|system> calls the runtime's existing accounts.selectClaude / accounts.selectCodex. These are the same methods the status-bar switcher and mobile already use, so there is no runtime or wire change.
• The CLI looks the account up in accounts.list first, matching emails case-insensitively. If one email belongs to several accounts (one sign-in in two organizations), it refuses and prints their ids instead of guessing which subscription to bill.
• orca account list now prints each Claude/Codex account's id and a system row, mirroring the OpenCode/Devin format.
• Updated the help text, root help, and CLI reference page.

What this gives today, and later

Setup	On current main	With per-account Claude folders (#26801)
Different subscriptions on different machines (laptop, devbox, other orca serve hosts)	✅ Works. Each Orca host has its own active account; run orca account select on each host.	✅ Works
Different subscriptions on one machine, in parallel	❌ Not possible. The machine has one shared Claude login, and switching moves every Claude session on it, running ones included.	✅ Works. Each workspace keeps the account it was started with, so "select, then create" is all a script needs.

So on current main this PR does less than it could: it makes the account a script runs on choosable, one account per machine at a time. Its full value — any subscription on any workspace — arrives when #26801 merges. Nothing in this PR would need to change then; the same select → worktree create flow simply stops affecting workspaces that are already running.

Why

The runtime has supported switching accounts over RPC for a long time; only the CLI was missing it. Coordinating agents and scripts already create workspaces with orca worktree create --agent claude, and choosing the subscription is the one step that still needed a person in the app.

Alternatives I considered and didn't take:

• A per-workspace --account flag on worktree create / terminal create. On current main it could only switch the whole machine and then launch. That would quietly move every other session too, and two launches at once would race. It makes sense as a small follow-up once Re-land Claude per-account folders (#24434, #26405) with the upgrade and proxy fixes #26801 lands.
• Honoring --environment to switch another machine's account from this one. The account commands deliberately run only on the local host today (see rejectAccountRemoteSelectionFlags), and changing that is a separate decision.
• Selecting by email only. Ids are needed for the multi-organization case, so both are accepted.

Linked Issue

Fixes #26875

Visual Proof

N/A — CLI-only change; output examples are above.

Testing

• I manually tested these changes locally

• Automated tests added/updated, or explained why not below

• New provider-account-selection.test.ts:

  • select by email (case-insensitive) and by id; system → null;
  • an ambiguous email is refused with its ids, and an unknown account is refused without switching;
  • a missing --account is refused;
  • Codex selected from a WSL bridge uses accounts.selectCodexForTarget;
  • Claude system from WSL is refused, since the Claude RPC has no target and would reset the Windows host;
  • OpenCode/Devin still route to accounts.selectData;
  • the list format.

• All src/cli tests pass (142 files, 1685 tests). tc:cli, tc:node, and check:code-quality:changed are clean. The branch is merged with the latest main.

• Real switches on macOS, against an Orca built from main just before Revert Claude per-account folders (#24434, #26405) before release #26638 (so it still had per-account folders), with three saved Claude accounts:

  • selected account B, then orca worktree create --agent claude: the new agent ran on account B (checked with claude auth status against its config folder);
  • selected account A and created another workspace: it ran on account A, while the first one stayed on B, in parallel;
  • selecting an account whose sign-in had expired was refused ("Sign in to this Claude account again before selecting it"), and nothing switched;
  • switched back to the original account afterwards.

• Not yet tested against a runtime built from current main (no per-account folders). There, the same command drives the same switch the status-bar menu does.

AI Disclosure

Written with Claude Code (Claude Opus 5.5), reviewed by me.

Review

Agent skill upstream boundary

• Not applicable, or this change copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.

Notes

• Security: uses the existing accounts-admin RPCs; the CLI stays pinned to the local runtime and still rejects --environment / --pairing-code.
• Windows/WSL: Codex selection from a WSL bridge targets that distro. Claude system from WSL is refused rather than silently resetting the host.
• SSH/remote: account commands remain host-local; run them on each machine whose account you want to set.
• Overlap with Re-land Claude per-account folders (#24434, #26405) with the upgrade and proxy fixes #26801: both touch account-list-format.ts, account.ts and account.test.ts. The conflicts are small: Re-land Claude per-account folders (#24434, #26405) with the upgrade and proxy fixes #26801 adds a "sign in again" note to each account line, and this PR adds the id. I've already combined the two in a local build (tests pass) and will rebase whichever lands second.
• Backwards compatibility: no new RPCs or params. The account list human output gains an id column and a system row; --json output is unchanged.

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) — ran the CLI subsets above; CI covers the rest

🤖 Generated with Claude Code

[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: 341bc3c5-6645-4204-abaa-23edb193bd89

---

📥 Commits

Reviewing files that changed from the base of the PR and between 93a6b1a and 7668947.

---

📒 Files selected for processing (10)

• docs/site/content/docs/cli/reference.mdx
• src/cli/handlers/account-list-format.ts
• src/cli/handlers/account.ts
• src/cli/handlers/data-account-commands.ts
• src/cli/handlers/provider-account-selection.test.ts
• src/cli/handlers/provider-account-selection.ts
• src/cli/help.ts
• src/cli/root-help-text-primary.ts
• src/cli/root-help-text-secondary.ts
• src/cli/specs/account.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

The CLI now supports selecting Claude and Codex accounts by ID or email, or selecting the system account. Claude system-account selection is rejected for WSL targets, and Codex selection can target a configured WSL distro. Account output includes IDs and a system-default row. The command help, specification, and guide describe the expanded selection options and their effect on subsequently launched agents.

---

Priority: ⬇️ Low

Merge Risk: ⚪ Minimal · up to 76689

No actionable merge-blocking issue is established. The change is mergeable after normal checks.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 57.14% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 9 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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.
Title check		The title clearly and concisely describes the main change: adding Claude and Codex account selection to orca account select.
Description check		The description follows the repository template and covers the user impact, implementation, rationale, linked issue, testing, platform considerations, compatibility, and checklist status. It also expl…

---

Full details: Docstring Coverage

Explanation

Docstring coverage is 57.14% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 9 files. (1 skipped: 1 unsupported.)

---

---

• Fix all pre-merge checks with AI

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

---

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.}