coreci/orca
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 91 Wiki Activity

docs(P02): CLI reference + jobspec reference + ingress guide

Browse Source 
P02 — operator-facing documentation (REQ-091, REQ-092, REQ-093; gate C-22).

docs/cli.md (REQ-091):
- Full CLI command/flag reference: every command/subcommand with synopsis,
  flag tables (name/type/default/description), one-line examples.
- Global flags (--json, --system, --config, --no-deprecation-warnings).
- Output modes (text/json/watch), env vars, exit codes.
- Deprecated surface callout boxes (daemon, cert, node-join-mTLS, HCL
  jobspec) pointing to v0.11 removal.

docs/jobspec.md (REQ-092):
- Markdown frontmatter schema reference: all top-level keys, block
  reference (runtime/ports/env-secrets/volumes/restart/update/service/
  health/lifecycle/constraints/affinity/tasks), kinds matrix
  (Job/Service/DaemonSet required vs allowed), CEL subset grammar, body
  byte-exact preservation (R-015), deprecated HCL callout.

docs/ingress.md (REQ-093):
- Traefik ingress reference: service->Traefik mapping (D-175), R-007
  socket-vs-TCP-bind semantics, generated YAML shape (routers/services/
  healthCheck), atomic reload (C-10), drain (weight:0), TLS (certResolver,
  trust domain, step-ca), worked-example pointer to examples/full-stack/,
  v0.11 forward limitations.

All factual claims grounded in live codebase (gate C-22). Cross-links
verified to resolve.

---ci---
project: orca
phase: 2
milestone: v0.10
status: execute
---/ci---
This commit is contained in:
Jon Chery
2026-08-05 20:57:05 +00:00
parent cfec794bb7
commit 289e5cf6e1
4 changed files with 1178 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/cli.md
+522
View File
@@ -0,0 +1,522 @@
# 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