@jr2/orchestrator 0.6.0 → 0.7.0

package/docs/reference/cli.md

@@ -7,7 +7,7 @@ description: "Every jr2 command: its synopsis, its arguments, flags and env vars
 
 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).
+Commands: [`version`](#version), [`init`](#init), [`check`](#check), [`up`](#up), [`down`](#down), [`gc`](#gc), [`kit push`](#kit-push), [`run`](#run), [`runs`](#runs), [`workflows`](#workflows), [`gates`](#gates), [`status`](#status), [`watch`](#watch), [`logs`](#logs), [`send`](#send), [`steer`](#steer), [`whoami`](#whoami), [`hooks`](#hooks), [`caller token`](#caller-token), [`caller rotate`](#caller-rotate), [`workspace ls`](#workspace-ls), [`workspace shell`](#workspace-shell), [`workspace forward`](#workspace-forward), [`workspace rm`](#workspace-rm), [`completion`](#completion).
 
 <a id="global-options"></a>
 
@@ -17,10 +17,10 @@ These address the deployment; each lists the verbs that take it ([ADR-0019](deci
 
 | 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) |
+| `-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), [`workflows`](#workflows), [`gates`](#gates), [`status`](#status), [`watch`](#watch), [`logs`](#logs), [`send`](#send), [`steer`](#steer), [`whoami`](#whoami), [`hooks`](#hooks), [`caller token`](#caller-token), [`caller rotate`](#caller-rotate), [`workspace ls`](#workspace-ls), [`workspace shell`](#workspace-shell), [`workspace forward`](#workspace-forward), [`workspace rm`](#workspace-rm) |
+| `--context <ctx>` |  | the kube context (default: kubectl's current context) | [`version`](#version), [`up`](#up), [`down`](#down), [`gc`](#gc), [`run`](#run), [`runs`](#runs), [`workflows`](#workflows), [`gates`](#gates), [`status`](#status), [`watch`](#watch), [`logs`](#logs), [`send`](#send), [`steer`](#steer), [`whoami`](#whoami), [`hooks`](#hooks), [`caller token`](#caller-token), [`caller rotate`](#caller-rotate), [`workspace ls`](#workspace-ls), [`workspace shell`](#workspace-shell), [`workspace forward`](#workspace-forward), [`workspace rm`](#workspace-rm) |
+| `--url <u>` | `JR2_URL` | attach to a specific orchestrator (skips kube entirely) | [`version`](#version), [`run`](#run), [`runs`](#runs), [`workflows`](#workflows), [`gates`](#gates), [`status`](#status), [`watch`](#watch), [`logs`](#logs), [`send`](#send), [`steer`](#steer), [`whoami`](#whoami), [`hooks`](#hooks) |
+|  | `JR2_TOKEN` | the Caller's credential to send, which makes the CLI that Caller: with `--url` / `JR2_URL` the only one, and otherwise used in place of the Instance token read from the cluster | [`run`](#run), [`runs`](#runs), [`workflows`](#workflows), [`gates`](#gates), [`status`](#status), [`watch`](#watch), [`logs`](#logs), [`send`](#send), [`steer`](#steer), [`whoami`](#whoami), [`hooks`](#hooks) |
 
 ## Commands
 
@@ -44,18 +44,16 @@ Also spelled `jr2 --version`.
 | --- | --- |
 | `--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) |
+
+Also takes `--url <u>`, `-n, --namespace <ns>`, `--context <ctx>`, `JR2_URL`: see [Global options](#global-options).
 
 **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).
+**Output**: report, a table or lines on stdout, or their JSON with `--json`, where the verb has it. 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).
 
@@ -97,7 +95,7 @@ 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.
+Runs the check that `jr2 up` runs before it stages the Assembly, and exits 1 with its refusal: a type error, a module that refuses to load (`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.
 
@@ -117,7 +115,7 @@ 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.
+Before the cluster work, sets the text between the jr2-docs markers in AGENTS.md to the docs index of the Kit version, and nothing else; a folder with no markers is left alone.
 
 **Flags**
 
@@ -125,9 +123,9 @@ Before the cluster work, sets the text between the jr2-docs markers in AGENTS.md
 | --- | --- |
 | `--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) |
+| `--skip-provider-preflight` | do not run the provider preflight: no check pod checks the models or reads an MCP server's tool list, so a check that fails while the model or server works does not stop the converge |
+
+Also takes `-n, --namespace <ns>`, `--context <ctx>`: see [Global options](#global-options).
 
 **Environment**
 
@@ -157,8 +155,8 @@ Remove the instance from the cluster.
 | --- | --- |
 | `--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) |
+
+Also takes `-n, --namespace <ns>`, `--context <ctx>`: see [Global options](#global-options).
 
 **Output**: activity, activity on stderr only. See [Output](#output).
 
@@ -180,7 +178,8 @@ Remove jr2's images that no live instance names, and Repo resources no Machine b
 | --- | --- |
 | `--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) |
+
+Also takes `--context <ctx>`: see [Global options](#global-options).
 
 **Output**: activity, activity on stderr only. See [Output](#output).
 
@@ -196,7 +195,7 @@ 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.
+The v0.7.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 it.
 
 **Arguments**
 
@@ -213,7 +212,8 @@ The v0.6.0 kit images (harness, operator, orchestrator) from their canonical hom
 ### `jr2 run`
 
 ```sh
-jr2 run <workflow> [--input <json>] [--detach] [--url <u>] [-n <ns>] [--context <ctx>]
+jr2 run <workflow> [--input <json>] [--detach] [--drop-held] [--url <u>] [-n <ns>]
+[--context <ctx>]
 ```
 
 Start a run; stream activity, print terminal result.
@@ -224,6 +224,8 @@ 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.
 
+A standing Workflow: jr2 starts its run, so `jr2 run` only resumes a paused one, prints the new run, and returns.
+
 **Arguments**
 
 | Argument | Required | Description |
@@ -236,32 +238,54 @@ Exits 0 only for a run that ended done, and 1 for every other end: failed, error
 | --- | --- |
 | `--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) |
+| `--drop-held` | resume a paused standing Workflow with no held item: its held items are not carried |
 
-**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 |
+Also takes `--url <u>`, `-n, --namespace <ns>`, `--context <ctx>`, `JR2_URL`, `JR2_TOKEN`: see [Global options](#global-options).
 
 **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).
+**Decisions**: [ADR-0009](decisions/0009-cli-and-instance-interface.md), [ADR-0017](decisions/0017-pool-over-a-source-port.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>]
+jr2 runs [--status <s>] [--workflow <name>] [--since <when>] [--url <u>] [-n <ns>]
+[--context <ctx>]
 ```
 
-List live runs; "placing" names the Workspaces that wait for capacity, and "status `<runId>`" says why.
+List runs, newest first (live by default); "placing" names the Workspaces that wait for capacity, and "status `<runId>`" says why.
+
+Each run is a summary: runId, workflow, status, reason, startedBy, startedAt, endedAt, assembly, openGates; an ended run is listed while jr2 keeps it (runs.retain).
+
+`jr2 workflows` lists the Workflows that a run can start.
 
-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.
+**Flags**
+
+| Flag | Description |
+| --- | --- |
+| `--status <s>` | live (the default), ended, all, or a comma list such as done,failed,drifted |
+| `--workflow <name>` | only the runs of this Workflow |
+| `--since <when>` | only the runs that started since: a duration (2h, 7d) or an ISO-8601 time |
+
+Also takes `--url <u>`, `-n, --namespace <ns>`, `--context <ctx>`, `JR2_URL`, `JR2_TOKEN`: see [Global options](#global-options).
+
+**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-0030](decisions/0030-a-snapshot-names-the-machine-it-was-written-under.md), [ADR-0064](decisions/0064-a-workspace-waits-for-capacity.md), [ADR-0065](decisions/0065-a-persist-survives-a-crash-and-history-is-kept-for-a-set-time.md).
+
+<a id="workflows"></a>
+
+### `jr2 workflows`
+
+```sh
+jr2 workflows [--json] [--url <u>] [-n <ns>] [--context <ctx>]
+```
+
+List the Workflows that a run can start, each with its origin: machine, chart file or chart.
+
+A Chart wrapper's named Charts indent under it; an unrunnable one says why.
 
 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.
 
@@ -269,21 +293,41 @@ A runtime Chart has no verb: PUT or DELETE /workflows/`<wrapper>`/charts/`<name>
 
 | 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) |
+| `--json` | print the listing (GET /workflows) as the one report object instead of the tree |
 
-**Environment**
+Also takes `--url <u>`, `-n, --namespace <ns>`, `--context <ctx>`, `JR2_URL`, `JR2_TOKEN`: see [Global options](#global-options).
 
-| Variable | Description |
+**Output**: report, a table or lines on stdout, or their JSON with `--json`, where the verb has it. 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).
+
+<a id="gates"></a>
+
+### `jr2 gates`
+
+```sh
+jr2 gates [--workflow <name>] [--url <u>] [-n <ns>] [--context <ctx>]
+```
+
+List the open Gates that this Caller may answer, across the live runs, oldest first.
+
+Each Gate is an entry: runId, workflow, gate, path, accepts, acceptsNow, meta, openedAt, and hook (the Hook kinds that it hears); never a run's context.
+
+Needs the answer scope; a scope that names single Gates ({ workflow, gates }) lists only those Gates.
+
+`jr2 send <runId> --gate <gate> --event <name>` answers one.
+
+**Flags**
+
+| Flag | 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 |
+| `--workflow <name>` | only the Gates of this Workflow's runs |
+
+Also takes `--url <u>`, `-n, --namespace <ns>`, `--context <ctx>`, `JR2_URL`, `JR2_TOKEN`: see [Global options](#global-options).
 
 **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).
+**Decisions**: [ADR-0009](decisions/0009-cli-and-instance-interface.md), [ADR-0011](decisions/0011-workflow-defined-events.md), [ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md).
 
 <a id="status"></a>
 
@@ -308,56 +352,75 @@ A failed run prints its reason beside the result: failed: `<reason>`.
 | 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**
+Also takes `--url <u>`, `-n, --namespace <ns>`, `--context <ctx>`, `JR2_URL`, `JR2_TOKEN`: see [Global options](#global-options).
 
-| Variable | Description |
+**Output**: `jr2 status <runId>`: result, one JSON result on stdout, and activity on stderr; `jr2 bare status`: report, a table or lines on stdout, or their JSON with `--json`, where the verb has it. 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="watch"></a>
+
+### `jr2 watch`
+
+```sh
+jr2 watch <runId> [--json] [--url <u>] [-n <ns>] [--context <ctx>]
+```
+
+Follow a run's feed to its end, with the lines that `jr2 run` prints while it is attached.
+
+On attach it prints where the run is now; an ended run prints its last status once.
+
+**Arguments**
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `runId` | yes | the run, or a unique prefix of its id |
+
+**Flags**
+
+| Flag | 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 |
+| `--json` | print each status as one JSON line, and the other events on stderr |
 
-**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).
+Also takes `--url <u>`, `-n, --namespace <ns>`, `--context <ctx>`, `JR2_URL`, `JR2_TOKEN`: see [Global options](#global-options).
 
-**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).
+**Output**: report, a table or lines on stdout, or their JSON with `--json`, where the verb has it. See [Output](#output).
+
+**Decisions**: [ADR-0009](decisions/0009-cli-and-instance-interface.md), [ADR-0022](decisions/0022-observation-is-a-level-triggered-feed.md).
 
 <a id="logs"></a>
 
 ### `jr2 logs`
 
 ```sh
-jr2 logs <runId> [-f] [--url <u>] [-n <ns>] [--context <ctx>]
+jr2 logs <runId> [agent] [-f] [--url <u>] [-n <ns>] [--context <ctx>]
 ```
 
-Replay a run's status; -f to follow until it settles.
+Print a run's conversations as the Harness prints them, every Agent interleaved by time, or one Agent.
+
+Each line is `[<agent>] [<instance id>] [<label>] <text>`; Menu-only Agents too; a Working tool's result is never in it.
+
+Reads what the Orchestrator keeps of each conversation, so it works after the Sandbox is gone, while jr2 keeps the run (runs.retain); pod logs stay `kubectl logs`.
 
 **Arguments**
 
 | Argument | Required | Description |
 | --- | --- | --- |
 | `runId` | yes | the run, or a unique prefix of its id |
+| `agent` | no | one Agent slot, as `jr2 steer <runId>` lists it, or an Agent name (default: every Agent) |
 
 **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) |
+| `-f, --follow` | print each new entry as it is kept, until the run is not live and no conversation is open |
 
-**Environment**
+Also takes `--url <u>`, `-n, --namespace <ns>`, `--context <ctx>`, `JR2_URL`, `JR2_TOKEN`: see [Global options](#global-options).
 
-| 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**: report, a table or lines on stdout, or their JSON with `--json`, where the verb has it. See [Output](#output).
 
-**Output**: result, one JSON result on stdout, and activity on stderr. See [Output](#output).
-
-**Decisions**: [ADR-0009](decisions/0009-cli-and-instance-interface.md).
+**Decisions**: [ADR-0009](decisions/0009-cli-and-instance-interface.md), [ADR-0023](decisions/0023-the-harness-prints-the-conversation.md), [ADR-0065](decisions/0065-a-persist-survives-a-crash-and-history-is-kept-for-a-set-time.md).
 
 <a id="send"></a>
 
@@ -389,20 +452,296 @@ With `--gate <gate>`, `--event <name>`, `--input <json>`: deliver a workflow eve
 | `--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**
+Also takes `--url <u>`, `-n, --namespace <ns>`, `--context <ctx>`, `JR2_URL`, `JR2_TOKEN`: see [Global options](#global-options).
 
-| Variable | Description |
+**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="steer"></a>
+
+### `jr2 steer`
+
+```sh
+jr2 steer <runId> [agent] [text] [--url <u>] [-n <ns>] [--context <ctx>]
+```
+
+Send a Steering message to one Agent of a live run, or list the Agent slots that can hear one.
+
+An open Turn of the slot hears it at its next step boundary; else, or when that Turn ends first, the slot's next Turn in its Machine instance hears it.
+
+With a runId alone it prints the run's Agent slots, each with open and steerable; `jr2 status` prints the messages sent to the run, in `steering`.
+
+Needs the steer scope for the run's Workflow.
+
+**Arguments**
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `runId` | yes | the run, or a unique prefix of its id |
+| `agent` | no | the Agent slot, as the run's list names it |
+| `text` | no | the message, at most 16 KiB |
+
+Also takes `--url <u>`, `-n, --namespace <ns>`, `--context <ctx>`, `JR2_URL`, `JR2_TOKEN`: see [Global options](#global-options).
+
+**Output**: `jr2 steer <runId> <agent> <text>`: activity, activity on stderr only; `jr2 steer <runId>`: result, one JSON result on stdout, and activity on stderr. See [Output](#output).
+
+**Decisions**: [ADR-0002](decisions/0002-duplex-streaming-actor.md), [ADR-0062](decisions/0062-jr2-briefs-the-agent-on-its-seat-never-on-its-task.md), [ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md).
+
+<a id="whoami"></a>
+
+### `jr2 whoami`
+
+```sh
+jr2 whoami [--url <u>] [-n <ns>] [--context <ctx>]
+```
+
+Print the Caller this credential is: how jr2 knows it, its name, what it may do, and whom it acts for.
+
+On a kube context the Caller is token/instance, on behalf of the kube user; with --url and JR2_TOKEN it is that token's Caller.
+
+Needs no scope, so a credential that may do nothing still sees why.
+
+Also takes `--url <u>`, `-n, --namespace <ns>`, `--context <ctx>`, `JR2_URL`, `JR2_TOKEN`: see [Global options](#global-options).
+
+**Output**: result, one JSON result on stdout, and activity on stderr. See [Output](#output).
+
+**Decisions**: [ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md).
+
+<a id="hooks"></a>
+
+### `jr2 hooks`
+
+```sh
+jr2 hooks <name> [--limit <n>] [--url <u>] [-n <ns>] [--context <ctx>]
+```
+
+Print a Hook's log: each delivery that jr2 keeps (runs.retain), newest first, and what the door did with it.
+
+A line is a handshake, a delivery and its outcome, a repeat (seen), a payload the parse refused (with zod's issues), a request the kind could not read, or a failed follow-up post.
+
+Needs the Instance token: no scope opens it.
+
+**Arguments**
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `name` | yes | the Hook, as `hooks` in jr2.config.ts names it |
+
+**Flags**
+
+| Flag | Description |
+| --- | --- |
+| `--limit <n>` | how many lines, newest first (default 50, at most 1000) |
+
+Also takes `--url <u>`, `-n, --namespace <ns>`, `--context <ctx>`, `JR2_URL`, `JR2_TOKEN`: see [Global options](#global-options).
+
+**Output**: result, one JSON result on stdout, and activity on stderr. See [Output](#output).
+
+**Decisions**: [ADR-0011](decisions/0011-workflow-defined-events.md), [ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md).
+
+<a id="caller-token"></a>
+
+### `jr2 caller token`
+
+```sh
+jr2 caller token <name> [-n <ns>] [--context <ctx>]
+```
+
+Print a named Caller token's value, read from its Secret over the kube API.
+
+`jr2 up` makes the value once, for each name that `callers.tokens` declares.
+
+**Arguments**
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `name` | yes | the named Caller token, as `callers.tokens` declares it |
+
+Also takes `-n, --namespace <ns>`, `--context <ctx>`: see [Global options](#global-options).
+
+**Output**: value, one value alone on stdout, for `$(…)`, and activity on stderr. See [Output](#output).
+
+**Decisions**: [ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md).
+
+<a id="caller-rotate"></a>
+
+### `jr2 caller rotate`
+
+```sh
+jr2 caller rotate <name> [-n <ns>] [--context <ctx>]
+```
+
+Make a new value for a named Caller token; the old value stops working.
+
+Returns when the Orchestrator has loaded the new digest (about a minute), so the old value is then refused; after 150s it fails, and the old value works until the load.
+
+Prints no value: `jr2 caller token <name>` prints the new one.
+
+**Arguments**
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `name` | yes | the named Caller token, as `callers.tokens` declares it |
+
+Also takes `-n, --namespace <ns>`, `--context <ctx>`: see [Global options](#global-options).
+
+**Output**: activity, activity on stderr only. See [Output](#output).
+
+**Decisions**: [ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md).
+
+<a id="workspace-ls"></a>
+
+### `jr2 workspace ls`
+
+```sh
+jr2 workspace ls [run] [--json] [-n <ns>] [--context <ctx>]
+```
+
+List the Workspaces: handle, Sandbox name, Workflow, phase, age, and whether a run holds it.
+
+Reads the Sandbox CRs over the kube API, with no Orchestrator: kube RBAC is the gate.
+
+A handle is `<run-prefix>`/<workspace path>, or the Sandbox's name.
+
+Held: the run's Lease marked it (a live run, or one that an Orchestrator crash left); released: its run is over; idle: no Lease renewed it for the idle timeout.
+
+**Arguments**
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `run` | no | only the Workspaces of this run, or of a prefix of its id |
+
+**Flags**
+
+| Flag | 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 |
+| `--json` | print the one report object on stdout instead of the table |
+
+Also takes `-n, --namespace <ns>`, `--context <ctx>`: see [Global options](#global-options).
+
+**Output**: report, a table or lines on stdout, or their JSON with `--json`, where the verb has it. See [Output](#output).
+
+**Decisions**: [ADR-0009](decisions/0009-cli-and-instance-interface.md), [ADR-0012](decisions/0012-workspace-wrapper-machine.md), [ADR-0021](decisions/0021-workspace-continuity-is-a-lease-that-answers-back.md).
+
+<a id="workspace-shell"></a>
+
+### `jr2 workspace shell`
+
+```sh
+jr2 workspace shell <ws> [-- cmd] [--user] [-n <ns>] [--context <ctx>]
+```
+
+A shell in the Workspace as its Agents work: started by the Harness's spawner in the Agents' Landlock domain, with the Workspace's granted Stand-ins and its folder.
+
+It never reaches the control Stand-in or a Stand-in that the Workspace does not grant.
+
+`jr2 workspace shell <ws> -- git status` runs one command with no terminal: Ctrl-C ends jr2, and the command gets the end of its input but no signal, so one that ignores it (a dev server) runs on.
+
+**Arguments**
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `ws` | yes | the Workspace: `<run-prefix>`/`<path>`, or its Sandbox's name |
+| `-- cmd` | no | one command to run in place of a shell |
+
+**Flags**
+
+| Flag | Description |
+| --- | --- |
+| `--user` | a shell in the User Container (`kubectl exec -c user`), which needs a shell in its image |
+
+Also takes `-n, --namespace <ns>`, `--context <ctx>`: see [Global options](#global-options).
 
 **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).
+**Decisions**: [ADR-0009](decisions/0009-cli-and-instance-interface.md), [ADR-0076](decisions/0076-an-agents-control-credential-lives-only-where-no-workspace-code-runs.md).
+
+<a id="workspace-forward"></a>
+
+### `jr2 workspace forward`
+
+```sh
+jr2 workspace forward <ws> <port> [--stdio] [-n <ns>] [--context <ctx>]
+```
+
+Forward a local port to a port in the Workspace's pod; prints 127.0.0.1:`<port>` and holds it until Ctrl-C.
+
+Ssh: Host *.jr2 with ProxyCommand jr2 workspace forward %h 22 --stdio -n `<ns>`, then ssh <sandbox name>.jr2.
+
+There is no Service for the User Container: the forward goes through the kube API.
+
+**Arguments**
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `ws` | yes | the Workspace: `<run-prefix>`/`<path>`, its Sandbox's name, or `<name>`.jr2 |
+| `port` | yes | the port in the Sandbox pod |
+
+**Flags**
+
+| Flag | Description |
+| --- | --- |
+| `--stdio` | carry one connection on stdin and stdout, for an ssh ProxyCommand |
+
+Also takes `-n, --namespace <ns>`, `--context <ctx>`: see [Global options](#global-options).
+
+**Output**: value, one value alone on stdout, for `$(…)`, and activity on stderr. See [Output](#output).
+
+**Decisions**: [ADR-0005](decisions/0005-sandbox-pod-composition.md), [ADR-0009](decisions/0009-cli-and-instance-interface.md).
+
+<a id="workspace-rm"></a>
+
+### `jr2 workspace rm`
+
+```sh
+jr2 workspace rm <ws> [-n <ns>] [--context <ctx>]
+```
+
+Remove a Sandbox that no run holds: released, or idle past its idle timeout.
+
+Refuses the Sandbox of a live run: cancel the run first; there is no --force.
+
+The keepalive's age is read on the API server's clock.
+
+**Arguments**
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `ws` | yes | the Workspace: `<run-prefix>`/`<path>`, or its Sandbox's name |
+
+Also takes `-n, --namespace <ns>`, `--context <ctx>`: see [Global options](#global-options).
+
+**Output**: activity, activity on stderr only. See [Output](#output).
+
+**Decisions**: [ADR-0009](decisions/0009-cli-and-instance-interface.md), [ADR-0021](decisions/0021-workspace-continuity-is-a-lease-that-answers-back.md).
+
+<a id="completion"></a>
+
+### `jr2 completion`
+
+```sh
+jr2 completion <shell>
+```
+
+Print the shell completion script.
+
+The script asks this jr2 for each completion, so the verbs and flags are the command table's.
+
+It completes Workspace handles, live run ids, Workflow names and a run's Agent slots too; a lookup that takes more than 2 s offers nothing.
+
+Bash: source <(jr2 completion bash); zsh: source <(jr2 completion zsh); fish: jr2 completion fish | source.
+
+**Arguments**
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `shell` | yes | bash, zsh or fish |
+
+**Output**: value, one value alone on stdout, for `$(…)`, and activity on stderr. See [Output](#output).
+
+**Decisions**: [ADR-0009](decisions/0009-cli-and-instance-interface.md).
 
 <a id="run-ids"></a>
 
@@ -420,7 +759,7 @@ The Instance's .env is loaded before any verb; a variable already set in the env
 
 ## 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.
+Result verbs (kit push, run, runs, gates, status `<runId>`, steer `<runId>`, whoami, hooks) print one JSON result on stdout and activity on stderr, so `jr2 run … | jq` yields the result; report verbs (version, workflows, bare status, watch, logs, workspace ls) print a table or lines on stdout, or their JSON with --json (watch: one JSON line for each status; logs has no --json); activity verbs (init, check, up, down, gc, send, steer `<runId>` `<agent>` `<text>`, caller rotate, workspace shell, workspace rm) print activity alone; value verbs (caller token, workspace forward, completion) print one value alone on stdout, for `$(…)`, and activity on stderr.
 
 <a id="exit-codes"></a>