@runtypelabs/cli 2.37.0 → 2.40.2

package/README.md

@@ -643,8 +643,93 @@ Manage agents.
 | `agents create -n <name>`          | Create a new agent                              |
 | `agents execute <id> -m <message>` | Execute an agent with a message                 |
 | `agents task <agent> -g <goal>`    | Run a multi-session task (see Marathon section) |
+| `agents ensure <file>`             | Converge a definition from a file               |
 | `agents delete <id>`               | Delete an agent                                 |
 
+`agents execute` and `dispatch --agent` take `--alias <name>` or `--version-id <id>`
+to run a specific version. Supply at most one; omit both to run the agent's saved
+configuration.
+
+#### Release aliases
+
+An agent runs an immutable **version**. A **release alias** is a named, mutable
+pointer that selects which version runs: `live` is built in and never expires, and
+any name matching `^[a-z0-9][a-z0-9-]{0,62}$` is a preview pointer. Every activation
+appends an append-only **deployment receipt**.
+
+| Subcommand                                                                     | Description                        |
+| ------------------------------------------------------------------------------ | ---------------------------------- |
+| `agents aliases list <agentId> [--include-archived]`                           | List the pointers, live first      |
+| `agents aliases get <agentId> <alias>`                                         | Read one pointer and its revision  |
+| `agents aliases activate <agentId> <alias> --version-id <id> [--revision <n>]` | Aim a pointer at one exact version |
+| `agents aliases archive <agentId> <alias> [--revision <n>] [--dry-run]`        | Stop a preview pointer resolving   |
+| `agents aliases archive <alias> --all [--dry-run]`                             | Archive that name on every agent   |
+| `agents aliases rollback <agentId> <alias> [--steps <n>] [--revision <n>]`     | Re-aim at the previous version     |
+| `agents deployments list <agentId> [--alias <name>]`                           | Read the deployment history        |
+
+Moving an existing `live` pointer requires the revision you read, sent as `If-Match`:
+
+```bash
+runtype agents aliases get agent_abc live --json
+runtype agents aliases activate agent_abc live --version-id agentver_9 --revision 12 \
+  --idempotency-key deploy-2026-09-06-1
+```
+
+`agents ensure <file> --deploy <alias>` saves and activates in one step;
+`--release publish|none` is the older spelling of the same thing, and supplying both
+is refused. A non-live deploy leaves live unchanged.
+
+##### Cleaning up a pull request's preview
+
+A preview pointer expires 14 days after the last converge that touched it, and a
+sweep archives it then. Archiving on PR close is the primary cleanup; the TTL is
+only the backstop. `--all` archives the name on every agent the pull request
+touched, each under the revision it just read, and reports a stale revision
+without stopping. It is idempotent: a second run finds nothing active.
+
+```yaml
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  archive-preview:
+    runs-on: ubuntu-latest
+    steps:
+      - run: npx @runtypelabs/cli agents aliases archive "pr-${{ github.event.number }}" --all
+        env:
+          RUNTYPE_API_KEY: ${{ secrets.RUNTYPE_API_KEY }}
+```
+
+An organization holds at most 50 active preview aliases and one agent at most 10.
+Creating one past either limit is refused with `PREVIEW_ALIAS_LIMIT`; archiving one
+frees the quota immediately.
+
+#### Promoting between organizations
+
+`runtype agents promote` moves an agent from one organization to another with two
+credentials. Neither key is ever a command-line argument: name the environment
+variable that holds it.
+
+| Subcommand                                          | Description                                             |
+| --------------------------------------------------- | ------------------------------------------------------- |
+| `agents promote prepare <name> --alias <candidate>` | Stage the definition at a preview pointer in the target |
+| `agents promote validate <manifest>`                | Re-plan and report unresolved references (exit 1)       |
+| `agents promote evaluate <manifest> --suite <id>`   | Run a suite against the staged version                  |
+| `agents promote activate <manifest> [--alias live]` | Deploy that exact staged version                        |
+
+```bash
+export RUNTYPE_SOURCE_API_KEY=... RUNTYPE_TARGET_API_KEY=...
+runtype agents promote prepare "Pricing Assistant" --alias promote-482
+runtype agents promote validate promotion.json
+runtype agents promote evaluate promotion.json --suite evalsuite_1
+runtype agents promote activate promotion.json
+```
+
+Credentials never cross organizations, secrets stay `{{secret:NAME}}` references
+resolved by the target, and the manifest carries only ids and hashes. `evaluate`
+reports its result and nothing gates activation on it.
+
 ### `runtype persona`
 
 Set up the [Persona](https://github.com/runtypelabs/persona) chat widget against Runtype: create an agent, create a client token, and output an embed snippet.
@@ -673,6 +758,39 @@ runtype dispatch --flow <id> --variable key=value --variable key2=value2
 runtype dispatch --flow <id> --no-stream --json
 ```
 
+#### Execution inputs and machine-readable results
+
+`dispatch`, `flows run`, and `agents execute` accept `--inputs <json>` or
+`--inputs-file <file|->` for typed input variables. Use `-` to read a JSON object
+from stdin. `--variable key=value` remains a repeatable **string** input; use JSON
+for numbers, booleans, arrays, objects, and null. Conflicting input sources and
+duplicate keys are rejected rather than silently overwritten.
+
+```bash
+runtype flows run flow_example --inputs '{"limit":5,"enabled":true}' --json
+printf '%s' '{"customer":{"name":"Alyss"}}' | runtype dispatch --flow flow_example --inputs-file - --json
+runtype agents execute agent_example --message "Summarize these items" --inputs '{"items":[1,2,3]}' --json
+runtype dispatch --flow flow_example --messages-file conversation.json --jsonl
+```
+
+`--messages-file <file|->` supplies a JSON array of messages instead of `--message`.
+Only one source may consume stdin. Input-bearing `agents execute` requests use
+the dispatch API so variables reach the runtime; requests without input variables
+retain the agent execution endpoint.
+
+For these execution commands, `--json` writes one final JSON value to stdout,
+without progress prose or text deltas. `--jsonl` writes structured events one per
+line followed by an `execution_summary` event (also used for buffered results or
+errors). The two formats are mutually exclusive. Diagnostics go to stderr.
+Exit codes are **0** for completion, **1** for failed execution, invalid input,
+authentication errors, or incomplete streams, and **2** when awaiting input or
+approval. Awaiting results do not claim `success: true`. A paused execution is
+not automatically approved or restarted.
+
+CRUD commands that accept a JSON-object `--from-file` through the shared file
+reader also accept `--from-file -`. This does not change commands whose input
+files have a different format, such as batch record-ID arrays.
+
 ### `runtype prompts`
 
 Manage prompts.
@@ -706,6 +824,17 @@ Manage batch operations.
 | `batch status <id>`                          | Check batch job status (`--watch`) |
 | `batch cancel <id>`                          | Cancel a batch job                 |
 
+`batch status --watch` polls in both terminal and nonterminal environments. Use
+`--timeout <ms>` (default `300000`) and `--interval <ms>` (default `2000`) to bound
+the local wait; these options require `--watch`. With `--json`, stdout contains
+one final result, while progress is sent to stderr. Failed or cancelled batches,
+completed batches with failed records, and local timeouts exit nonzero. Timing out
+stops watching only: it does not cancel or resubmit the server batch.
+
+```bash
+runtype batch status batch_example --watch --timeout 600000 --interval 2000 --json
+```
+
 ### `runtype eval`
 
 Manage evaluations.
@@ -855,16 +984,59 @@ runtype config path
 
 Valid config keys: `apiUrl`, `defaultModel`, `defaultTemperature`, `outputFormat`, `streamResponses`
 
-### Global Options
+### Effective target and headless safeguards
+
+```bash
+# Inspect the resolved endpoint and credential source without exposing the key
+runtype config context --json
+
+# Fail closed if the target or authenticated organization differs
+runtype --no-input --expect-api-url https://api.runtype.com --expect-org org_example \
+  flows run flow_example --inputs '{"limit":5}' --json
+
+# Headless mode is not consent: destructive commands also require --yes
+runtype --no-input records delete record_example --yes
+```
 
-All commands support these flags:
+API URL precedence is **`--api-url` > `RUNTYPE_API_URL` > saved `apiUrl` config >
+stored credential endpoint > production**. Saved URL configuration now affects
+ordinary API commands, not just configuration display. If an old saved value is
+stale, reset it or explicitly select your intended endpoint before upgrading
+automation. Conflicting explicit API URL flags are rejected.
+
+`config context` is an offline, redacted inspection; its stored organization hint
+is not proof of current server identity (`orgVerified: false`). `--expect-org`
+checks the authenticated identity against the server before API actions. With
+either expected-target guard, an invalid environment credential does not silently
+fall back to a different stored credential.
+
+Claim/verify tokens remain bound to their issuing server; the expected-URL guard
+also checks that actual endpoint. Anonymous registration and claim/verify reject
+`--expect-org`, since that ceremony cannot prove the resulting organization.
+
+Implicit login never prompts when stdin is not a terminal. `--no-input` also
+disables interactive startup and prompts in terminal sessions; delete, bulk-delete,
+revoke, and reset commands require explicit `--yes` in this mode. Marathon and
+`agents task` reject `--no-input`; use their documented headless JSON mode instead.
+
+### Global Options
 
-| Flag                 | Description              |
-| -------------------- | ------------------------ |
-| `--json`             | Output in JSON format    |
-| `--tty` / `--no-tty` | Force TTY / non-TTY mode |
-| `-v, --verbose`      | Enable verbose output    |
-| `--api-url <url>`    | Override API URL         |
+Root flags are forwarded to subcommands; output support depends on the command:
+
+| Flag                     | Description                             |
+| ------------------------ | --------------------------------------- |
+| `--json`                 | Output in JSON format                   |
+| `--tty` / `--no-tty`     | Force TTY / non-TTY mode                |
+| `-v, --verbose`          | Enable verbose output                   |
+| `--api-url <url>`        | Override API URL                        |
+| `--expect-api-url <url>` | Assert effective API endpoint           |
+| `--expect-org <id>`      | Assert authenticated organization       |
+| `--no-input`             | Disable prompts; does not imply consent |
+| `-y, --yes`              | Explicit destructive-action consent     |
+
+`--tty` / `--no-tty` are available on commands with terminal rendering. The strict
+single-result JSON contract above applies to the three execution commands and
+`batch status --watch`, not every legacy command.
 
 ## Development