@shardflux/cli 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.9.0 — 2026-10-04 (not yet published)
+
+- `shard ws hint <workspace>` explicitly stages a parked workspace ahead of a VM tool call, without waiting for restore or resuming a suspended workspace.
+
 Every command and option the README shows is available from the version named here. Breaking changes ship in minor
 releases and are marked **Breaking**.
 
@@ -7,6 +11,20 @@ releases and are marked **Breaking**.
 
 Needs `@shardflux/sdk` 0.14.0 or later.
 
+### Sign up from an agent
+
+- `shard signup [--email <email>] [--name <name>] [--no-codex] [--no-setup] [--tool <tool>...]`: creates the account,
+  signs in and runs `shard setup` in one command, with no browser and no password. With the Codex CLI signed in with
+  ChatGPT on the machine, Codex refreshes its login (`codex app-server`) and the ID token from `$CODEX_HOME/auth.json`
+  verifies the email (the account starts with its trial; an existing account of that identity or email is signed
+  in). Without one, `--email` creates an account that works at once on the Free plan. `--json`: `{created, access,
+  method, user, setup}`.
+- `shard verify [<code>]`: emails a 6-digit verification code (and asks for it on a terminal), or confirms one.
+  Nothing is signed out; an account from `shard signup` gets its trial.
+- `shard auth login --codex` signs in with the Codex login; `shard auth step-up --codex` confirms a sensitive action
+  with it instead of the password.
+- After signing in with an unverified email, the next step printed is `shard verify`.
+
 ### Workspaces working at once
 
 - A command whose workspace call finds every workspace the plan allows to work at once busy is sent again after
@@ -21,6 +39,55 @@ Needs `@shardflux/sdk` 0.14.0 or later.
 - `shard usage` says `retained state  used up: new workspaces and forks are refused (...)` when the Retained state
   allowance's `cap_state` is `storage_blocked` (`enforcement` `storage_block`).
 
+### Inbound ports
+
+Additive. Serve a port of a processful workspace at its own private HTTPS URL; a request wakes a parked or suspended
+workspace.
+
+- `shard ws port expose <id|key> <port>`: the URL and how requests get in (`--json`: the API's port object
+  `{port, url, created_at, callback}`). Idempotent.
+- `shard ws port ls <id|key>`: port, URL, exposure time and callback URL (`--json`: `{ports}`).
+- `shard ws port close <id|key> <port>` (`--json`: `{workspace_id, port, closed}`).
+- `shard ws port token <id|key> <port> [--ttl 1m..24h]`: the port token alone on stdout, how to send it on stderr
+  (`--json`: `{token, expires_at, url}`).
+- `shard ws port link <id|key> <port> [--ttl 1m..7d] [--path /...]`: a URL that opens the port in a browser
+  (`--json`: `{url, expires_at}`).
+- `shard ws port callback <id|key> <port> [--revoke]`: the port's callback URL for webhooks and OAuth redirects, shown
+  once (`--json`: `{url, created_at}`; with `--revoke`: `{workspace_id, port, revoked}`).
+- `ports` is an alias of `port`. A port outside 1-65535, a `--ttl` out of range or not in whole seconds, and a
+  `--path` without a leading `/` exit 2 before any request; a file-first workspace is refused before any port
+  request. Hints for `port_not_exposed` (expose it first) and `port_limit` (close a port first).
+
+### Memory across platform upgrades
+
+- The cold-boot note and `--json --timing` name the new reason `runtime_retired` (the runtime the workspace was
+  suspended on was retired after an announced window): `note: workspace <id> resumed from its saved disk; running
+  processes were restarted (runtime_retired)`.
+
+### Resize a workspace
+
+- `shard ws resize <id|key> [--memory MIB] [--held MIB] [--fixed|--elastic] [--cpu MILLIS] [--disk GIB]
+  [--timeout D] [--timing]`: changes the caps of a running, suspended or stopped workspace without a restart
+  (`PATCH /v1/workspaces/{id}/caps` through `workspace.resize()`), and waits until the resize has finished. It prints
+  per resource the change and when it applies, e.g. `memory  2048 → 6144 MiB  now` or `memory  4096 → 8192 MiB
+  elastic, held 1024 MiB  on resume`, with what was clamped to a limit or applied in part. `--json` prints the result
+  (`workspace_id`, `operation_id`, `state`, the `memory` / `cpu` / `disk` named, `caps`, and `operation` when one was
+  waited for). No resource flag, `--fixed` with `--elastic`, or `--held` with `--fixed` are usage errors (exit 2) with
+  no request. Ctrl-C names the operation, which continues server side.
+
+### Memory hint for commands
+
+- `shard ws exec --resource-hint auto|light|heavy` and `shard ws exec-start --resource-hint …` send `resource_hint`
+  with the exec start: `heavy` gives an elastic workspace its memory before the command starts, `light` starts it at
+  once, `auto` (the default) decides from the command. Without the flag nothing is sent. On a file-first workspace
+  `--resource-hint` is a usage error (exit 2).
+
+### Elastic memory
+
+- `--memory-held` on `shard ws open` / `shard ws fork` no longer needs `--allocation-mode elastic`: without a mode the
+  API decides (with elastic-by-default enabled for the organization a new workspace is elastic; otherwise
+  `requires_elastic`). With `--allocation-mode fixed` it stays a usage error.
+
 ## 0.8.1 (not yet published)
 
 Needs `@shardflux/sdk` 0.13.1 or later.

package/README.md

@@ -37,14 +37,11 @@ Or run it without installing: `npx @shardflux/cli --help`. The unscoped
 
 ## Quick start
 
-No account yet? Everything happens in the terminal; a person only opens the emailed link (or hands
-it to `shard`) and, for a paid plan, pays in Stripe Checkout.
+No account yet? One command (0.9.0+) creates it, signs you in and saves an API key: no browser, no
+password. With the Codex CLI signed in with ChatGPT on this machine, your email is verified by it.
 
 ```sh
-printf '%s\n' "$PASSWORD" | shard auth register --email you@example.com --name "Ada Lovelace"
-shard auth verify-email 'https://app.shardflux.dev/auth/verify-email#token=...'   # the link from the email
-printf '%s\n' "$PASSWORD" | shard auth login --email you@example.com
-shard setup                                   # organization, project and an API key, saved
+shard signup                                  # or: shard signup --email you@example.com
 shard workspaces open acme/demo --template python-node-browser
 shard ws exec acme/demo -- python3 -c 'print(40 + 2)'
 shard files write acme/demo /home/user/notes.txt --from notes.txt
@@ -111,14 +108,14 @@ npm test 2>&1 | tail -n 60 | shard feedback --category bug --workspace acme/demo
 `shard` is built to be driven by an agent: no browser, no prompts when standard input is not a
 terminal, `--json` on every command, secrets only on standard input, and documented exit codes.
 
-1. **Account:** `printf '%s\n' "$PASSWORD" | shard auth register --email <email>` (answers the same
-   whether or not the address exists). Ask the person for the link in the verification email and run
-   `shard auth verify-email '<link>'` (the whole link, quoted).
-2. **Sign in:** `printf '%s\n' "$PASSWORD" | shard auth login --email <email> --json`. With two-factor
-   authentication it exits 4 with `mfa_required`: ask the person for the code, then
-   `shard auth mfa --code <code>` (within 10 minutes), or pass `--code` to `login`.
-3. **Set up:** `shard setup --json`: an organization, a project and an API key with every workspace
-   tool, saved in the credentials file. Idempotent: run it again any time.
+1. **Account (0.9.0+):** `shard signup --json`. With the Codex CLI signed in with ChatGPT on the
+   machine it signs up (or signs in) verified by that login; otherwise pass `--email <email>` and the
+   account works at once on the Free plan. It then runs `shard setup`: an organization, a project and
+   an API key with every workspace tool, saved in the credentials file. With two-factor authentication
+   it exits 4 with `mfa_required`: ask the person for the code, then `shard auth mfa --code <code>`.
+2. **Verify the email** (an `--email` signup, to start the trial): `shard verify --json` emails a
+   6-digit code; ask the person for it, then `shard verify <code>`. Nothing is signed out.
+3. **Set up again any time:** `shard setup --json` is idempotent.
 4. **Work:** `shard ws open <key> --template <slug> --json`, `shard ws exec <key> -- <cmd>`,
    `shard files ...` use the saved key.
 5. **A paid plan:** `shard billing plans`, then `shard billing upgrade <plan> --json` prints the Stripe
@@ -132,12 +129,15 @@ terminal, `--json` on every command, secrets only on standard input, and documen
 7. **Feedback:** send `shard feedback` as you work, the moment something fails, confuses you or is
    missing, or your user asks for an improvement (see [Feedback](#feedback-agents-use-this-while-you-work)).
 
-What stays human: reading the verification email, entering a card in Stripe Checkout, and the
-authenticator app's codes.
+What a person does: entering a card in Stripe Checkout, the authenticator app's codes, and (for an
+`--email` signup) reading the 6-digit code.
 
 ## Accounts and sign-in (0.5.0+)
 
 ```sh
+shard signup [--email you@example.com] [--name "Ada Lovelace"] [--no-codex] [--no-setup]   # 0.9.0+
+shard verify [<code>]                                  # 0.9.0+: emails a 6-digit code, then confirms it
+shard auth login --codex                               # 0.9.0+: sign in with the Codex login on this machine
 printf '%s\n' "$PASSWORD" | shard auth register --email you@example.com [--name "Ada Lovelace"]
 shard auth verify-email '<link from the email>'        # or just the token in it
 shard auth resend-verification                         # signed in, email not verified yet
@@ -147,6 +147,7 @@ shard auth status                                      # session and saved key,
 shard auth sessions [--revoke <session-id>]            # browser and CLI sessions
 shard auth logout [--all]
 printf '%s\n' "$PASSWORD" | shard auth step-up [--code 123456]
+shard auth step-up --codex [--code 123456]             # 0.9.0+: confirm with the linked Codex login
 printf '%s\n%s\n' "$CURRENT" "$NEW" | shard auth password change
 shard auth password reset --email you@example.com
 printf '%s\n' "$NEW" | shard auth password reset-confirm '<link from the email>'
@@ -157,6 +158,12 @@ shard auth totp disable --code 123456
 shard auth totp recovery-codes
 ```
 
+- **`shard signup`** (0.9.0+) asks the Codex CLI on this machine to refresh its ChatGPT login
+  (`codex app-server`) and sends the ID token from `$CODEX_HOME/auth.json` (default `~/.codex`), never
+  Codex's access or refresh token. The account is verified and starts with its trial; an account that
+  already uses that ChatGPT identity or email is signed in instead. Without a Codex login, `--email`
+  creates an account that works at once on the Free plan; `shard verify` starts the trial.
+  `--no-codex` uses `--email` even when Codex is signed in; `--no-setup` skips `shard setup`.
 - **Passwords never come from arguments** (`--password` is refused). On a terminal `shard` asks without
   echo (a new password twice); otherwise it reads standard input, one line per secret: `auth password
   change` reads the current password, then the new one. Emailed links and tokens are single-use
@@ -177,7 +184,7 @@ shard auth totp recovery-codes
   it from standard input (or asks), sets it, and otherwise prints the `auth password reset-confirm`
   command to run.
 - After `auth login`, `shard` prints who you are, whether the email is verified, your organizations
-  and the next step (`shard setup`, or `shard auth verify-email`).
+  and the next step (`shard setup`, or `shard verify`).
 
 ## Setup (0.5.0+)
 
@@ -378,8 +385,8 @@ shows the status; `shard version --check` asks now (`--json`: `{"cli", "sdk", "u
 | `workspaces list [--state S] [--prefix P] [--lifetime persistent\|session\|any] [--purpose standard\|template_draft\|template_test\|any] [--include-deleted] [--all] [--limit N] [--cursor C]` | One page, or every page with `--all`. The next cursor is printed on stderr. By default only persistent standard workspaces are listed. A file-first workspace's state reads `running (file-first)` (0.5.0+). |
 | `workspaces get <id\|key>` | One workspace (deleted ones included), with the startup of its template's start commands and services (0.4.0+): a failed step shows its exit code, reason and output tail. Its mode, and a file-first workspace's tree revision (0.5.0+). Its memory (0.8.0+): `fixed 4096 MiB`, or `elastic: promised …, held …, plugged +… MiB`. The template version whose [immutable paths](#immutable-paths-080) it has mounted (0.8.0+): `immutable paths  v3 (mounted read-only)`. |
 | `workspaces inputs <id\|key>` | The workspace's text inputs (0.4.0+). |
-| `workspaces exec <id\|key> [--cwd D] [--env K=V]... [--timeout T] [--stdin F\|-] [-v] [--execution-id ID] [--output-limit N] [--burst [--burst-vcpus N] [--burst-memory MIB]] -- <cmd> [args...]` | Runs argv with no shell. Output is streamed (in the start request itself, 0.8.0+) and resumes from byte offsets after dropped connections. `shard` exits with the command's exit code. Ctrl-C cancels the command. `-v` (0.5.0+) then prints the session id and exit status on stderr, and the memory grow the command waited for on an elastic workspace (0.8.0+; `--json`: `memory_grow`). `--cwd` is an absolute path (default `/home/user`); a relative one is refused (`invalid_cwd`, exit 2). A command that could not start (a `--cwd` that is not a directory, a program not on `PATH`) exits 6 with the workspace's reason and a hint (0.5.1+; before, it exited 1 with no output). On a file-first workspace (0.5.0+) the command runs as an execution instead: see [File-first workspaces](#file-first-workspaces). `--burst` (0.8.0+): [burst execution](#burst-execution-080). |
-| `workspaces exec-start <id\|key> [--session-id ID] [--cwd D] [--timeout T] [--stdin-open] -- <cmd> [args...]`, `workspaces exec-read <id\|key> <session-id> [--follow]`, `workspaces exec-cancel <id\|key> <session-id> [--grace D]` | Background commands (0.8.0+): start a command and return at once, read its output and state (`--follow` streams it to its exit and exits with its code; while it runs `exec-read` exits 5), stop it. See [Background commands](#background-commands-080). |
+| `workspaces exec <id\|key> [--cwd D] [--env K=V]... [--timeout T] [--stdin F\|-] [-v] [--execution-id ID] [--output-limit N] [--resource-hint auto\|light\|heavy] [--burst [--burst-vcpus N] [--burst-memory MIB]] -- <cmd> [args...]` | Runs argv with no shell. Output is streamed (in the start request itself, 0.8.0+) and resumes from byte offsets after dropped connections. `shard` exits with the command's exit code. Ctrl-C cancels the command. `-v` (0.5.0+) then prints the session id and exit status on stderr, and the memory grow the command waited for on an elastic workspace (0.8.0+; `--json`: `memory_grow`). `--cwd` is an absolute path (default `/home/user`); a relative one is refused (`invalid_cwd`, exit 2). A command that could not start (a `--cwd` that is not a directory, a program not on `PATH`) exits 6 with the workspace's reason and a hint (0.5.1+; before, it exited 1 with no output). On a file-first workspace (0.5.0+) the command runs as an execution instead: see [File-first workspaces](#file-first-workspaces). `--burst` (0.8.0+): [burst execution](#burst-execution-080). `--resource-hint` (0.9.0+): [elastic memory](#elastic-memory-080). |
+| `workspaces exec-start <id\|key> [--session-id ID] [--cwd D] [--timeout T] [--stdin-open] [--resource-hint auto\|light\|heavy] -- <cmd> [args...]`, `workspaces exec-read <id\|key> <session-id> [--follow]`, `workspaces exec-cancel <id\|key> <session-id> [--grace D]` | Background commands (0.8.0+): start a command and return at once, read its output and state (`--follow` streams it to its exit and exits with its code; while it runs `exec-read` exits 5), stop it. See [Background commands](#background-commands-080). |
 | `executions get <id\|key> <execution-id> [--wait D]` | The result of a file-first workspace's execution (0.5.0+): its output, then what ran. Exits with the command's code, 6 if the execution failed or was lost, 5 while it still runs. |
 | `files read <id\|key> <path> [--out F]` | Raw bytes to stdout, or to a local file. |
 | `files write <id\|key> <path> [--from F\|-] [--append] [--no-parents] [--if-revision N]` | Atomic write. The default source is stdin. `--if-revision` (0.5.0+): file-first workspaces only, see [Tree revisions](#tree-revisions). |
@@ -391,6 +398,7 @@ shows the status; `shard version --check` asks now (`--json`: `{"cli", "sdk", "u
 | `workspaces suspend <id\|key> --durable [--timeout T]` | (0.7.0+) Suspend and wait until the copy is in durable storage. See "Durable storage". |
 | `workspaces suspend <id\|key> --when-idle D` / `--cancel-when-idle` | (0.5.1+) Suspend once the workspace has been idle for `D` (0 to 1h; `0` = as soon as it is idle, 0.6.1+), or cancel that. See "Suspend when idle". |
 | `workspaces fork <id\|key> <new-key> [caps] [--allocation-mode fixed\|elastic] [--memory-held N] [--wait]` | Fork into a new key. Without caps the fork keeps the source's caps and memory allocation (0.8.0+). With `--wait` the API holds the fork until the copy runs and returns it ready in the same request (0.8.0+; `--timing` shows one `request` phase marked `(held)`). |
+| `workspaces resize <id\|key> [--memory MIB] [--held MIB] [--fixed\|--elastic] [--cpu MILLIS] [--disk GIB] [--timeout 5m] [--timing]` | Change the memory, CPU and disk of a running or suspended workspace without a restart (0.9.0+). Prints per resource the change and when it applies (`now`, `on resume`, `next start`). See [Resize a workspace](#resize-a-workspace-090). |
 | `workspaces delete <id\|key> --yes [--wait]` | Delete the workspace. Tool access ends at once. After deletion finishes, the key can open a new workspace ID. |
 | `workspaces close <id\|key> [--wait]` | End a session workspace now: it is deleted, and the key then opens a new workspace. A persistent workspace is refused (`not_session`). |
 | `workspaces reset <id\|key> --yes [--wait]` | Layered workspaces: wipe every change and restart on the template. The previous state stays restorable for 7 days. |
@@ -398,6 +406,8 @@ shows the status; `shard version --check` asks now (`--json`: `{"cli", "sdk", "u
 | `workspaces changes <id\|key> [--path P] [--hash] [--summary] [--all] [--limit N] [--cursor C]` | What a layered, running workspace changed against its template. |
 | `workspaces sessions <id\|key>` | Attributed agent sessions: label, principal and tokens issued. |
 | `workspaces secrets <id\|key> [--set NAME]... [--clear]` | Show the secret names bound to the workspace and their status, or replace them. |
+| `workspaces port expose <id\|key> <port>`, `workspaces port ls <id\|key>`, `workspaces port close <id\|key> <port>` | Serve a port of the workspace at its own private HTTPS URL, list the exposed ports, close one (0.9.0+; see [Inbound ports](#inbound-ports-090)). |
+| `workspaces port token <id\|key> <port> [--ttl D]`, `workspaces port link <id\|key> <port> [--ttl D] [--path P]`, `workspaces port callback <id\|key> <port> [--revoke]` | A port token (printed alone), a link that opens the port in a browser, the port's callback URL for webhooks and OAuth redirects (0.9.0+). |
 | `secrets create <NAME> [--from-file F] [--description T] [--tool T]... [--allow-workspace ID]... [--org ID [--allow-project ID]... [--all-projects]]` | Create a secret. The value comes from standard input or `--from-file`, never from an argument. |
 | `secrets list [--org ID] [--include-deleted] [--all]`, `secrets get <id\|NAME>` | Secret metadata. Values are never shown. |
 | `secrets update <id\|NAME> [--description T] [--tool T]... [--allow-workspace ID]... [--any-workspace] [--allow-project ID]... [--all-projects] [--clear-projects]` | Change the description or usage permissions. |
@@ -650,19 +660,40 @@ shard ws suspend acme/demo --cancel-when-idle
 
 ## Elastic memory (0.8.0+)
 
-Give a workspace a large memory promise while it holds only what it uses. It idles at `--memory-held` (default
-1024 MiB) and grows before each command starts, so builds and test runners see the memory they need from their first
-instruction.
+A workspace can hold only the memory its commands use and grow up to `--memory-mib` when they need more; billing counts
+the memory it holds. It idles at `--memory-held` (default 1024 MiB). Package installs, test runners, compilers and
+bundlers get their memory before they start, so they see what they need from their first instruction; everything else
+starts at once and the workspace grows while it runs.
 
 ```sh
 shard ws open acme/demo --template python-node-browser --memory-mib 8192 --allocation-mode elastic
 shard ws get acme/demo                  # memory  elastic: promised 8192 MiB, held 1024 MiB, plugged +3072 MiB
 shard ws exec acme/demo -v -- npm test  # memory grow  delivered 1024 -> 4096 MiB in 175 ms
+shard ws exec acme/demo --resource-hint heavy -- python3 train.py   # 0.9.0+: memory first, then the command
 ```
 
-The layout takes effect at the workspace's next start. `--json` output carries `memory` on the workspace and
+`--allocation-mode fixed` gives a static allocation of `--memory-mib`. `--resource-hint` (0.9.0+) is `auto` (the
+default: decided from the command), `heavy` or `light`. `--json` output carries `memory` on the workspace and
 `memory_grow` on a command that grew it.
 
+## Resize a workspace (0.9.0+)
+
+Change the memory, CPU and disk of any workspace, running or suspended, fixed or elastic, without a restart:
+
+```sh
+$ shard ws resize acme/demo --memory 6144 --disk 20
+Resized acme/demo (0f6c…), running:
+memory  2048 → 6144 MiB  now
+disk    10 → 20 GiB      now
+
+$ shard ws resize acme/demo --elastic --held 1024    # switch modes live
+```
+
+Memory changes live, and disks grow online. A suspended workspace gets its new size when it resumes, before its first
+call. CPU changes live within the vCPUs the workspace booted with; a larger CPU size applies at the next start. Each
+resource says when it applies (`now`, `on resume` or `next start`), and the new caps are stored, so every later start
+uses them. `--json` prints the result with `applies_at` per resource and the stored `caps`.
+
 ## Burst execution (0.8.0+)
 
 Run one heavy command, such as a cold build or a full test suite, on a larger VM without resizing the workspace:
@@ -695,6 +726,31 @@ shard ws exec-cancel acme/demo build-1 --grace 10s
   code and output.
 - `exec-cancel` sends SIGTERM, then SIGKILL after `--grace` (default 5s, at most 60s).
 
+## Inbound ports (0.9.0+)
+
+Serve a port of a workspace at its own HTTPS URL: a preview of the app your agent is building, a webhook receiver, an
+OAuth redirect, a live view. A request wakes a parked or suspended workspace and is answered once it runs. Every port
+is private: a request carries a port token, a browser link's session, or arrives on the port's callback URL.
+
+```sh
+shard ws exec-start acme/demo -- python3 -m http.server 3000 --bind 0.0.0.0
+shard ws port expose acme/demo 3000          # https://3000-<handle>.shardflux.app
+curl -H "Authorization: Bearer $(shard ws port token acme/demo 3000)" https://3000-<handle>.shardflux.app/
+shard ws port link acme/demo 3000 --path /dashboard   # open it in a browser
+shard ws port callback acme/demo 3000        # register <url>webhooks/github with GitHub
+shard ws port close acme/demo 3000
+```
+
+- The server inside the workspace listens on `0.0.0.0`, not only `127.0.0.1`.
+- `expose` is idempotent: an exposed port keeps its URL, tokens, links and callback URL. `port ls` lists them.
+- `token` prints the token alone on stdout (`--ttl` 1m to 24h, default 1h). Send it as `Authorization: Bearer
+  <token>`, or as `X-Shardflux-Token` when the app reads `Authorization` itself.
+- `link` prints a URL that starts a browser session for the port (`--ttl` 1m to 7d, default 24h) and lands on
+  `--path`. Anyone with the link can open the port until it expires.
+- `callback` prints the callback URL once; a request to `<url><rest>` reaches `/<rest>` without a token. Running it
+  again replaces the URL; `--revoke` removes it.
+- `close` stops the port's tokens, links and callback URL at once.
+
 ## Start deadlines
 
 A queued open, resume or fork (`capacity_pending`) has a deadline 15 minutes after it was created.
@@ -833,6 +889,10 @@ printf %s "$NEW_KEY" | shard secrets rotate OPENAI_API_KEY
   - `secrets create`/`get`/`update` print the secret's metadata; `list`, `versions` and `access-log`
     print `{data, next_cursor}`; `rotate` prints `{secret, version}`; `delete` prints
     `{deleted, id, name, scope}`; `workspaces secrets` prints `{workspace_id, names, secrets}`.
+  - `workspaces port expose` prints the port `{port, url, created_at, callback}`; `port ls` prints `{ports}`;
+    `port token` prints `{token, expires_at, url}` (`jq -r .token`); `port link` prints `{url, expires_at}`;
+    `port callback` prints `{url, created_at}`; `port close` prints `{workspace_id, port, closed}` and
+    `port callback --revoke` prints `{workspace_id, port, revoked}` (0.9.0+).
   - Account commands (0.5.0+) print the API's objects too: lists are `{data, next_cursor}` (with
     `default_organization_id`, `default_project_id` or `saved_api_key_id` where a default applies);
     `auth login`/`auth mfa` print `{status, user, session: {expires_at, credentials_file}, organizations,
@@ -917,3 +977,7 @@ shard ws exec-input qm/project-42 qm-worker-1 --offset 5 --close
 ```
 
 Use the byte offset in each acknowledgement, including partial writes. `ws resume` can recover a failed workspace with its existing ID and disk. A completed delete frees the key; old IDs remain deleted. Protocol-error JSON includes `source`; HTTP 404 alone does not mean a workspace was deleted.
+
+### Prepare an imminent command (0.9.0+)
+
+Call `shard ws hint <workspace>` ahead of a tool call to stage a parked workspace while the input is prepared. It returns without waiting for restore. Resume a suspended workspace first. The hint is explicit; ordinary commands add no early hint.

package/dist/account-args.js

@@ -40,6 +40,30 @@ const VOLUME_WAIT = {
     timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (default 5m); the operation continues server side.' },
 };
 export const ACCOUNT_COMMANDS = [
+    // ---- agent signup (0.9.0+) -----------------------------------------------------------------------------
+    {
+        path: ['signup'],
+        summary: 'Create your account and get ready to run workspaces in one command: no browser, no password',
+        description: 'Signs up with the Codex login on this machine (ChatGPT): your email is verified by it, so the account starts with its trial, and an account that already uses that ChatGPT identity or email is signed in instead. Without a Codex login, pass --email: the account works at once on the Free plan, and "shard verify" starts the trial. Then it runs "shard setup" (organization, project and an API key, saved) unless --no-setup. Two-factor accounts: pass --code or type it at the prompt.',
+        positionals: [],
+        options: {
+            email: { type: 'string', value: '<email>', description: 'Your email address, used when there is no Codex login (or with --no-codex).' },
+            name: { type: 'string', value: '<display name>', description: 'Your name as others see it (setup names the organization after it).' },
+            codex: { type: 'boolean', description: 'Use the Codex login on this machine (default; --no-codex signs up with --email).' },
+            setup: { type: 'boolean', description: 'Run shard setup afterwards (default; --no-setup skips it).' },
+            tool: { type: 'string', multiple: true, value: '<tool>', description: 'Workspace tool the saved API key may use (repeatable; exec, files, pty, process, git, browser). Default: all.' },
+            ...SECOND_FACTOR,
+        },
+        examples: ['shard signup', 'shard signup --email you@example.com', 'shard signup --no-codex --email you@example.com --name "Ada Lovelace"'],
+    },
+    {
+        path: ['verify'],
+        summary: 'Verify your email with a 6-digit code: emails the code, then confirm it',
+        description: 'Without a code it emails one (valid 15 minutes) and, on a terminal, asks for it; otherwise pass it next: "shard verify <code>". Nothing is signed out and saved API keys keep working; an account from "shard signup" gets its trial.',
+        positionals: [{ name: 'code', required: false }],
+        options: {},
+        examples: ['shard verify', 'shard verify 123456'],
+    },
     // ---- sign-in (auth) ------------------------------------------------------------------------------------
     {
         path: ['auth', 'register'],
@@ -66,8 +90,12 @@ export const ACCOUNT_COMMANDS = [
         summary: 'Sign in: saves a session for this API in the credentials file (the password is read from standard input or a prompt)',
         description: 'Two-factor accounts: pass --code (or --recovery-code), or type the code at the prompt; without either the pending sign-in is saved and "shard auth mfa --code <code>" completes it within 10 minutes (exit 4 until then). Prints who you are, your organizations and the next step. A session lasts 30 days of use (90 at most). SHARDFLUX_SESSION_TOKEN, when set, is used instead of the saved session.',
         positionals: [],
-        options: { email: { type: 'string', value: '<email>', description: 'Your email address (required).' }, ...SECOND_FACTOR },
-        examples: [`printf '%s\\n' "$PASSWORD" | shard auth login --email you@example.com`, `printf '%s\\n' "$PASSWORD" | shard auth login --email you@example.com --code 123456`],
+        options: {
+            email: { type: 'string', value: '<email>', description: 'Your email address (required without --codex).' },
+            codex: { type: 'boolean', description: 'Sign in with the Codex login on this machine instead of a password (0.9.0+; creates the account when there is none).' },
+            ...SECOND_FACTOR,
+        },
+        examples: [`printf '%s\\n' "$PASSWORD" | shard auth login --email you@example.com`, `printf '%s\\n' "$PASSWORD" | shard auth login --email you@example.com --code 123456`, 'shard auth login --codex'],
     },
     {
         path: ['auth', 'mfa'],
@@ -98,9 +126,9 @@ export const ACCOUNT_COMMANDS = [
     {
         path: ['auth', 'step-up'],
         summary: 'Confirm your password (and code) for sensitive actions: valid 10 minutes',
-        description: 'Needed for two-factor changes, an email change, data exports and deletions. On a terminal "shard" asks by itself when the API requires it; scripts run this first. The password comes from standard input or a prompt; two-factor accounts add --code (or type it at the prompt).',
+        description: 'Needed for two-factor changes, an email change, data exports and deletions. On a terminal "shard" asks by itself when the API requires it; scripts run this first. The password comes from standard input or a prompt; with --codex (0.9.0+) the Codex login linked to the account confirms it instead. Two-factor accounts add --code (or type it at the prompt).',
         positionals: [],
-        options: { ...SECOND_FACTOR },
+        options: { codex: { type: 'boolean', description: 'Confirm with the Codex login on this machine instead of the password (accounts it signs in to).' }, ...SECOND_FACTOR },
         examples: [`printf '%s\\n' "$PASSWORD" | shard auth step-up`, `printf '%s\\n' "$PASSWORD" | shard auth step-up --code 123456`],
     },
     {