CLI

Getting Started

Install the Orca CLI, sign in, and run your first commands.

The Orca CLI (orca) is a single static binary that uses the same backend as the desktop app. Use it to manage workspaces, tasks, automations, and the local host server from a terminal or CI. Scripts and other agents can also dispatch agent tasks with it. orca is an alias for orca: every install below puts both on PATH.

Install

Desktop app

The desktop app includes the Orca CLI. When the app launches, it writes app-managed shims at ~/.orca/bin/orca and ~/.orca/bin/orca, and Orca terminals prepend ~/.orca/bin to PATH automatically.

To use the bundled CLI from a normal shell, add the directory to your shell profile:

export PATH="$HOME/.orca/bin:$PATH"

Standalone install

curl -fsSL https://orca.marcofaul.de/cli/install.sh | sh

The script auto-detects your platform (macOS on Apple Silicon or Intel, Linux on x64 or arm64), installs Orca under ~/orca by default, and adds ~/orca/bin to your shell PATH.

Homebrew

brew install MarcoFaul/tap/orca

Sign in

orca auth login

The CLI starts a loopback callback server on 127.0.0.1:51789 (or 51790 through 51793 if earlier ports are busy), opens your browser to the consent page, and stores a session token at ~/.orca/config.json.

If you belong to multiple organizations, the CLI asks you to pick one. To skip the prompt:

orca auth login --organization acme

In CI or other non-interactive environments with no browser, use an API key. Store it once with auth login --api-key:

orca auth login --api-key sk_live_…
orca auth whoami

Or set ORCA_API_KEY without writing anything to disk:

export ORCA_API_KEY=sk_live_…
orca auth whoami

API keys are issued from the Settings → API Keys page in the desktop app.

Verify your session

orca auth whoami
Signed in as Satya Patel (you@example.com)
Organization: Acme
Auth: Session (expires in 32 min)

Explore interactively

Bare orca in a terminal opens an interactive command browser. Use the arrow keys to browse commands and flags, and fill in required inputs with guided prompts. A confirmation screen shows the exact command before it runs. orca --help prints the same catalog as static help. Agents and CI always get static help.

The interactive command browser

Run your first commands

List the projects on this machine. Each one has an id, which later commands take as PROJECT_ID:

orca projects list

If your repo isn't there yet, register it on this machine. Clone from a Git URL or import an existing checkout:

# Clone from a URL
orca projects create --name "my-app" --local \
  --clone https://github.com/org/my-app.git \
  --parent-dir ~/code

# Or register an existing local checkout
orca projects create --name "my-app" --local --import ~/code/my-app

If the project already exists in your org but isn't on this machine, attach to it instead of creating a duplicate:

orca projects setup PROJECT_ID --local --parent-dir ~/code

Then create a workspace against it:

orca workspaces create \
  --project PROJECT_ID \
  --name "fix-login-bug" \
  --branch fix/login-bug \
  --local

Dispatch agent tasks from a script or another agent

One command creates a workspace on its own branch and starts an agent in it with a prompt. Get PROJECT_ID from orca projects list:

orca workspaces create \
  --project PROJECT_ID \
  --name "flaky-tests-2026-10-30" \
  --branch flaky-tests-2026-10-30 \
  --local \
  --agent claude \
  --prompt "Find the flaky test in CI and propose a fix. Do not merge."

Give each task a branch of its own, for example with a date or a task slug. If the branch already has a workspace on the host, the command reuses that workspace (alreadyExists: true in the JSON output) and starts the agent in it, next to any agent already working there.

--local puts the workspace on the machine that runs the command. A CI runner usually exits when the job ends, so from CI target a host that stays on with --host HOST_ID (see Local vs. remote hosts). Projects belong to a host, so use the same --host HOST_ID on every command: get PROJECT_ID from orca projects list --host HOST_ID, and pass --host HOST_ID instead of --local to workspaces create, agents create, and the terminals commands below.

The JSON output has the workspace ID in workspace.id. For each agent, agents[].ok tells you if it started (agents[].error says why not), and agents[].sessionId is its terminal ID. The command can exit 0 when an agent fails to start, so a script should check ok:

orca workspaces create --project PROJECT_ID --name "flaky-tests-2026-10-30" \
  --branch flaky-tests-2026-10-30 --local --agent claude \
  --prompt "Find the flaky test in CI and propose a fix. Do not merge." --json \
  | jq -e '.agents[0].ok'

To start another agent in a workspace that already exists:

orca agents create --workspace WORKSPACE_ID --local --agent codex --prompt "Review the diff and list risks."

Check on the work and read what an agent printed. workspaces list prints each WORKSPACE_ID. terminals list prints only a count in a terminal, so use --json to get each TERMINAL_ID:

orca workspaces list --local
orca terminals list --workspace WORKSPACE_ID --local --json \
  | jq -r '.sessions[].terminalId'
orca terminals read --workspace WORKSPACE_ID --terminal TERMINAL_ID --local

Each dispatched task opens in the desktop and iPhone apps like any other workspace, with its diff ready to review.

Another agent can do the same through the Orca MCP server. An automation with a webhook trigger starts a run when any service sends a POST to its URL.

Trigger an automation

Run an automation immediately:

orca automations list               # each automation's id is AUTOMATION_ID
orca automations run AUTOMATION_ID
orca automations logs AUTOMATION_ID

Output modes

Commands print a terminal-friendly view by default. Two flags change the output for scripts:

FlagOutput
--jsonThe data payload as formatted JSON. No envelope.
--quietOne ID per line for arrays of objects with id; the ID for single objects; JSON otherwise.
orca tasks list --assignee-me --json | jq '.[].title'
orca workspaces list --quiet | xargs -L1 orca workspaces archive

When the CLI detects an agent or CI environment (CLAUDE_CODE, CLAUDECODE, CLAUDE_CODE_ENTRYPOINT, CODEX_CLI, GEMINI_CLI, ORCA_AGENT, or CI set to a non-empty value), it defaults to JSON output unless you pass --quiet.

Local vs. remote hosts

Commands that touch a host accept --host HOST_ID to pick which host handles the request, or --local for this machine. orca hosts list gives each HOST_ID. Local calls go straight to the host server over loopback and work offline. Remote calls route through the cloud API and the relay.

orca hosts list
orca workspaces list --local          # this machine
orca workspaces list --host HOST_ID   # another host

Every host-scoped command targets exactly one host. projects list defaults to this machine. projects create and projects setup require --host or --local. workspaces create, workspaces list, and terminals commands default to the cloud when your account has cloud workspaces, and to this machine when it does not, so pass --local or --host in scripts to get the same host every time. There is no org-wide listing; the desktop app is the cross-host view.

Where state lives

~/.orca/config.json                            # auth, active organization
~/.orca/host/<organizationId>/manifest.json    # host server endpoint + token
~/.orca/host/<organizationId>/host.db          # local host server DB

ORCA_HOME_DIR relocates the whole tree, matching the desktop app.

See the CLI reference for every command, flag, and output shape.

On this page