orca/docs/cli.md

Orca CLI Reference

This document is the complete reference for the orca command-line interface. Every command, subcommand, and flag is documented here.

Canonical path (v0.9+): The v0.9 re-architecture introduced the SSH-push deployment model, markdown jobspec, multi-namespace layout, and CLI-side scheduler. Commands marked deprecated below are from the v0.8 daemon/mTLS model. The v0.12 milestone closed the dual-write window (REQ-138) — the legacy CA/mTLS/daemon paths are deleted. The v0.13 milestone (in progress) wires the scheduler into orca job run and delivers production hardening round 2.

Global flags

These flags are available on every orca command.

Flag	Type	Default	Description
--json	bool	false	Output in JSON format (machine-readable)
--system	bool	false	Use system-level namespace root (/root/.orca) instead of user-level (~/.orca). Errors if ORCA_HOME is already set to a conflicting value.
--config	string	""	Path to config file (overrides ~/.orca/config.md). Supports .md (canonical) and .hcl (legacy) formats.
--no-deprecation-warnings	bool	false	Suppress deprecation warnings. Use during orca upgrade migrations.

Output modes

• Text (default): human-readable tables and messages.
• JSON (--json): structured JSON output for machine consumption and AI agents.
• Watch (--watch on list commands): table refresh (text default) or NDJSON streaming (--json), one line per event until Ctrl-C.

Environment variables

Variable	Description
ORCA_HOME	Namespace root directory (default ~/.orca). Overrides all on-disk paths.
ORCA_DB	Fine-grained database path override.
ORCA_LISTEN_ADDR	Daemon listen address (deprecated).
ORCA_CA_PATH	CA certificate path override.
ORCA_SERVER_CERT_PATH	Server certificate path override.
ORCA_SERVER_KEY_PATH	Server key path override.
ORCA_NODE_CPU	Node CPU capacity override (millicores).
ORCA_NODE_MEMORY_MB	Node memory capacity override (MiB).

Exit codes

Code	Meaning
0	Success
1	Error (printed to stderr)

---

orca init

Initialize local orca state with full bootstrap.

orca init

Performs a 6-step idempotent bootstrap:

1. Create the namespace directory (honors $ORCA_HOME; defaults to ~/.orca)
2. Open and migrate the SQLite database (migrations 0001–0006)
3. Bootstrap the internal CA (ca.crt + ca.key) if not already present
4. Generate the server cert (server.crt + server.key) if not already present
5. Auto-detect the local OS via /etc/os-release
6. Register a localhost node (kind=localhost, os=<detected>)

Re-running orca init is safe — it refreshes last_seen and os on the localhost node without regenerating certs or changing the node ID.

Flags: none.

Example:

orca init
orca --system init    # system-level bootstrap at /root/.orca

---

orca version

Print the orca version, git commit, and build time.

orca version

Flags: none (global flags only).

---

orca status (deprecated)

Show orca daemon status.

orca status

Deprecated (v0.13): This command is a v0.1 stub that reports a hardcoded "daemon stopped" status. The daemon model was replaced by SSH-push in v0.9 (R-001) and the dual-write window closed in v0.12 (REQ-138). Use orca node list for node registry/state and orca metrics /healthz for health probes. This command will be removed in a future release.

---

orca node

Manage orca nodes — join, leave, list, drain, key-reset, and capacity.

orca node join

Join a node to the orca registry.

orca node join [flags]

Node types (via --type):

• localhost (default): register a local or Linux node
• proxmox: SSH-bootstrap a remote Proxmox VE 8/9 host (deploys orca pubkey, creates orca user + PVE role + sudoers allowlist; requires --host + --ssh-key; R-021: no passwords)

Flag	Type	Default	Description
--name	string	""	Node name (required for --type localhost)
--addr	string	"localhost:8443"	Node address
--ca-fingerprint	string	""	Pin CA cert SHA-256 (fails if on-disk CA doesn't match)
--type	string	"localhost"	Node type: localhost or proxmox
--host	string	""	Proxmox host address (IP/hostname; required for --type proxmox)
--ssh-user	string	"root"	SSH username for proxmox bootstrap
--ssh-key	string	""	SSH private key path for proxmox bootstrap (R-021: no passwords; default: orca key)
--ssh-port	int	22	SSH port for proxmox bootstrap
--proxmox-user	string	"orca"	Linux system user to create on the proxmox host
--proxmox-role	string	"OrcaOperator"	PVE custom role to create
--host-key-fingerprint	string	""	SSH host key SHA256:base64 fingerprint (pre-pin; supersedes TOFU for --type proxmox)

Examples:

# Localhost
orca node join --name my-node

# Proxmox (v0.9 canonical SSH-push path)
orca node join --type proxmox --host 192.168.1.100 --ssh-user root
orca node join --type proxmox --host 192.168.1.100 --ssh-key ~/.ssh/orca_ed25519

# Proxmox with pre-pinned host key
orca node join --type proxmox --host 192.168.1.100 --host-key-fingerprint SHA256:abc123...

orca node leave

Remove a node from the orca registry.

orca node leave [node-id] [flags]

Flag	Type	Default	Description
--id	string	""	Node ID (alternative to positional argument)

orca node list

List all nodes in the orca registry.

orca node list [flags]

Flag	Type	Default	Description
--watch	bool	false	Stream nodes until Ctrl-C (table refresh or --json per-event)

Output columns: ID NAME ADDRESS STATE

orca node key-reset

Reset the SSH known_hosts entry for a node.

orca node key-reset <node>

Removes the pinned SSH host key for <node> from the local known_hosts file. The next connect re-pins the key via TOFU or --host-key-fingerprint. Local only — does not touch the remote host's authorized_keys.

<node> is the node name (for proxmox nodes, this is the host address).

Example:

orca node key-reset 192.168.1.100

orca node drain

Drain a node: stop its allocations and mark it drained (REQ-061).

orca node drain <host> [flags]

Marks the node as "draining" (scheduler skips draining nodes), stops every running allocation via SSH (systemctl stop orca-alloc-<id>.service), waits for them to stop, and marks the node "drained". This is NOT live-migration — use orca job migrate to reschedule first.

Flag	Type	Default	Description
--timeout	duration	30s	Max time to wait for allocations to stop

orca node capacity

Manage node capacity declarations (bin-packing scheduler input).

orca node capacity <subcommand>

orca node capacity show

Show capacity for a node (defaults to self).

orca node capacity show [node-id] [flags]

Flag	Type	Default	Description
--node	string	""	Node ID (defaults to self)

Output: Node:, CPU: (millicores), Memory: (MiB), Disk: (MiB), Updated:

orca node capacity set

Declare capacity for a node.

orca node capacity set [flags]

Flag	Type	Default	Description
--cpu	int	0	CPU capacity in millicores (1000 = 1 vCPU)
--memory	int	0	Memory capacity in MiB
--disk	int	0	Disk capacity in MiB
--node	string	""	Node ID (defaults to self)

Example:

orca node capacity set --cpu 4000 --memory 8192 --disk 100000
orca node capacity set --cpu 2000 --memory 4096 --node web-1

orca node capacity list

List all node capacity declarations.

orca node capacity list

Output columns: NODE CPU(mc) MEM(MiB) DISK(MiB) UPDATED

---

orca job

Manage orca jobs — run, list, stop, lint, verify, migrate, restart.

orca job run

Run a job from a spec file.

orca job run <spec> [flags]

Dispatches by file extension:

• .md → Markdown frontmatter parser (v0.9 canonical)
• .yaml / .yml → YAML frontmatter parser
• .hcl → Legacy HCL adapter (deprecated)

The v0.13 scheduler wiring (REQ-151) deploys to remote nodes via the scheduler → emitter → SSH-push pipeline. When no remote nodes are available, falls back to local execution (dev mode).

Flag	Type	Default	Description
--target	string	""	Pin job to a specific node ID (overrides bin-packing scheduler)
--idempotency-key	string	""	Idempotency key for cross-node dispatch dedupe

Examples:

orca job run web-app.md
orca job run api.yaml --target node-abc-123
orca job run worker.md --idempotency-key deploy-2026-08-05

Deprecated: orca job run <spec.hcl> (legacy HCL jobspec) still works via the adapter but emits a deprecation warning. Migrate .hcl specs to .md (see docs/jobspec.md).

orca job list

List all jobs.

orca job list [flags]

Flag	Type	Default	Description
--watch	bool	false	Stream jobs until Ctrl-C (table refresh or --json per-event)

Output columns: ID NAME STATUS EXIT

Examples:

orca job list
orca job list --watch           # table refresh
orca job list --watch --json    # NDJSON: {"event":"update","job":{...}}

orca job stop

Stop a running job by sending systemctl stop orca-alloc-<name>-* to the node running the allocation via SSH, then mark the job as stopped in the DB (REQ-158, P09).

orca job stop [job-id] [flags]

If --peer is not given, the node is looked up from the allocation history. If no node is found, the DB status is updated anyway (soft stop fallback for local-run jobs).

Flag	Type	Default	Description
--id	string	""	Job ID (alternative to positional argument)
--peer	string	""	Peer address (host:port) running the allocation (auto-detected from alloc history if empty)
--timeout	duration	2m0s	SSH command timeout

Example:

orca job stop abc-123-def
orca job stop --id abc-123-def
orca job stop abc-123-def --peer 192.168.1.100:22

orca job logs

Show task output for a job.

orca job logs [job-id] [flags]

Flag	Type	Default	Description
--id	string	""	Job ID (alternative to positional argument)

Example:

orca job logs abc-123-def

orca job lint

Lint a jobspec (schema, CEL, body, migration, best-practice) without applying it (REQ-084).

orca job lint <spec> [flags]

Flag	Type	Default	Description
--explain	bool	false	Print the rationale for each finding
--format	string	"text"	Output format: text or json

Exit codes: 0 = no errors (warnings OK), 1 = errors found.

orca job verify

Dry-run a jobspec through the lead (no apply).

orca job verify <spec> [flags]

Validates the spec through the render + txn pipeline without staging or applying it. Reports any schema, constraint, or render errors.

orca job migrate

Drain + reschedule a job onto a target node (REQ-116).

orca job migrate <job-id> [flags]

Stops the job on its current node and re-submits it to the scheduler (pinned to --target if given).

orca job restart

Restart an allocation to pick up EnvironmentFile drift (REQ-113).

orca job restart <job-id> [flags]

Restarts the systemd unit(s) for the job's allocation(s) via SSH so they re-read the .env / .env.secrets files without a full redeploy.

---

orca ns

Manage orca namespaces under ORCA_HOME (R-002).

Each namespace is a directory with ns.md, .env, .env.secrets, db/, jobs/, alloc/. The implicit root namespace _defaults always exists; every namespace inherits from _defaults and cannot opt out (D-185, D-187).

orca ns list

List all namespaces under ORCA_HOME.

orca ns list

Output columns: NAME DEFAULT PATH (_defaults marked *)

orca ns create

Create a namespace directory + ns.md.

orca ns create <name> [flags]

Flag	Type	Default	Description
--parent	string	""	Parent namespace (default _defaults; implicit root always appended last)
--inherits-env	bool	true	Inherit env from parents
--inherits-secrets	bool	true	Inherit secrets from parents

Example:

orca ns create prod --parent _defaults
orca ns create staging --parent prod

orca ns delete

Remove an empty namespace directory.

orca ns delete <name>

Refuses if jobs/ or alloc/ contain files. The implicit root _defaults cannot be deleted.

orca ns inspect

Print the effective inheritance chain, merged env, and constraints.

orca ns inspect <name>

Output: Namespace:, Chain: (e.g., prod -> _defaults), Env: (sorted keys), Constraints: (unioned CEL expressions).

orca ns validate

Run cycle + missing-parent + schema checks on a namespace.

orca ns validate <name>

Exits 0 if valid, 1 on error. Runs over ALL namespaces under ORCA_HOME (parsing + resolving validates cycles and missing parents across the set).

orca ns inherit

Set the parent namespace for a namespace (R-002).

orca ns inherit <name> [flags]

Updates ns.md frontmatter (parents field) and validates the new chain has no cycles. The implicit root _defaults is always appended last (D-185).

Flag	Type	Default	Description
--parent	string	""	Parent namespace to inherit from (required)

Example:

orca ns inherit staging --parent prod

orca ns set-constraint

Set a constraint on a namespace (stored in ns.md frontmatter).

orca ns set-constraint <name> <key>=<value>

Constraints are key=value strings (e.g., max-allocs=10) stored in ns.md frontmatter and unioned across the inheritance chain by the resolver.

Example:

orca ns set-constraint prod max-allocs=10

---

orca secrets

Manage encrypted .env.secrets per namespace (REQ-080).

Each namespace has a .env.secrets file at <ORCA_HOME>/<ns>/.env.secrets containing one base64(nonce||ciphertext||tag) blob per line. Encryption is AES-256-GCM with a per-namespace HKDF-SHA256 sub-key derived from the cluster master.key (mode 0600). The AAD is the 1-based line number, defeating line-swap attacks.

orca secrets set

Encrypt KEY=value and add or update it in <namespace>/.env.secrets.

orca secrets set <namespace> <KEY=value>

orca secrets get

Decrypt the secret named KEY from <namespace>/.env.secrets and print its value to stdout.

orca secrets get <namespace> <KEY>

The value is printed with no trailing newline added. The value is never logged via slog.

orca secrets list

List the keys of all secrets stored in <namespace>/.env.secrets. Values are never printed.

orca secrets list <namespace>

orca secrets rotate

Re-encrypt the secret named KEY with a fresh nonce. The plaintext value is unchanged.

orca secrets rotate <namespace> <KEY>

orca secrets delete

Remove the secret named KEY from <namespace>/.env.secrets.

orca secrets delete <namespace> <KEY>

orca secrets rotate-master

Generate a new master key, re-encrypt every namespace's .env.secrets under the new key, and re-seal the master key to OIDC (REQ-129, C-30).

orca secrets rotate-master [flags]

Flag	Type	Default	Description
--dry-run	bool	false	Report affected namespaces without writing (C-30)

Atomic per-namespace; automatic rollback to the old key on any failure.

---

orca acl

Manage the cluster ACL (P02, v0.11). Identities are either SPIFFE workload URIs (spiffe://orca.local/ns/<ns>/sa/<sa>/<alloc>) or operator token IDs. Permissions are deny-by-default.

State is stored at ClusterDir()/acl.json (mode 0600).

orca acl grant

Grant permissions to an identity on a namespace.

orca acl grant <identity> [flags]

Flag	Type	Default	Description
--namespace	string	""	Namespace scope (required for tokens; defaults to spiffe path ns)
--permissions	string	"read"	Comma-separated list of read,write,admin

orca acl revoke

Revoke an identity's entry on a namespace.

orca acl revoke <identity> [flags]

Flag	Type	Default	Description
--namespace	string	""	Namespace scope (required for tokens; defaults to spiffe path ns)

orca acl list

List all ACL entries.

orca acl list

orca acl check

Check whether an identity has the given permission on a namespace. Exits 0 if allowed, 1 if denied.

orca acl check <identity> [flags]

Flag	Type	Default	Description
--namespace	string	""	Namespace scope (required for tokens; defaults to spiffe path ns)
--permission	string	"read"	Permission to check: read, write, or admin

---

orca cluster

Cluster-wide operations: cutover, lead rotation, mixed-version compatibility checks, and master-key seal/unseal (REQ-147, D-241, C-35).

orca cluster cutover

Stop v0.8 orca daemons and adopt running allocs (P14b).

orca cluster cutover

Stops the v0.8 orca-daemon on every peer that still runs one, discovers its running allocations (orca-alloc-*.service), and adopts each into the SSH-push path. Idempotent.

orca cluster rotate-lead

Rotate the cluster lead to a new bare Linux node (REQ-114, R-003).

orca cluster rotate-lead --to <new-lead-host> [flags]

Steps: verify the new lead is a registered bare Linux node (Proxmox nodes are ineligible — hypervisor kernel is shared with guests), copy the cluster CA + master key + config + txn log to the new lead via SSH, update local cluster state, rotate the SSH keypair, and deploy the new public key to every peer. Workloads keep running.

Flag	Type	Default	Description
--to	string	""	New lead host (required)
--debug	bool	false	Enable debug logging

orca cluster compat-check

Check mixed-version tolerance across peers (REQ-065, C-13).

orca cluster compat-check

Verifies each peer's orca version, txn manifest format compatibility, render-contract JSON schema compatibility, and that no new required fields break old peers.

orca cluster seal

Seal the cluster master key (REQ-147, D-241, C-35).

orca cluster seal

Encrypts the raw master key at ClusterDir()/master.key with a key derived from the OIDC ID token subject (if orca auth login has been run) or the cluster CA fingerprint (mTLS-only offline path). The sealed blob is written to ClusterDir()/master.key.sealed (0600). Five Shamir shards (3-of-5 recovery) are printed to stdout — store them offline. The raw master key is then deleted from disk.

orca cluster unseal

Unseal the cluster master key (REQ-147, D-241, C-35).

orca cluster unseal [flags]

Reads the sealed blob at ClusterDir()/master.key.sealed and unwraps the master key using the OIDC ID token subject or the cluster CA fingerprint. The unwrapped master key is written back to ClusterDir()/master.key (0600). The raw key is zeroed from memory on process exit.

With --recovery, the operator is prompted for 3 of the 5 Shamir shards printed at seal time (IdP-lost recovery path).

Flag	Type	Default	Description
--recovery	bool	false	Shamir recovery: prompt for 3-of-5 shards (if IdP lost)

---

orca doctor

Run self-checks on the orca installation.

orca doctor [subcommand]

Without a subcommand, runs all checks and prints a PASS/WARN/FAIL report per check.

Subcommands

Command	Description
orca doctor cert	CA, server cert, expiry, fingerprint checks
orca doctor network	Network reachability via mTLS /healthz probe
orca doctor db	Database integrity (PRAGMA integrity_check + migration version)
orca doctor os	OS detection self-check (verifies /etc/os-release matches stored node)
orca doctor proxmox	Proxmox node reachability via SSH pveversion/pvecmd status probe; audits /etc/sudoers.d/orca
orca doctor nft	nftables ingress ruleset self-check (R-017); audits live ruleset against on-disk hash
orca doctor audit	Verify the audit log hash chain (tamper-evidence check, REQ-125)
orca doctor modes	Verify security-sensitive file permissions (REQ-033/130, F13)
orca doctor oidc	Check the bundled Dex OIDC provider health (P06)
orca doctor db-retention	Check DB row counts for unbounded growth (REQ-158)
orca doctor no-orca-on-server	Verify no orca binary/service/process on peers (REQ-086, R-001)

Example:

orca doctor
orca doctor cert
orca doctor proxmox --json
orca doctor audit
orca doctor modes

---

orca audit

View orca audit log (security-first observability).

orca audit list

List recent audit log entries.

orca audit list [flags]

Flag	Type	Default	Description
--limit	int	50	Max entries to show

Output columns: TIMESTAMP ACTOR ACTION RESOURCE RESULT

---

orca backup

Create a signed tar.gz backup of ORCA_HOME (P04).

orca backup [flags]

Walks ORCA_HOME recursively, excludes /run/orca/*, *.sock, *.db-wal, *.db-shm, packs the rest into a tar.gz, and computes an HMAC-SHA256 signature using the cluster master key.

Flag	Type	Default	Description
--out	string	""	Output tarball path (default: orca-backup-<timestamp>.tar.gz in CWD)

---

orca restore

Restore ORCA_HOME from a verified signed backup (P04/P07).

orca restore [flags]

Verifies the HMAC-SHA256 signature before extracting. Reconciles with live state: refuses to clobber running allocations unless --force is given. With --dry-run, extracts to a temp dir and reports what would be restored without touching ORCA_HOME.

Flag	Type	Default	Description
--in	string	""	Input tarball path (required)
--force	bool	false	Stop running allocs before restore
--dry-run	bool	false	Extract to temp dir; report without writing

---

orca upgrade

Upgrade orca to a new version (thin wrapper; R-017 cutover).

orca upgrade [flags]

Handles the R-017 binding cutover (Traefik :443 → 127.0.0.1:8443 + nftables), creates the orca system user on existing peers (C-27), optionally imports the v0.8 internal CA into step-ca, and runs Migratev08tov11 if a v0.8 layout is detected. Idempotent.

Flag	Type	Default	Description
--to	string	""	Target version (e.g., v0.12.10) (required)
--dry-run	bool	false	Report what would be done without making changes
--force	bool	false	Skip cutover verification (use with caution)
--import-ca	bool	false	Import the v0.8 internal CA into step-ca during upgrade

---

orca metrics

Start a standalone HTTP server exposing Prometheus text-exposition metrics at /metrics and a liveness probe at /healthz.

orca metrics [flags]

No orca daemon required (R-001). Polls cluster state periodically and updates gauges.

Flag	Type	Default	Description
--addr	string	":9100"	Listen address for the metrics HTTP server

---

orca logs

Aggregate journald logs across registered nodes via SSH fanout (REQ-117).

orca logs [flags]

Runs journalctl -u 'orca-alloc-*' --since <dur> --output json on each peer, parses the JSON-per-line output, and streams the entries with a [<hostname>] prefix (multi-node) or raw (single-node). --json outputs the raw journalctl JSON lines verbatim.

Flag	Type	Default	Description
--all-nodes	bool	false	Fan out to every registered node
--node	string	""	Single node host to query
--job	string	""	Filter units to orca-alloc-<name>-*
--since	string	""	Duration (e.g., 5m, 1h, 30m)
--json	bool	false	Output raw journalctl JSON lines

Examples:

orca logs --all-nodes --since 5m
orca logs --node web-1 --since 1h
orca logs --all-nodes --job web --since 30m --json

---

orca cache

Manage the CLI-side SQLite cache (R-008) at ORCA_HOME/orca_cache.db.

orca cache <subcommand>

Read-only list commands (node/job/ns list) populate the cache; writes bypass it. The --watch flag bypasses the cache entirely (streaming).

orca cache show

Print cache stats (per-class counts, sizes, oldest entry).

orca cache show

orca cache invalidate

Drop all entries for a cache class.

orca cache invalidate <class>

Example:

orca cache invalidate nodes

orca cache invalidate-all

Drop every entry in the cache.

orca cache invalidate-all

---

orca drift

Detect and remediate control-plane drift (P10b). Orca's drift detector is a BACKUP (R-019): the primary consistency mechanism is systemd / Traefik / step-ca / Syncthing themselves. Pre-flight drift blocks txn apply (R-020).

orca drift <subcommand>

orca drift show

Show the aggregated drift events from the lead.

orca drift show [flags]

Flag	Type	Default	Description
--peer	string	""	Filter to a single peer host

orca drift watch

Stream drift events from the lead's aggregated state.

orca drift watch [flags]

Flag	Type	Default	Description
--interval	duration	2s	Poll interval
--paths	strings	[]	Comma-separated glob patterns to watch (default: all)

orca drift acknowledge

Record operator acknowledgment for the given path in drift-acknowledgments.json on the lead. Acknowledged drift no longer blocks txn apply for that namespace (R-020).

orca drift acknowledge <peer> <path> [flags]

Flag	Type	Default	Description
--timeout	duration	2m0s	SSH command timeout

orca drift remediate

Trigger orca-remediate.sh on the lead for the given path.

orca drift remediate <peer> <path> [flags]

Flag	Type	Default	Description
--force	bool	false	Bypass the cooldown window (C4)
--timeout	duration	2m0s	SSH command timeout

orca drift config

Show or validate the drift config.

orca drift config <subcommand>

orca drift config show

Show the current drift config.

orca drift config show

orca drift config validate

Validate the drift config.

orca drift config validate

Flag	Type	Default	Description
--config	string	""	Path to drift config JSON (default: built-in)

---

orca txn

Manage orca's transactional control-plane updates (P10a).

A transaction (txn) is a content-addressed desired-state bundle (apply.sh + verify.sh + rollback.sh + signed manifest) staged to the lead peer and applied idempotently. Cluster-wide txns require explicit operator acknowledgement; namespace-scoped txns only touch the given namespace (C-23).

orca txn <subcommand>

orca txn apply

Apply a staged txn on the lead peer (idempotent; C-09 failure contract).

orca txn apply <txn-id> [flags]

The txn must already be staged on the lead under /run/orca/txns/<txn-id>/. Cluster-wide txns (no --namespace) require --force + --i-understand-the-risk (or --yes for non-interactive). Namespace-scoped txns (--namespace <ns>) only touch that namespace.

Flag	Type	Default	Description
--namespace	string	""	Namespace scope (cluster-wide if empty)
--force	bool	false	Acknowledge cluster-wide risk
--i-understand-the-risk	bool	false	Acknowledge cluster-wide risk (explicit)
--yes	bool	false	Non-interactive acknowledgement (skip prompt)

orca txn list

List staged + applied transactions.

orca txn list

orca txn show

Show txn details (desired state, manifest, status).

orca txn show <txn-id>

orca txn rollback

Run rollback.sh for a staged txn on the lead peer.

orca txn rollback <txn-id> [flags]

Flag	Type	Default	Description
--lead	string	""	Lead peer address (host:port)
--timeout	duration	2m0s	SSH rollback timeout

---

orca nft

Inspect and manage the nftables ingress ruleset (R-017). Orca's ingress is hybrid: Traefik binds 127.0.0.1:8443 and nftables DNATs the public :443 to it.

orca nft <subcommand>

orca nft show

Show the live inet orca-ingress table on the peer (default: lead).

orca nft show [flags]

Flag	Type	Default	Description
--peer	string	""	Peer host to query (default: lead)

orca nft diff

Compare the live nft ruleset against the expected from a txn.

orca nft diff [flags]

Flag	Type	Default	Description
--against	string	""	Txn-ID to diff against (required)

orca nft doctor

Alias for orca doctor nft.

orca nft doctor

orca nft country

GeoIP country-block management (opt-in). Manages the orca_geoip_block nft set.

orca nft country <subcommand>

orca nft country block add

Add country codes to the GeoIP block set.

orca nft country block add <cc-list>

Adds one or more ISO-3166 alpha-2 country codes (comma-separated) to the orca_geoip_block nft set on the lead.

Example:

orca nft country block add RU,CN

orca nft rate

Rate-limit meter management.

orca nft rate <subcommand>

orca nft rate limit set

Adjust the forward-chain rate-limit meter.

orca nft rate limit set [flags]

Flag	Type	Default	Description
--rate	int	0	Rate limit in packets/second (required, >0)

Re-renders /etc/nftables.d/orca.nft with the new rate and applies it on the lead. The burst is set to 2x the rate when not specified.

---

orca cert (deprecated)

Manage orca certificates (CA, server, rotation).

Deprecated: The v0.9 re-architecture replaces the internal CA with step-ca (D-101/REQ-076). The orca cert command tree is retained for the dual-write window and scheduled for deletion. The v0.12 milestone closed the dual-write window (REQ-138).

orca cert <subcommand>

Subcommands

Command	Description
orca cert ca-init	Initialize a local orca CA (ca.crt + ca.key)
orca cert gen	Generate a server cert (CSR + sign)
orca cert show	Print the server cert (private keys redacted; REQ-035)
orca cert renew	Rotate the server cert (REQ-034)
orca cert fingerprint	Print the SHA-256 fingerprint of ca.crt or server.crt

---

orca auth

OIDC authentication for human operators (zero-trust identity, R-021).

Orca uses OIDC for human-identity authentication (R-021: no Orca-issued credentials). The bundled Dex (deployed by orca auth init-idp) is the default issuer; oidc.issuer in config can repoint to a BYO external IdP. The CLI performs the authorization-code + PKCE + local loopback redirect flow; headless/CI uses the device-code flow.

orca auth <subcommand>

orca auth login

Authenticate via OIDC (browser or device-code flow).

orca auth login [flags]

By default, opens the default browser for the authorization-code + PKCE

• local loopback redirect flow. Credentials are stored at ~/.orca/credentials.json (0600, short-lived + refresh).

Flag	Type	Default	Description
--client-id	string	"orca-cli"	OIDC client ID
--client-secret	string	""	OIDC client secret (confidential clients; public PKCE clients omit)
--device-code	bool	false	Use device-code flow (headless/CI)

orca auth logout

Clear the stored OIDC credentials.

orca auth logout

orca auth status

Show the current OIDC authentication status.

orca auth status

orca auth init-idp

Bootstrap the bundled Dex OIDC provider on the lead.

orca auth init-idp [flags]

Deploys a bundled Dex instance on the lead node as a systemd unit, fronted by Traefik (R-017, step-ca cert). The WebAuthn connector (P05) provides the password-free upstream authenticator.

Flag	Type	Default	Description
--rp-id	string	""	WebAuthn relying-party ID (cluster Traefik domain; C-38)

orca auth register

Open the WebAuthn passkey registration page in the browser.

orca auth register [flags]

Opens the browser to the Dex WebAuthn registration page at https://<cluster>/orca/webauthn/register. The operator authenticates via an existing session, then registers a passkey (biometric or security key). Use --no-browser to print the URL instead of opening a browser.

Flag	Type	Default	Description
--no-browser	bool	false	Print the URL instead of opening a browser

See docs/webauthn.md for the WebAuthn / passkey guide.

---

orca peer-setup

Create the orca system user + drift-events dir on a peer (REQ-111).

orca peer-setup <peer> [flags]

SSH to <peer> and idempotently create the orca system user (useradd -r orca -s /usr/sbin/nologin) and /etc/orca/state/drift-events/ owned by orca:orca. Also detects NFS on /etc/orca (REQ-112/D-233) and logs a warning. Use --no-orca-user to skip user creation (for environments with an existing service account).

Flag	Type	Default	Description
--no-orca-user	bool	false	Skip orca system user creation (env has existing service account)
--timeout	duration	2m0s	SSH command timeout

---

orca collector

Manage the lead-side collector: the aggregator (orca-aggregate.sh, 10s cadence, merges per-peer state into cluster.json + drift-event aggregation per REQ-107) and the watchdog (orca-watchdog.sh, 30s cadence, detects aggregator starvation per C-11). Opt-in (C-12).

orca collector <subcommand>

orca collector start

Emit the collector scripts + systemd units and enable them.

orca collector start [flags]

Flag	Type	Default	Description
--dry-run	bool	false	Emit scripts/units without enabling or running systemctl
--root	string	"/"	Install root for emitted paths (for testing use a temp dir)

orca collector stop

Disable and remove the collector scripts + systemd units.

orca collector stop [flags]

Flag	Type	Default	Description
--dry-run	bool	false	Remove scripts/units without disabling or running systemctl
--root	string	"/"	Install root for emitted paths (for testing use a temp dir)

orca collector status

Report whether the collector (aggregator + watchdog) is running.

orca collector status

---

orca daemon (deprecated)

Run the orca daemon (HTTP API + health checks).

Deprecated: The v0.9 re-architecture replaces the daemon with SSH-push (R-001). The daemon is repurposed to drain-and-stop in v0.11-P05. The v0.12 milestone closed the dual-write window (REQ-138). The legacy daemon plaintext/mTLS mode is deleted; mTLS is available for metrics/health probes only.

orca daemon [flags]

Flag	Type	Default	Description
--addr	string	":8080"	Listen address
--pprof	bool	false	Enable pprof endpoint (loopback-only by default)

---

Deprecated commands

The following commands are from the v0.8 daemon/mTLS model and are deprecated. The v0.12 milestone (REQ-138) closed the dual-write window — the legacy CA/mTLS/daemon paths are deleted. The orca cert command tree and orca daemon are retained as thin stubs during the final removal cycle.

orca daemon — Run the orca daemon. Replaced by SSH-push (R-001). The daemon is repurposed to drain-and-stop and the legacy plaintext/mTLS mode is deleted (REQ-138).

orca cert — Manage orca certificates. Replaced by step-ca (D-101). Scheduled for deletion.

orca node join (mTLS path) — The localhost mTLS join path (without --type proxmox) is deprecated. The v0.9 canonical path is SSH-push (--type proxmox) or local execution (no join needed).

orca job run <spec.hcl> — Legacy HCL jobspec. Migrate to .md (see docs/jobspec.md).

orca status — v0.1 stub. Use orca node list + orca metrics /healthz.

To suppress deprecation warnings during migration, use --no-deprecation-warnings:

orca --no-deprecation-warnings daemon

---

See also

• docs/jobspec.md — Markdown frontmatter jobspec reference
• docs/ingress.md — Traefik ingress configuration guide
• docs/namespace.md — Namespace and path layout
• docs/install.md — Installation guide
• docs/security-runbook.md — Security runbook (seal/unseal, rotation, incident response)
• docs/webauthn.md — WebAuthn / passkey registration
• docs/threat-model.md — STRIDE threat model + zero-trust architecture
• docs/oidc.md — OIDC configuration (Dex quickstart, BYO IdP)
• examples/full-stack/ — Full-stack example with ingress