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**:
```bash
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**:
```bash
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](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**:
```bash
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**:
```bash
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**:
```bash
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**:
```bash
# 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**:
```bash
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**:
```bash
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**:
```bash
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**:
```bash
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](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`:
```bash
orca --no-deprecation-warnings daemon
```

---

## See also

- [docs/jobspec.md](jobspec.md) — Markdown frontmatter jobspec reference
- [docs/ingress.md](ingress.md) — Traefik ingress configuration guide
- [docs/namespace.md](namespace.md) — Namespace and path layout
- [docs/install.md](install.md) — Installation guide
- [examples/full-stack/](../examples/full-stack/) — Full-stack example with ingress