@hyperscale0/cli 1.0.328 → 1.0.330

package/AGENTS.md

@@ -2,31 +2,53 @@
 
 Hyperscale is the operating system for financial products: providers are the hardware and ADL adapters are the drivers. The CLI is its `kubectl`, a client of the same operation API as portals, MCP and SDK; read [how Hyperscale fits](https://hyperscale0.ai/docs/runtime.md#how-hyperscale-fits).
 
-Use `hyperscale help --json` for the complete tree, flags and examples.
+Use `hyperscale help --json` for the complete tree: usage, flags, examples,
+scopes and the operation behind each command. `help --all --json` adds the
+operations that have no command; call those with `api call`.
 Use `hyperscale <group> <command> --help --json` for one command.
 
 ```text
-auth       login, signup, logout
+auth       login, signup, verify, logout
 whoami     verify login and show the selected product
 product    create, list, show, select
 hsx        pull, check, plan, apply, watch
-key        create, list, revoke
+pricing    price list and the selected product's fees
+key        create, list, show, revoke, rotate
 action     list, show, run
 object     kinds, list, show, create, actions, run
-activity   list, tail
+activity   list, show, tail
 architect  chat
+agent      setup
 api        list, call, resume
 open       Launch or Build product page
 help       command tree
 ```
 
-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`. Signup uses `auth signup --email <email>
---name <name> --company <company>`. Do not print or persist credentials in
-project files.
+The other groups (customer, account, transfer, webhook, event, report and the
+rest) map one command to one tenant operation. Path IDs are arguments; tenant
+and product IDs come from the login and the selected product. Lists accept
+`--limit <n>`, `--cursor <c>` or `--all`. Mutations send an idempotency key;
+pass `--idempotency-key` to retry safely. Without a TTY a missing required flag
+exits 2 and names the flag.
 
-Browser login creates a named agent member with its own CLI grant. Access
+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.
+
+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
@@ -34,12 +56,18 @@ 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.
+
 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 HSX check or plan cannot proceed,
-3 live action waiting for human approval.
+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.
 
 `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

@@ -22,16 +22,41 @@ hyperscale whoami
 
 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. To create an account:
+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
-hyperscale auth signup --email you@example.com --name "Your name" --company Acme
+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
+sandbox account. An agent without a terminal passes the flags, pipes the
+password on stdin, and finishes with the code in a second call:
+
+```sh
+printf '%s\n' "$PASSWORD" | hyperscale auth signup --email you@example.com --name "Your name" --company Acme --json
+hyperscale auth signup --code 123456 --json
+```
+
+`hyperscale auth verify` confirms the email of an existing account the same
+way. The browser signup and its email link keep working.
+
 `hyperscale auth logout` removes the local login. Add `--revoke` to revoke the
 token too. Tokens and saved requests use macOS Keychain when available, with
 an owner-only file fallback (mode 0600). `HYPERSCALE_CREDENTIAL_STORE=file`
-selects file storage. `HYPERSCALE_CONFIG_DIR` sets its directory.
+selects file storage. `HYPERSCALE_CONFIG_DIR` or `--config-dir <path>` sets its
+directory.
 
 ## Work on a product
 
@@ -40,6 +65,7 @@ hyperscale product list
 hyperscale product select <id>
 hyperscale hsx pull product.hsx
 hyperscale hsx check product.hsx
+hyperscale pricing
 hyperscale hsx plan product.hsx --config settings.json --json > plan.json
 hyperscale hsx apply product.hsx --config settings.json --plan-file plan.json --yes
 hyperscale hsx watch product.hsx --plan --config settings.json
@@ -53,7 +79,86 @@ contain `partyBindings`, a map of participant names to IDs.
 
 Create a new product with `product create --source product.hsx --name Savings
 --config settings.json`. Use `product show` for the current product, or pass
-an ID. `--product <id>` selects a product for one command.
+an ID. `--product <id>` selects a product for one command. `pricing` shows the
+price list and the selected product's own monthly and activation fees; sandbox
+use is free.
+
+## Develop against the sandbox
+
+```sh
+hyperscale init my-store
+cd my-store
+hyperscale hsx plan
+hyperscale hsx apply --confirm
+hyperscale scenario run day.json
+```
+
+`init` pulls the Product's HSX and settings, writes a first scenario and
+links the directory with `hyperscale.json`. Inside a linked directory every
+command uses its Product and environment, and `hsx check`, `plan`, `apply` and
+`watch` need no file arguments: plan saves its review in `.hyperscale/` and
+apply reads it from there. `link` links an existing `.hsx` file instead.
+`--template storefront` also writes a Vite React shop whose server holds the
+Product key; it runs in mock mode until you add one.
+
+A scenario is a JSON story that runs in the sandbox and stops at the first
+step that fails:
+
+```json
+{
+  "scenario": "A first rental",
+  "customers": { "maya": { "name": "Maya Brooks", "fund": "1000" } },
+  "steps": [
+    {
+      "create": "rental",
+      "as": "camera",
+      "by": "maya",
+      "fields": { "item": "Camera", "renter": "Maya", "price": "750" }
+    },
+    { "run": "agree_rental", "on": "camera", "by": "maya" },
+    { "advance": "4d" },
+    { "fund": "maya", "amount": "50" },
+    {
+      "name": "Maya has her change",
+      "expect": { "balances": { "maya": { "settled": "300.00" } } }
+    }
+  ]
+}
+```
+
+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 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
+hyperscale listen --forward-to http://localhost:3000/webhooks
+hyperscale event resend <event-id> --forward-to http://localhost:3000/webhooks
+hyperscale log tail --status failed --since 1h
+hyperscale log explain <request-id>
+hyperscale doctor
+hyperscale docs operate
+hyperscale export records --type receipts --from 2026-07-01 > receipts.csv
+```
+
+`listen` forwards the Product's sandbox events as Standard Webhooks
+deliveries: `webhook-id`, `webhook-timestamp` and `webhook-signature`, signed
+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, 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.
+
+Profiles keep separate logins: `hyperscale profile use work`, then
+`hyperscale auth login`. `--profile <name>` or `HYPERSCALE_PROFILE` picks one
+for a single command, and `hyperscale.json` can name one with `profile`.
 
 ## Run actions and work with objects
 
@@ -80,8 +185,8 @@ Use `--on-behalf-of` to act for a customer. Mutations accept
 ```sh
 hyperscale key create --name Agent
 hyperscale key list
-hyperscale key revoke <id>
-hyperscale activity list
+hyperscale key revoke <api-key-id>
+hyperscale activity list --limit 20
 hyperscale activity tail --follow
 hyperscale api list --catalog
 hyperscale api call <operation> --input-file request.json --json
@@ -90,10 +195,37 @@ 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.
 
+## Every operation as a command
+
+Customers, accounts, transfers, webhooks, events, reports and the rest of the
+tenant API are commands too: `hyperscale customer list`,
+`hyperscale webhook add --url <url> --events '*'`, `hyperscale transfer show <id>`.
+[`command-map.js`](command-map.js) names each operation's command and writes its
+help by hand. [`operation-commands.js`](operation-commands.js) derives the
+arguments, flags, scopes and paging from the generated OpenAPI documents.
+Operations a founder never runs from a terminal stay reachable through
+`api call` and are listed with a reason by `hyperscale help --all`.
+
+Path IDs are arguments. Tenant and product IDs come from the login and the
+selected product. Enum flags list their values in help. Nested input comes
+through `--input`, `--input-file` or `--input -` for stdin, with flags merged
+over it. Lists fetch one page; `--limit <n>` and `--all` follow cursors.
+Mutations send a generated idempotency key, accept `--idempotency-key` and print
+the receipt ID. In a terminal, a missing required value prompts; secrets are
+read hidden. Without a terminal it is a usage error that names the flag.
+
+[`docs/cli.md`](../../docs/cli.md) is the full reference, generated from
+`hyperscale help --all --json` by `bun distribution/cli/reference.ts`. A spec
+fails when it drifts.
+
 ## Output and settings
 
 Every command supports `--json`. Success goes to stdout and errors go to stderr.
@@ -118,9 +250,12 @@ and times out after 1.5 seconds. The next run can use its result. JSON, pipes,
 CI and `HYPERSCALE_NO_UPDATE_CHECK=1` suppress checks and notices. To upgrade,
 run `npm install -g @hyperscale0/cli@latest`.
 
-`hyperscale help --json` returns the whole command tree with flags and examples.
+`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 and 2 for an HSX check or plan that cannot proceed.
+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.
 
 Set `HYPERSCALE_BASE_URL` for the API origin and `HYPERSCALE_ENVIRONMENT` for
 `sandbox` or `live`. `HYPERSCALE_TOKEN` supplies a login token and
@@ -134,7 +269,8 @@ when the API supplies it; older profiles show "not saved" until then.
 
 The terminal covers HSX files and product operations. The portals own the visual
 editor, full product design, company administration and provider setup.
-Infrastructure logs have no public CLI endpoint; activity is the public record.
+Infrastructure logs have no public CLI endpoint; activity and `log tail` are the
+public record.
 
 License: Tier 2 Source Available under LicenseRef-Hyperscale-IPCL-1.0. See [LICENSE.md](LICENSE.md) and [NOTICE.md](NOTICE.md).
 Hyperscale is a trademark of Hyperscale LLC.