@hyperscale0/cli 1.0.318 → 1.0.329

package/AGENTS.md

@@ -2,29 +2,43 @@
 
 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
 ```
 
+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.
+
 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.
+Verify with `hyperscale whoami --json`. 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
 tokens last ten minutes; the CLI rotates the refresh token and keeps both in
@@ -34,12 +48,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,27 @@ 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.
+
+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
-hyperscale auth signup --email you@example.com --name "Your name" --company Acme
+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 +51,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 +65,85 @@ 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": "100000" } },
+  "steps": [
+    {
+      "create": "rental",
+      "as": "camera",
+      "by": "maya",
+      "fields": { "item": "Camera", "renter": "Maya", "price": "75000" }
+    },
+    { "run": "agree_rental", "on": "camera", "by": "maya" },
+    { "advance": "4d" },
+    { "fund": "maya", "amount": "5000" },
+    {
+      "name": "Maya has her change",
+      "expect": { "balances": { "maya": { "settled": "30000" } } }
+    }
+  ]
+}
+```
+
+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
+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, 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 +170,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
@@ -94,6 +184,29 @@ 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 +231,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 +250,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.