@brainbase-labs/cli 0.46.0 → 0.48.0

package/README.md

@@ -53,8 +53,9 @@ brainbase task send <task-id> "Use the revised approach instead" --json
 brainbase task stop <task-id>
 ```
 
-`send` prints the input ID and generation to stderr before submitting and reports delivery
-status in stdout. Initial acceptance can say **delivery pending** while the
+`send` reports the input ID and delivery status in stdout. The input ID and
+generation needed to recover a send are printed only when one did not finish:
+on an error, on an unconfirmed receipt, or when it is interrupted. Initial acceptance can say **delivery pending** while the
 server determines whether native steering is available. Native steering follows
 the harness's own timing. A confirmed fallback says **queued for the next turn**.
 `submitted` means the harness has received the input; it does not mean the agent
@@ -67,8 +68,8 @@ Resource-scoped keys can lack that read access when task-read enforcement is ena
 If the read fails, no mutation is sent. Use `--generation <n>` to bypass the read only
 with a trusted current cutoff for a new operation, or the original cutoff for a retry.
 A concurrent Stop prevents a send from joining newer work with an older generation.
-If the HTTP response is lost or you press Ctrl-C, keep the input ID and generation,
-and repeat the exact message with `--input-id <uuid> --generation <n>` to recover that request safely. Reusing an ID
+If the HTTP response is lost or you press Ctrl-C, the command prints the input ID and generation;
+repeat the exact message with `--input-id <uuid> --generation <n>` to recover that request safely. Reusing an ID
 does not replay an existing input. A **delivery unconfirmed** receipt means
 the agent may already have received the instruction; deliberately resend
 without `--input-id` only if you want to retry it as a new input.
@@ -97,15 +98,18 @@ this confirms admission or delivery, not task success.
 
 ## Renaming and labelling tasks
 
-Change a task's title or its metadata labels, including while it runs:
+Change a task's title, its metadata labels or its model, including while it runs:
 
 ```sh
 brainbase task update <task-id> --title "Nightly smoke run" --metadata env=staging
 brainbase task update <task-id> --unset-metadata env --json
+brainbase task update <task-id> --model claude-sonnet-5-5
 ```
 
 `--metadata` and `--unset-metadata` keep every label you do not name.
-`--clear-metadata` removes them all, and `--clear-title` removes the title. See
+`--clear-metadata` removes them all, and `--clear-title` removes the title.
+`--model` switches the model the task's next turn runs on; a turn already
+running keeps its model. See
 [the command reference](docs/reference/commands.mdx) for every flag.
 
 ## Benchmark management
@@ -332,7 +336,7 @@ Playbook files carry a small YAML frontmatter (`title`, `description`) — the C
 | `BRAINBASE_API_URL` | Legacy KLS host override. Control requests use `/api/cli`; it is also the fallback for model-proxy and registry traffic. |
 | `BRAINBASE_PROXY_URL` | Override the model-proxy host used when enabling harness tracking. |
 | `BRAINBASE_REGISTRY_URL` | Override the registry API host. |
-| `BRAINBASE_TOKEN` | Use a PAT instead of the stored login session. The only way a PAT authenticates a control-plane command — see [Auth](#auth). |
+| `BRAINBASE_TOKEN` | Use a PAT instead of the stored login session. Outranks both the session and the PAT saved in `token.json`. See [Auth](#auth). |
 | `BRAINBASE_HOME` | Where local state lives (default: `~/.brainbase`) |
 
 Model-proxy and registry traffic fall back through `BRAINBASE_API_URL`,
@@ -340,30 +344,26 @@ the server captured at login, and finally `https://api.v1.brainbaselabs.com`.
 
 ## Auth
 
-Three credentials, and which ones a command considers depends on the service
-it talks to:
+Every command tries three credentials, in this order:
 
-| Commands | Credentials tried, in order |
-|-|-|
-| `agent`, `orchestration`, `link`, `unlink`, `sync`, `status`, `team` | `BRAINBASE_TOKEN`, then the `auth.json` session |
-| `template`, `skill`, `token` | `BRAINBASE_TOKEN`, then the session, then `token.json` |
-| `task` commands | `BRAINBASE_TOKEN`, then the session, then `token.json` — the last only when no session is configured |
-| `benchmark` control-plane commands | `BRAINBASE_TOKEN`, then the session |
+1. `BRAINBASE_TOKEN`
+2. the `auth.json` login session, renewed first if it has expired
+3. the PAT that `brainbase token create` saved in `~/.brainbase/token.json`,
+   when there is no session or it could not be renewed. A PAT minted by a
+   different account than the session is never used in its place.
 
-`brainbase whoami` (or `--json`) reports which one is active.
+`brainbase whoami` (or `--json`) reports which one is active. It renews an
+expired session itself, so what it reports is what the next command will use.
 
-**For CI:** `brainbase token create` saves the PAT to `~/.brainbase/token.json`,
-and control-plane commands never read that file — `brainbase agent push` needs
-the token in `BRAINBASE_TOKEN`:
+**For CI:** a runner has no `token.json`, so hand it the PAT as a secret:
 
 ```bash
 export BRAINBASE_TOKEN=bbpat_…
 brainbase agent push
 ```
 
-Do not bake a `~/.brainbase` directory into a build image: a leftover
-`auth.json` outranks the stored PAT, and every control-plane command starts
-failing once its session expires.
+Do not bake a `~/.brainbase` directory into a build image. Ship
+`BRAINBASE_TOKEN` as a secret instead.
 
 An explicit PAT does not inherit routing from a stored login. Set
 `BRAINBASE_CONTROL_PLANE_URL` when using a PAT against a non-default MAS host.