@hyperscale0/cli 1.0.329 → 1.0.332

package/AGENTS.md

@@ -31,16 +31,24 @@ and product IDs come from the login and the selected product. Lists accept
 pass `--idempotency-key` to retry safely. Without a TTY a missing required flag
 exits 2 and names the flag.
 
-Start with `hyperscale auth login --no-open --json`. The URL and code go to
-stderr. A person approves them in the browser. Rerun to resume a pending login.
-Verify with `hyperscale whoami --json`. To create an account, pipe the
+Check `hyperscale whoami --json` first. To sign in a founder who has an
+account, pipe their password on stdin to `auth login --email <email> --json`;
+it mails a six-digit code and exits. Ask the founder for the code, then run
+`auth login --code <code> --json`. To approve in a browser instead, run
+`auth login --no-open --json`: the first stdout line is `approval_needed` with
+the code and URL, and the last is `signed_in`. Rerun to resume a pending login.
+For CI, pipe a `hyperscale_pat_` token to `auth login --with-token`. To create an account, pipe the
 founder's password on stdin to `auth signup --email <email> --name <name>
 --company <company> --json`; it mails a six-digit code and exits. Ask the
 founder for the code, then run `auth signup --code <code> --json`. The account
 starts in sandbox. `auth verify` confirms an existing account's email the same
 way. Do not print or persist credentials in project files.
 
-Browser login creates a named agent member with its own CLI grant. Access
+Either login creates a named agent member with its own CLI grant. In sandbox
+it acts as the founder, `--on-behalf-of` included; `whoami` shows the
+founder's team role. The grant ends after 30 days, or 7 days unused, and so do
+sandbox keys `key create --name <name>` makes from it. `doctor` names where the
+token is stored. Access
 tokens last ten minutes; the CLI rotates the refresh token and keeps both in
 Keychain or a mode 0600 file. Logout removes them locally. Revoke the member or
 grant in the browser; `--revoke` only revokes a human PAT. Sandbox work within
@@ -48,18 +56,33 @@ the grant runs directly. A live action exits 3 with `agent_approval_required`
 and a browser link; a human approves it with their password. The CLI cannot
 approve its own work.
 
-`agent setup [claude-code|codex|cursor]` writes the Hyperscale MCP server into
-that host's project config and prints the file it wrote. The config reads a
-sandbox Product key from `HYPERSCALE_API_KEY` (`--key-env` names another
-variable) and never contains the key. `--oauth` writes browser sign-in instead.
+`agent setup [claude-code|codex|cursor]` uses the founder's CLI login to mint
+a named, sandbox-only agent credential (`agent_grant.create`). It keeps the
+token in the login's store, writes the host's MCP entry with
+`HYPERSCALE_TOKEN` as the bearer variable, and installs the skill into the
+host's skills folder. `agent token <host>` prints the stored token so the
+shell can export it as `HYPERSCALE_TOKEN`; MCP and the CLI then use the same
+door.
+`--oauth` writes browser sign-in instead and mints nothing.
+
+Credential order for product commands: `--api-key`, `HYPERSCALE_API_KEY`,
+`--token`, `HYPERSCALE_TOKEN`, then the stored login. A key never moves a
+command off the selected Product: a key for another Product exits 2 with
+`api_key_product_mismatch`, names both Products and says what to unset.
+`whoami` names the credential in use; `--verbose` adds grant and token ids.
+The Keychain item is keyed by the config folder, so two folders hold two
+logins; `doctor` names the item it reads.
 
 Every command accepts `--json`. Ordinary success is one JSON value on stdout;
 failure is an error object on stderr. Errors retain status, code, message,
 fix, details and available request, operation, receipt and trace IDs.
 JSON output has no ANSI codes, banners, spinners or prompts.
-Exit codes: 0 success, 1 failure, 2 usage error or HSX check or plan cannot
-proceed, 3 live action waiting for human approval, 4 not signed in or missing
-scope, 5 not found, 6 conflict such as a reused idempotency key.
+Exit codes: 0 success, 1 server refusal or failure, 2 usage (unknown command
+or option, or an argument, flag or input refused before any request; also an
+HSX check or plan that cannot proceed), 3 live action waiting for human
+approval, 4 not signed in or not allowed (401, 403), 5 not found (404), 6
+conflict with the current state (409). `refusals.js` holds the table;
+`help --json` prints it as `exitCodes`.
 
 `hsx watch --json` emits one JSON object per line with `type` set to `check`,
 `plan` or `error`. Check and plan events contain `data`; errors contain `error`.

package/README.md

@@ -24,6 +24,20 @@ Approve the URL and code in your browser. The CLI saves your login on this
 device. Use `--no-open` to approve on another device. A pending sign-in resumes
 when you run the command again.
 
+On a machine with no browser, sign in with your password and an emailed code:
+`hyperscale auth login --email you@example.com`. Without a terminal, pipe the
+password and finish in a second call:
+
+```sh
+printf '%s\n' "$PASSWORD" | hyperscale auth login --email you@example.com --json
+hyperscale auth login --code 123456 --json
+```
+
+A login ends after 30 days, or 7 days unused. `whoami` shows when.
+`hyperscale doctor` names where the token is stored: the macOS Keychain or a
+private file in the config folder. For CI, pipe a personal access token to
+`hyperscale auth login --with-token`, or set `HYPERSCALE_TOKEN`.
+
 To create an account without a browser, run `hyperscale auth signup`. It asks
 for your name, work email, company and a password, solves a short proof of work,
 and mails a six-digit code. Type the code and the CLI is signed in to the new
@@ -93,20 +107,20 @@ step that fails:
 ```json
 {
   "scenario": "A first rental",
-  "customers": { "maya": { "name": "Maya Brooks", "fund": "100000" } },
+  "customers": { "maya": { "name": "Maya Brooks", "fund": "1000" } },
   "steps": [
     {
       "create": "rental",
       "as": "camera",
       "by": "maya",
-      "fields": { "item": "Camera", "renter": "Maya", "price": "75000" }
+      "fields": { "item": "Camera", "renter": "Maya", "price": "750" }
     },
     { "run": "agree_rental", "on": "camera", "by": "maya" },
     { "advance": "4d" },
-    { "fund": "maya", "amount": "5000" },
+    { "fund": "maya", "amount": "50" },
     {
       "name": "Maya has her change",
-      "expect": { "balances": { "maya": { "settled": "30000" } } }
+      "expect": { "balances": { "maya": { "settled": "300.00" } } }
     }
   ]
 }
@@ -116,9 +130,10 @@ Each customer is created, given a sandbox account and funded first. `create`
 makes an object, `run` runs an action on it, `fund` adds sandbox money,
 `advance` moves the sandbox clock (`30m`, `4h`, `2d`, `1w` or an ISO time) and
 `expect` checks balances. A plain balance compares to `available`; an object
-can name `available`, `settled` or `pending`. Amounts are minor-unit strings,
-as in the API. Funding and actions need the Product key in
-`HYPERSCALE_API_KEY`. `scenario init` writes a working example for the
+can name `available`, `settled` or `pending`. Amounts are major units, as
+`fund` takes them (`"750"` or `"750.50"` in SAR), in money fields and action
+input too; the runner sends the API minor units. Funding and actions need the
+Product key in `HYPERSCALE_API_KEY`. `scenario init` writes a working example for the
 Product.
 
 ```sh
@@ -137,7 +152,7 @@ with the `whsec_` secret it prints. The secret stays the same for a profile,
 so your handler keeps verifying across restarts. `log tail` reads the developer
 log of your API calls with their request ids; `log explain` shows one call's
 inputs, error, fix and receipt with secrets redacted. `doctor` checks the CLI,
-config directory, API, login, Product and sandbox clock and prints a fix for
+config directory, API, login, token store, Product and sandbox clock and prints a fix for
 each failure. `export records` prints transfers, receipts or one account's
 statements as CSV.
 
@@ -180,6 +195,10 @@ hyperscale architect chat --brief "Review this product" --json
 hyperscale open
 ```
 
+`key create --name` names the key, and `key list` shows each name and expiry.
+A key made from a CLI login ends when that login ends; `key create` prints the
+date. A key made in the browser lasts 90 days.
+
 API access covers all published operations. A request that needs browser
 review prints a URL and a saved reference. Approve it, then use `api resume`.
 Approval alone does not mean the request completed.
@@ -233,14 +252,28 @@ run `npm install -g @hyperscale0/cli@latest`.
 
 `hyperscale help --json` returns the whole command tree with flags, examples,
 scopes and operations; `help --all` adds the advanced operations.
-Use `hyperscale <group> <command> --help` for one command. Exit codes are 0 for
-success, 1 for failure, 2 for a usage error or an HSX check or plan that cannot
-proceed, 3 for a live action waiting for approval, 4 for a missing login or
-scope, 5 for not found and 6 for a conflict.
+Use `hyperscale <group> <command> --help` for one command.
+
+| Exit | Meaning                                                                                                              |
+| ---- | -------------------------------------------------------------------------------------------------------------------- |
+| 0    | Success.                                                                                                             |
+| 1    | The server refused the request or could not finish it.                                                               |
+| 2    | Usage: an unknown command or option, an argument, flag or input refused before any request, or an HSX check failure. |
+| 3    | A live action is waiting for a person to approve it.                                                                 |
+| 4    | Not signed in, or this login or key may not do that (HTTP 401 or 403).                                               |
+| 5    | The thing named does not exist (HTTP 404).                                                                           |
+| 6    | The request conflicts with the current state (HTTP 409).                                                             |
+
+`help --json` lists the same table under `exitCodes`. A mistyped command or
+option suggests the nearest one, and every refusal carries a runnable `fix`.
 
 Set `HYPERSCALE_BASE_URL` for the API origin and `HYPERSCALE_ENVIRONMENT` for
 `sandbox` or `live`. `HYPERSCALE_TOKEN` supplies a login token and
 `HYPERSCALE_API_KEY` supplies a product key. Each has a matching command flag.
+Product commands use the first one set: `--api-key`, `HYPERSCALE_API_KEY`,
+`--token`, `HYPERSCALE_TOKEN`, then the stored login. `whoami` names it.
+`agent setup <host>` gives a coding agent its own sandbox token for both MCP
+and the CLI; see https://hyperscale0.ai/auth.md.
 
 The API defaults to `https://hyperscale0.ai`, which maps to the Launch and
 Build portals. `open` refuses other API origins because they do not identify