CLI Reference

All commands are subcommands of the orca binary.

Cluster

`orca server`

Start the control plane, agent, and proxy on this node.

orca server              # Foreground
orca server &            # Background

`orca join`

Join this node to an existing cluster.

orca join 10.0.0.1       # Join by leader address

`orca nodes`

List cluster nodes with status and resource usage.

orca nodes

`orca tui`

Launch the terminal dashboard.

orca tui

`orca update`

Self-update the orca binary.

orca update

Services

`orca deploy`

Deploy services from services/*/service.toml.

orca deploy              # Deploy all discovered services
orca deploy api          # Deploy a single service by name
orca deploy api worker   # Deploy multiple services in one call

`orca status`

Show service status, replicas, and health.

orca status
orca status --project frontend

`orca logs`

Stream logs from a service.

orca logs api
orca logs api --tail 100
orca logs api --summarize         # AI-summarized digest with likely causes

--summarize requires an [ai] section in cluster.toml. See the AI Ops guide for setup.

`orca scale`

Scale a service to N replicas.

orca scale api 5

`orca stop`

Stop a service (config is retained).

orca stop api
orca stop api worker          # Stop multiple services in one call

`orca redeploy`

Force-pull the image and restart one or more services, even when the spec hasn’t changed.

orca redeploy api
orca redeploy api worker billing   # Redeploy multiple services in one call

`orca promote`

Promote a canary deployment to stable.

orca promote api

`orca rollback`

Rollback to the previous deployment.

orca rollback api

`orca exec`

Execute a command inside a running container.

orca exec api -- sh
orca exec api -- cat /etc/hostname

Databases

`orca db create`

Create a managed database with auto-generated credentials.

orca db create postgres mydb
orca db create redis cache
orca db create mysql appdb
orca db create mongodb docs

`orca db list`

List database services.

orca db list

Secrets

`orca secrets set`

Store an encrypted secret.

orca secrets set DB_PASS "s3cret"

`orca secrets list`

List secret keys (values are never displayed).

orca secrets list

`orca secrets import`

Bulk import secrets from an .env file.

orca secrets import -f .env

Operations

`orca backup`

Backup volumes and configs.

orca backup all           # Volumes + config files (secrets.json, cluster.toml)
orca backup basic         # Config files only
orca backup restore-basic # Restore latest secrets.json / cluster.toml from local backup
orca backup list          # List backups

`orca cleanup`

Prune unused Docker resources (images, containers, volumes).

orca cleanup

`orca token`

Manage API tokens.

orca token create --name ci --role deployer
orca token list

`orca webhooks`

Manage git push deploy webhooks.

orca webhooks                                                # List
orca webhooks add --repo myorg/app --service app --branch main

# Provide a shared secret so the webhook handler can verify the signature:
orca webhooks add --repo myorg/app --service app --branch main \
    --secret "$(openssl rand -hex 32)"

# Infra webhook -- triggers `git pull` + redeploy on the cluster
# whenever your orca-infra repo receives a push (no --service needed):
orca webhooks add --repo myorg/orca-infra --branch main --infra \
    --secret "$(openssl rand -hex 32)"

Flags:

Flag	Purpose
`--repo <owner/name>`	Source repository
`--service <name>`	Service to redeploy on push (omit with `--infra`)
`--branch <name>`	Branch filter (default: `main`)
`--secret <value>`	HMAC shared secret for signature verification
`--infra`	Treat as an orca-infra webhook: `git pull` + redeploy the cluster on push

`orca completions`

Print a shell completion script for the chosen shell. Pipe it to a file or source it directly.

orca completions bash       > /etc/bash_completion.d/orca
orca completions zsh        > "${fpath[1]}/_orca"
orca completions fish       > ~/.config/fish/completions/orca.fish
orca completions powershell > orca.ps1

Supported shells: bash, zsh, fish, powershell.

AI

`orca ask`

Ask the AI assistant a question with full cluster context.

orca ask "why is the API returning 500s?"
orca ask "which service is using the most memory?"

`orca generate`

Generate service configuration from natural language.

orca generate "deploy redis with 2GB storage"