CLI reference

The orca command talks to the Orca daemon, so you can script what the app does: run worktree instances, manage containers, stacks and the gateway, and install the CA certificate. This page lists every command and flag.

Run orca --help or orca <command> --help for the same information in your terminal.

#Install

The CLI ships with the desktop app, next to the daemon:

• macOS: /Applications/Orca Desktop.app/Contents/MacOS/orca. To use it as orca, link it into a folder on your PATH:

  Terminal

  sudo ln -s "/Applications/Orca Desktop.app/Contents/MacOS/orca" /usr/local/bin/orca

• Windows: the installer adds the install folder to your user PATH. Open a new terminal after installing.

• Linux: included in the .deb and AppImage bundles.

To build it from source:

cargo build --release --bin orca
./target/release/orca version

#Connect and authenticate

Every command except the config commands goes through the daemon API. Two global options control how:

Without --token or ORCA_TOKEN, the CLI reads api_token from Orca's config file (~/Library/Application Support/orca/config.json on macOS, ~/.config/orca/config.json on Linux, %APPDATA%\orca\config.json on Windows). On the machine where the app runs you normally don't need to set anything.

To control a daemon on another machine:

ORCA_DAEMON_URL=http://build-box:9477 ORCA_TOKEN=... orca containers list

#Status and version

orca status flags:

#Worktree instances

These commands work out the project and instance from the current folder, so you run them inside a git worktree of a registered project. Each worktree gets its own running copy of the app, while databases and other shared services run once.

#orca projects

orca projects add [PATH]      # register a git repo (default: current folder)
orca projects list [--json]   # registered projects, shared services and instances
orca projects remove <ID>     # unregister a project (stop its instances first)

Any worktree of a repo works for add.

#orca up

Start or rebuild this worktree's instance and wait until it's up. It prints each step, then the URLs and the path of the .orca/env file.

#orca down

Stop this worktree's instance.

#orca logs

orca logs [SERVICE] [--tail 200] [-f]

#orca env

Print the instance's URLs, ports and connection strings from .orca/env as shell exports:

eval $(orca env)

Run orca up first: the file doesn't exist until the instance has started.

#orca run

Run a command with the instance's environment. It starts the instance if it isn't running, loads .orca/env into the command's environment, and exits with the command's exit code.

orca run -- npm test
orca run --serve web -- npm run dev

Everything after -- is the command and its arguments.

#Workspaces

A workspace sets up a team's local environment from one repo.

#AI tools (MCP)

orca mcp runs Orca as an MCP server over stdio for Claude Code, Claude Desktop, Cursor and other AI tools. It reads the token from Orca's config, so the AI tool's config holds none. See AI agents and MCP.

#Containers

orca containers list
orca containers start <ID>
orca containers stop <ID>
orca containers logs <ID> [--tail <N>]
orca containers exec <ID> -- <COMMAND> [ARGS...]

<ID> is a container ID or name. exec exits with the command's exit code.

#Images

orca images list
orca images pull <REFERENCE>    # for example nginx:alpine
orca images remove <ID>         # image ID or tag
orca images prune               # remove unused images

#Stacks

orca stacks list           # name, status, service count and directory
orca stacks up <NAME>      # docker compose up
orca stacks down <NAME>    # docker compose down

#Deploy

orca deploy <PATH>
orca deploy --template <ID>

#Templates

orca templates list
orca templates search <QUERY>   # matches name, description and category

#Kubernetes

orca k8s status              # enabled, running, version, node, pod counts
orca k8s enable
orca k8s disable
orca k8s runtime [VALUE]

orca k8s runtime without a value shows the cluster's container runtime. Set it to docker (the default, so images you build locally are usable without a push or import) or containerd.

#Machines

orca machine list

#Gateway

orca gateway status
orca gateway start
orca gateway stop
orca gateway routes
orca gateway add <HOST> <CONTAINER> <PORT>
orca gateway remove <HOST>
orca gateway config [flags]

add routes a hostname such as app.localhost to a container's port. remove deletes the route for a hostname.

orca gateway config shows the configuration when run without flags, or updates it:

See Gateway for how hostnames and certificates work.

#CA certificate

orca ca info      # subject, expiry and fingerprint
orca ca export    # print the CA certificate (PEM) to stdout
orca ca install   # add it to the system trust store

orca ca install uses sudo security add-trusted-cert on macOS, sudo update-ca-certificates on Linux and certutil on Windows, so expect a password prompt on macOS and Linux. If it fails, it prints the command to run by hand and where it saved the certificate.

#Config

These commands read and write Orca's config file directly, without going through the daemon. They cover the gateway settings.

orca config export [--include-secrets] > orca-config.yaml
orca config import orca-config.yaml
orca config get <KEY>
orca config set <KEY> <VALUE>

Valid keys are gateway.domain, gateway.http_port, gateway.https_port and gateway.tls_mode (orca_ca or custom).