up

docs/orchestrator/cli.md

@@ -0,0 +1,35 @@
+# Orchestrator CLI (DOCS-ORCH-33-003)
+
+> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.
+
+Last updated: 2025-11-25
+
+## Commands
+- `stella orch dag list` — list DAGs (stable order by `dagId`, `version` DESC). Flags: `--dag-id`, `--active`.
+- `stella orch dag publish --file dag.yaml --signature sig.dsse` — publish DAG version (idempotent on signature).
+- `stella orch dag disable --dag-id <id> --version <ver>` — disable version.
+- `stella orch run start --dag-id <id> [--version <ver>] --inputs inputs.json [--run-token <uuid>]` — start run.
+- `stella orch run list [--dag-id <id>] [--status running|completed|failed|cancelled] [--from ISO] [--to ISO]` — list runs.
+- `stella orch run cancel --run-id <id>` — request cancellation.
+- `stella orch run logs --run-id <id> [--step-id <step>]` — fetch logs/artifacts (tenant scoped).
+- `stella orch run stream --dag-id <id>` — stream NDJSON run events (matches WebSocket feed).
+
+## Global flags
+- `--tenant <id>` (required), `--api-url`, `--token`, `--traceparent`, `--output json|table`, `--page-size`, `--page-token`.
+
+## Determinism & offline
+- CLI sorts client-side exactly as API returns; table output uses fixed column order.
+- Works offline against local WebService; no external downloads.
+- All timestamps printed UTC; hashes lower-case hex.
+
+## Exit codes
+- `0` success; `1` validation/HTTP error; `2` auth/tenant missing; `3` cancellation rejected.
+
+## Examples
+```bash
+# Start a run with idempotency token
+stella orch run start --dag-id policy-refresh --inputs inputs.json --run-token 3e2b3d2e-1f21-4c2d-9a9d-123456789abc --tenant acme
+
+# Stream run updates
+stella orch run stream --dag-id policy-refresh --tenant acme --output json
+```