@jr2/orchestrator 0.4.1 → 0.6.0

package/docs/reference/cli.md

@@ -0,0 +1,433 @@
+---
+title: CLI
+description: "Every jr2 command: its synopsis, its arguments, flags and env vars, and what it prints."
+---
+
+# CLI
+
+The `jr2` binary: orchestrate agentic workflows ([ADR-0009](decisions/0009-cli-and-instance-interface.md)). `jr2 --help` prints the same table as this page, and `jr2 <command> --help` prints one command.
+
+Commands: [`version`](#version), [`init`](#init), [`check`](#check), [`up`](#up), [`down`](#down), [`gc`](#gc), [`kit push`](#kit-push), [`run`](#run), [`runs`](#runs), [`status`](#status), [`logs`](#logs), [`send`](#send).
+
+<a id="global-options"></a>
+
+## Global options
+
+These address the deployment; each lists the verbs that take it ([ADR-0019](decisions/0019-one-converging-command-against-the-current-context.md)).
+
+| Flag | Variable | Description | Taken by |
+| --- | --- | --- | --- |
+| `-n, --namespace <ns>` |  | the deployment's namespace (default: the config's `name`, then the Instance folder's name) | [`version`](#version), [`up`](#up), [`down`](#down), [`run`](#run), [`runs`](#runs), [`status`](#status), [`logs`](#logs), [`send`](#send) |
+| `--context <ctx>` |  | the kube context (default: kubectl's current context) | [`version`](#version), [`up`](#up), [`down`](#down), [`gc`](#gc), [`run`](#run), [`runs`](#runs), [`status`](#status), [`logs`](#logs), [`send`](#send) |
+| `--url <u>` | `JR2_URL` | attach to a specific orchestrator (skips kube entirely) | [`version`](#version), [`run`](#run), [`runs`](#runs), [`status`](#status), [`logs`](#logs), [`send`](#send) |
+|  | `JR2_TOKEN` | the Instance token to send: with `--url` / `JR2_URL` the only one, and otherwise used in place of the one read from the cluster | [`run`](#run), [`runs`](#runs), [`status`](#status), [`logs`](#logs), [`send`](#send) |
+
+## Commands
+
+<a id="version"></a>
+
+### `jr2 version`
+
+```sh
+jr2 version [--local] [--json] [--url <u>] [-n <ns>] [--context <ctx>]
+```
+
+What runs here (this jr2, the global that handed off, the Instance's Kit) and what the cluster runs.
+
+--local skips the cluster.
+
+Also spelled `jr2 --version`.
+
+**Flags**
+
+| Flag | Description |
+| --- | --- |
+| `--local` | report what runs here and skip the cluster |
+| `--json` | print the one report object on stdout instead of the table |
+| `--url <u>` | attach to a specific orchestrator (skips kube entirely) |
+| `-n, --namespace <ns>` | the deployment's namespace (default: the config's `name`, then the Instance folder's name) |
+| `--context <ctx>` | the kube context (default: kubectl's current context) |
+
+**Environment**
+
+| Variable | Description |
+| --- | --- |
+| `JR2_URL` | the orchestrator to attach to, when `--url` is not given |
+| `JR2_HANDOFF_FROM` | set by the global `jr2` that handed off to this one, which the report names |
+
+**Output**: report, a table on stdout, or the one report object with `--json`. See [Output](#output).
+
+**Decisions**: [ADR-0009](decisions/0009-cli-and-instance-interface.md), [ADR-0056](decisions/0056-a-global-jr2-hands-off-to-the-instances-own-and-an-instance-has-one-kit-version.md).
+
+<a id="init"></a>
+
+### `jr2 init`
+
+```sh
+jr2 init [dir] [--name <n>]
+```
+
+Scaffold a new instance folder.
+
+Writes AGENTS.md, with the jr2 docs index between its two jr2-docs markers (empty when this jr2 has no docs bundle), and a CLAUDE.md that imports it.
+
+**Arguments**
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `dir` | no | the folder to scaffold (default: the current directory) |
+
+**Flags**
+
+| Flag | Description |
+| --- | --- |
+| `--name <n>` | the package name in package.json (default: the folder's name) |
+
+**Output**: activity, activity on stderr only. See [Output](#output).
+
+**Decisions**: [ADR-0009](decisions/0009-cli-and-instance-interface.md), [ADR-0072](decisions/0072-the-docs-ship-inside-the-kit-and-an-instances-agents-md-indexes-them.md).
+
+<a id="check"></a>
+
+### `jr2 check`
+
+```sh
+jr2 check
+```
+
+Typecheck this instance and load its workflows, as `jr2 up` does first, with no cluster.
+
+Runs the check that `jr2 up` runs before it stages the Assembly, and exits 1 with the same refusal: a type error, a module that refuses to load (a refusal of `createMachine`, `defineEvent` or `workspace()`), an Open part, a Chart file, a dispatch, an Effect secret or a Size.
+
+Reads no kube context and writes no file, so an Assistant runs it before it gives a change to the user.
+
+**Output**: activity, activity on stderr only. See [Output](#output).
+
+**Decisions**: [ADR-0050](decisions/0050-what-code-names-config-declares-what-the-cli-names-discovery-finds.md).
+
+<a id="up"></a>
+
+### `jr2 up`
+
+```sh
+jr2 up [--yes] [--force] [--skip-provider-preflight] [-n <ns>] [--context <ctx>]
+```
+
+Converge the current kube context to this instance.
+
+Reads each `git.credentials` token from the env var it names, after the Instance's .env.
+
+Before the cluster work, sets the text between the jr2-docs markers in AGENTS.md to the docs index of the Kit version, and changes nothing outside them; a folder with no markers is left alone.
+
+**Flags**
+
+| Flag | Description |
+| --- | --- |
+| `--yes` | answer the questions non-interactively: confirm first-time setup, and take the recommended git ssh key source (for CI) |
+| `--force` | build every image again, even one already built or deployed |
+| `--skip-provider-preflight` | do not run the provider preflight: no check pod checks the models, so a check that fails when the model works does not stop the converge |
+| `-n, --namespace <ns>` | the deployment's namespace (default: the config's `name`, then the Instance folder's name) |
+| `--context <ctx>` | the kube context (default: kubectl's current context) |
+
+**Environment**
+
+| Variable | Description |
+| --- | --- |
+| `NO_COLOR` | draws the git ssh key menu without highlight |
+
+**Output**: activity, activity on stderr only. See [Output](#output).
+
+**Decisions**: [ADR-0019](decisions/0019-one-converging-command-against-the-current-context.md), [ADR-0051](decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md), [ADR-0069](decisions/0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md), [ADR-0072](decisions/0072-the-docs-ship-inside-the-kit-and-an-instances-agents-md-indexes-them.md).
+
+<a id="down"></a>
+
+### `jr2 down`
+
+```sh
+jr2 down [--all] [--yes] [-n <ns>] [--context <ctx>]
+```
+
+Remove the instance from the cluster.
+
+--all: operator too; --yes: no confirmation.
+
+**Flags**
+
+| Flag | Description |
+| --- | --- |
+| `--all` | also uninstall the per-cluster operator |
+| `--yes` | do not ask for confirmation (for CI) |
+| `-n, --namespace <ns>` | the deployment's namespace (default: the config's `name`, then the Instance folder's name) |
+| `--context <ctx>` | the kube context (default: kubectl's current context) |
+
+**Output**: activity, activity on stderr only. See [Output](#output).
+
+**Decisions**: [ADR-0019](decisions/0019-one-converging-command-against-the-current-context.md).
+
+<a id="gc"></a>
+
+### `jr2 gc`
+
+```sh
+jr2 gc [--dry-run] [--repo-ttl <ttl>] [--context <ctx>]
+```
+
+Remove jr2's images that no live instance names, and Repo resources no Machine binds and no run attached lately.
+
+**Flags**
+
+| Flag | Description |
+| --- | --- |
+| `--dry-run` | print what would be removed, and remove nothing |
+| `--repo-ttl <ttl>` | how long since a run last attached before an unbound Repo is garbage (default: 7d) |
+| `--context <ctx>` | the kube context (default: kubectl's current context) |
+
+**Output**: activity, activity on stderr only. See [Output](#output).
+
+**Decisions**: [ADR-0039](decisions/0039-image-garbage-collects-by-reachability.md), [ADR-0051](decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md).
+
+<a id="kit-push"></a>
+
+### `jr2 kit push`
+
+```sh
+jr2 kit push <registry>
+```
+
+Mirror the published kit images into a registry.
+
+The v0.6.0 kit images (harness, operator, orchestrator) from their canonical home, and the Custodian's pinned Envoy from its own, for a cluster whose `kitRegistry` names the registry.
+
+**Arguments**
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `registry` | yes | the registry to mirror into, as `kitRegistry` names it |
+
+**Output**: result, one JSON result on stdout, and activity on stderr. See [Output](#output).
+
+**Decisions**: [ADR-0044](decisions/0044-kit-images-live-at-a-canonical-home-a-self-host-mirrors-it.md), [ADR-0059](decisions/0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md), [ADR-0069](decisions/0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md).
+
+<a id="run"></a>
+
+### `jr2 run`
+
+```sh
+jr2 run <workflow> [--input <json>] [--detach] [--url <u>] [-n <ns>] [--context <ctx>]
+```
+
+Start a run; stream activity, print terminal result.
+
+--detach: just print the runId and return.
+
+A Chart that the door refuses prints one line for each rule that it fails.
+
+Exits 0 only for a run that ended done, and 1 for every other end: failed, error, cancelled, lost, drifted, or parked before it settled; a failed run prints its reason.
+
+**Arguments**
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `workflow` | yes | the workflow to start, or a named Chart as `<wrapper>/<name>` |
+
+**Flags**
+
+| Flag | Description |
+| --- | --- |
+| `--input <json>` | the run's input, as a JSON object (default: {}) |
+| `--detach` | print the runId and return, and do not stream |
+| `--url <u>` | attach to a specific orchestrator (skips kube entirely) |
+| `-n, --namespace <ns>` | the deployment's namespace (default: the config's `name`, then the Instance folder's name) |
+| `--context <ctx>` | the kube context (default: kubectl's current context) |
+
+**Environment**
+
+| Variable | Description |
+| --- | --- |
+| `JR2_URL` | the orchestrator to attach to, when `--url` is not given |
+| `JR2_TOKEN` | the Instance token to send: with `--url` / `JR2_URL` the only one, and otherwise used in place of the one read from the cluster |
+
+**Output**: result, one JSON result on stdout, and activity on stderr. See [Output](#output).
+
+**Decisions**: [ADR-0009](decisions/0009-cli-and-instance-interface.md), [ADR-0070](decisions/0070-a-machine-lends-its-parts-to-a-chart.md), [ADR-0073](decisions/0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md).
+
+<a id="runs"></a>
+
+### `jr2 runs`
+
+```sh
+jr2 runs [--workflows] [--url <u>] [-n <ns>] [--context <ctx>]
+```
+
+List live runs; "placing" names the Workspaces that wait for capacity, and "status `<runId>`" says why.
+
+The Workflows a run can start on stderr, each with its origin (machine, chart file, chart) and a Chart wrapper's Charts under it; --workflows prints that listing as the result.
+
+A runtime Chart has no verb: PUT or DELETE /workflows/`<wrapper>`/charts/`<name>` with the Instance token (an MCP or curl), then `jr2 run <wrapper>/<name>` starts it.
+
+**Flags**
+
+| Flag | Description |
+| --- | --- |
+| `--workflows` | print the Workflow listing as the JSON result instead |
+| `--url <u>` | attach to a specific orchestrator (skips kube entirely) |
+| `-n, --namespace <ns>` | the deployment's namespace (default: the config's `name`, then the Instance folder's name) |
+| `--context <ctx>` | the kube context (default: kubectl's current context) |
+
+**Environment**
+
+| Variable | Description |
+| --- | --- |
+| `JR2_URL` | the orchestrator to attach to, when `--url` is not given |
+| `JR2_TOKEN` | the Instance token to send: with `--url` / `JR2_URL` the only one, and otherwise used in place of the one read from the cluster |
+
+**Output**: result, one JSON result on stdout, and activity on stderr. See [Output](#output).
+
+**Decisions**: [ADR-0009](decisions/0009-cli-and-instance-interface.md), [ADR-0064](decisions/0064-a-workspace-waits-for-capacity.md), [ADR-0070](decisions/0070-a-machine-lends-its-parts-to-a-chart.md).
+
+<a id="status"></a>
+
+### `jr2 status`
+
+```sh
+jr2 status [runId] [--json] [--url <u>] [-n <ns>] [--context <ctx>]
+```
+
+Print a run's current status (read-through), or the instance's Repos, per node, when given none.
+
+A failed run prints its reason beside the result: failed: `<reason>`.
+
+**Arguments**
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `runId` | no | the run to read; without one, the instance's Repos |
+
+**Flags**
+
+| Flag | Description |
+| --- | --- |
+| `--json` | print the one report object on stdout instead of the table (without a runId) |
+| `--url <u>` | attach to a specific orchestrator (skips kube entirely) |
+| `-n, --namespace <ns>` | the deployment's namespace (default: the config's `name`, then the Instance folder's name) |
+| `--context <ctx>` | the kube context (default: kubectl's current context) |
+
+**Environment**
+
+| Variable | Description |
+| --- | --- |
+| `JR2_URL` | the orchestrator to attach to, when `--url` is not given |
+| `JR2_TOKEN` | the Instance token to send: with `--url` / `JR2_URL` the only one, and otherwise used in place of the one read from the cluster |
+
+**Output**: `jr2 status <runId>`: result, one JSON result on stdout, and activity on stderr; `jr2 bare status`: report, a table on stdout, or the one report object with `--json`. See [Output](#output).
+
+**Decisions**: [ADR-0048](decisions/0048-the-orchestrator-boots-without-its-repos.md), [ADR-0051](decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md), [ADR-0073](decisions/0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md).
+
+<a id="logs"></a>
+
+### `jr2 logs`
+
+```sh
+jr2 logs <runId> [-f] [--url <u>] [-n <ns>] [--context <ctx>]
+```
+
+Replay a run's status; -f to follow until it settles.
+
+**Arguments**
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `runId` | yes | the run, or a unique prefix of its id |
+
+**Flags**
+
+| Flag | Description |
+| --- | --- |
+| `-f, --follow` | follow until the run settles |
+| `--url <u>` | attach to a specific orchestrator (skips kube entirely) |
+| `-n, --namespace <ns>` | the deployment's namespace (default: the config's `name`, then the Instance folder's name) |
+| `--context <ctx>` | the kube context (default: kubectl's current context) |
+
+**Environment**
+
+| Variable | Description |
+| --- | --- |
+| `JR2_URL` | the orchestrator to attach to, when `--url` is not given |
+| `JR2_TOKEN` | the Instance token to send: with `--url` / `JR2_URL` the only one, and otherwise used in place of the one read from the cluster |
+
+**Output**: result, one JSON result on stdout, and activity on stderr. See [Output](#output).
+
+**Decisions**: [ADR-0009](decisions/0009-cli-and-instance-interface.md).
+
+<a id="send"></a>
+
+### `jr2 send`
+
+```sh
+jr2 send <runId> --event CANCEL [--keep] [--url <u>] [-n <ns>] [--context <ctx>]
+jr2 send <runId> --gate <gate> --event <name> [--input <json>] [--url <u>] [-n <ns>]
+[--context <ctx>]
+```
+
+Abandon a live run, or deliver a workflow event to an open gate.
+
+With `--event CANCEL`, `--keep`: abandon a live run and destroy its Workspaces; --keep keeps them for inspection until the idle timeout.
+
+With `--gate <gate>`, `--event <name>`, `--input <json>`: deliver a workflow event to an open gate.
+
+**Arguments**
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `runId` | yes | the run, or a unique prefix of its id |
+
+**Flags**
+
+| Flag | Description |
+| --- | --- |
+| `--event <name>` | CANCEL (run control), or with --gate an event the gate accepts Required. |
+| `--gate <gate>` | the open gate to deliver the event to |
+| `--input <json>` | the event's input, as a JSON object (with --gate) |
+| `--keep` | with --event CANCEL: keep the Workspaces for inspection until the idle timeout |
+| `--url <u>` | attach to a specific orchestrator (skips kube entirely) |
+| `-n, --namespace <ns>` | the deployment's namespace (default: the config's `name`, then the Instance folder's name) |
+| `--context <ctx>` | the kube context (default: kubectl's current context) |
+
+**Environment**
+
+| Variable | Description |
+| --- | --- |
+| `JR2_URL` | the orchestrator to attach to, when `--url` is not given |
+| `JR2_TOKEN` | the Instance token to send: with `--url` / `JR2_URL` the only one, and otherwise used in place of the one read from the cluster |
+
+**Output**: activity, activity on stderr only. See [Output](#output).
+
+**Decisions**: [ADR-0009](decisions/0009-cli-and-instance-interface.md), [ADR-0011](decisions/0011-workflow-defined-events.md), [ADR-0013](decisions/0013-the-agent-reaches-its-machine-through-a-container-it-cannot-read.md), [ADR-0025](decisions/0025-cancel-ends-a-run-stop-parks-it.md).
+
+<a id="run-ids"></a>
+
+## Run ids
+
+Any `<runId>` above may be abbreviated to a unique prefix (4+ chars, git-style); an ambiguous prefix lists the candidates and fails rather than guessing.
+
+<a id="env"></a>
+
+## Env
+
+The Instance's .env is loaded before any verb; a variable already set in the environment wins.
+
+<a id="output"></a>
+
+## Output
+
+Result verbs (kit push, run, runs, status `<runId>`, logs) print one JSON result on stdout and activity on stderr, so `jr2 run … | jq` yields the result; report verbs (version, bare status) print a table on stdout, or the one object with --json; activity verbs (init, check, up, down, gc, send) print activity alone.
+
+<a id="exit-codes"></a>
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | ok |
+| 1 | runtime error |
+| 2 | usage |