@runtypelabs/cli 2.39.0 → 2.40.3

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.