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 and will be removed in v0.11. Use the v0.9 canonical path for all new work.

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.hcl). Supports .hcl (legacy) and .md (v0.9 canonical) formats.
--no-deprecation-warnings	bool	false	Suppress v0.9 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_PROXMOX_PASSWORD	SSH password for orca node join --type proxmox (never persisted).
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 job

Manage orca jobs — run, list, stop, and inspect.

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, see callout below)

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). Removed in v0.11.

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 (soft stop).

orca job stop [job-id] [flags]

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

Example:

orca job stop abc-123-def
orca job stop --id abc-123-def

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 node

Manage orca nodes — join, leave, or list nodes in the registry.

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 + --password)

Flag	Type	Default	Description
--name	string	""	Node name (required for --type localhost)
--addr	string	""	Node address (default localhost:8443)
--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
--password	string	""	SSH password for proxmox bootstrap (never persisted; prefer $ORCA_PROXMOX_PASSWORD)
--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 (deprecated mTLS path)
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_PROXMOX_PASSWORD=secret orca node join --type proxmox --host 192.168.1.100

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

Deprecated: orca node join without --type proxmox (the localhost mTLS join path) is deprecated in v0.9. The v0.9 canonical path is SSH-push (--type proxmox) or local execution (no join needed). Removed in v0.11.

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 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	int64	0	CPU capacity in millicores (1000 = 1 vCPU)
--memory	int64	0	Memory capacity in MiB
--disk	int64	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 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.

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

Example:

orca doctor
orca doctor cert
orca doctor proxmox --json

---

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 version

Print version information.

orca version

Output:

orca version v0.9.1
  git commit: abc1234
  build time: 2026-08-05T20:30:00Z

---

orca status

Show orca daemon status.

orca status

Deprecated: The daemon model is deprecated in v0.9 (replaced by SSH-push, R-001). This command returns a stub status. Removed in v0.11.

---

Deprecated commands

The following commands are from the v0.8 daemon/mTLS model and are deprecated in v0.9. They still work during the dual-write window but emit slog.Warn deprecation warnings. They will be removed in v0.11.

orca daemon — Run the orca daemon (HTTP API + health checks). 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 and deleted in v0.11-P14. Flags: --addr (default :8080), --pprof (pprof endpoint, default disabled).

orca cert — Manage orca certificates (CA, server, rotation). The v0.9 re-architecture replaces the internal CA with step-ca (D-101). Subcommands: ca-init, gen, show, renew, fingerprint. Removed in v0.11.

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). The HCL adapter preserves orca job run old-spec.hcl during the migration window.

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
• examples/full-stack/ — Full-stack example with ingress