@hyperscale0/cli 1.0.0-beta.25 → 1.0.0-beta.27

package/README.md

@@ -1,131 +1,68 @@
 # @hyperscale0/cli
 
-Hyperscale™ CLI: the founder command line. It logs a founder in, discovers
-public Blueprints, composes Products, manages sandbox API keys, and runs one
-Product's frozen public actions.
+The Hyperscale developer command line.
 
-## Install
+## Start
 
-```bash
+```sh
 npm install -g @hyperscale0/cli
-# or run directly with bunx / npx
-bunx @hyperscale0/cli --help
+hyperscale auth login --base-url https://dev.hyperscale0.ai
+hyperscale whoami --json
 ```
 
-## Quickstart
-
-Mint a founder PAT in Hyperscale Portal at https://hyperscale0.ai/desk. Open
-Security, then Personal access tokens. Unapproved founders can request access at
-https://hyperscale0.ai/request-access.
-
-```bash
-export HYPERSCALE_TOKEN="<your founder PAT>"
-bunx @hyperscale0/cli auth login --no-browser
-bunx @hyperscale0/cli whoami
-bunx @hyperscale0/cli start --blueprint vehicle-escrow-marketplace --json
-bunx @hyperscale0/cli blueprint list
-bunx @hyperscale0/cli product create --blueprint luxury-goods-consignment-escrow --name "Luxury Consignment"
-bunx @hyperscale0/cli product create --source product.hsx --name "Custom Escrow"
-bunx @hyperscale0/cli product select <Product id>
-bunx @hyperscale0/cli key create --name "Founder laptop"
-bunx @hyperscale0/cli compose check product.hsx
-bunx @hyperscale0/cli compose plan product.hsx
-bunx @hyperscale0/cli compose apply product.hsx --yes
-bunx @hyperscale0/cli activity list
-bunx @hyperscale0/cli ops list payment
-
-export HYPERSCALE_API_KEY="<your Product API key>"
-bunx @hyperscale0/cli product actions
-bunx @hyperscale0/cli product actions escrow_order.placeBuyerHold --json
-bunx @hyperscale0/cli product run escrow_order.placeBuyerHold --input '{"escrowOrderId":"eord_sandbox_..."}'
-bunx @hyperscale0/cli call account.list --input '{"limit":5}'
-```
-
-## Commands
-
-`product actions` lists the frozen Product surface. Pass one exact public
-operation id such as `escrow_order.placeBuyerHold` to return its full input
-schema, output schema, policies, build id, surface version, and operation-set
-digest.
-`product create` creates and selects a new Product with `--name <name>`
-from either `--blueprint <slug>` or `--source <file.hsx>`.
-`start` asks which catalog company to build in a terminal. Scripts and agents
-pass `--blueprint <slug>` to skip the prompt. `product select <Product id>`
-stores the default Product used by compose, key, and Product commands when
-`--product` is absent.
-`compose check` compiles textual HSX and runs the independent composer check.
-`compose plan` diffs it against the selected Product. `compose apply`
-recomposes that Product and requires `--confirm`, or `--yes` for an agent.
-Compiler or composer refusal exits 2. Transport and server failure exit 1.
-`npx @hyperscale0/cli` runs the same commands. Add
-`--json` for machine-readable success and failure output.
-`auth login --no-browser` skips the localhost browser callback. Without a PAT,
-it prints the PAT desk and request-access URL. With `--token` or
-`HYPERSCALE_TOKEN`, it validates and stores that founder PAT without opening a
-browser.
-
-Founder PAT commands are `auth`, `whoami`, `product create/list/show/select`,
-`compose plan/apply`, `key`, and `activity`. They use
-`--token`, `HYPERSCALE_TOKEN`, or a stored login in that order. Product API
-key commands are `product actions/run`, `ops list`, and `call`. They use
-`HYPERSCALE_API_KEY` and need no founder login profile. `compose check`
-runs locally when no founder credential exists. On a clean machine, set the
-Product API key and pass `--product <id>`. Use `--base-url` and
-`--environment` when their defaults do not name the Product's plane.
-
-Point it at another host with `--base-url`, and at the live plane with
-`--environment live`. Live keys and sandbox keys are never interchangeable.
-The CLI stores the founder PAT in macOS Keychain by default. If Keychain is
-unavailable, it falls back to an owner-only 0600 file under
-`HYPERSCALE_CONFIG_DIR`, or `~/.config/hyperscale` by default. Set
-`HYPERSCALE_CREDENTIAL_STORE=file` to choose that file store and skip
-Keychain access. `auth logout` deletes local state and does not revoke the
-PAT. `auth logout --revoke` revokes the active PAT before deleting local
-state. Passkey login stays in the portal at
-https://hyperscale0.ai/signin.
-
-Run `bunx @hyperscale0/cli --help` for the full option list.
-
-## Command shapes and automation
-
-When passing `--json`, commands emit structured JSON to stdout on success.
-Commands that create or switch active resources (`product create`, `product select`,
-`product show`, `blueprint show`, `key create`, and `start`) include a
-`nextCommands` string array in their success envelope with recommended follow-up
-commands.
-
-Failures under `--json` emit a single JSON object strictly to stderr, leaving
-stdout empty. The stderr failure envelope contains:
-- `status`: the numeric HTTP status when the failure came from the API; absent otherwise
-- `error.code`: stable error code string
-- `error.message`: sanitized diagnostic message (capped at 1024 characters)
-- `error.fix`: actionable corrective step
-- `error.details`: structured error details or contextual payload
-- Correlation fields: `requestId`, `operationId`, `receiptId`, and `traceId` when reported by the upstream API
-
-## Pricing and compose flags
-
-`compose apply` takes one confirmation form:
-- `--confirm`: confirm the mutation for a person
-- `--yes`: confirm the mutation without a prompt for an agent; accepts the candidate price current at apply time
-- `--pricing-identity <id>`: candidate pricing identity from `compose plan`; required with `--confirm` only when scheduled pricing exists
-- `--plan-file <path>`: saved JSON plan file from `compose plan --json`; used with `--confirm` to read the pricing identity when scheduled pricing exists
-
-## Exit codes
-
-- `0`: Success
-- `1`: General failure (validation error, transport failure, server error, or unknown option)
-- `2`: Compiler or composer refusal (such as contract incompatibility or invalid composition)
-
-## Reference
-
-- [Portal desk](https://hyperscale0.ai/desk)
-- [Developer entry point](https://hyperscale0.ai/developers)
-- [Documentation](https://hyperscale0.ai/docs)
-
-## Security and license
-
-- Security: https://hyperscale0.ai/security
-- License: LicenseRef-Hyperscale-Proprietary
-
-Hyperscale™ is a trademark of Hyperscale LLC.
+Use `bunx @hyperscale0/cli@latest` or `npx @hyperscale0/cli@latest`
+without a global install. Browser login requests read-only scopes through
+portal consent. Request different scopes with `auth login --scopes <scope,...>`.
+The login summary shows the authority actually returned by the server.
+Headless callers can use `auth login --no-browser --token <pat>`.
+
+## Product commands
+
+`product select <id>` saves a Product. Member PATs use that Product's route.
+`product actions` lists the selected Build's exact public action names.
+`product run <instrument.action> --input-file request.json` runs one.
+Product API keys still work through `HYPERSCALE_API_KEY` or `--api-key`.
+The server's frozen operation set resolves aliases, never the bundled catalog.
+
+`ops list --catalog` browses catalog command data without authentication.
+`ops list` discovers operations for the active credential and Product.
+`call <operation>` calls one with `--input` or `--input-file`.
+`compose check/plan/apply <file.hsx>` uses the server composer.
+Run `hyperscale help <command>` for options and examples.
+
+## Review and resume
+
+HTTP 409 `approval_required` prints the server review URL, approval request
+ID, waiting state and a local resume reference. Review happens in the browser.
+Then run `hyperscale resume <reference>`. Resume replays the same origin,
+environment, credential, path, body bytes and idempotency key from secure local
+storage. Body and credential overrides are refused. `--yes` cannot approve
+money. Approval is not evidence of execution.
+
+A lost response does not mean failure. Keep the printed operation reference
+and read its status before retrying. Resume never creates a new idempotency key.
+Successful requests remove their saved credential copy. Review and uncertain
+requests remain local until they complete. Logout removes the login credential;
+it does not revoke separately saved pending requests. Use portal token revocation
+if those requests must lose server authority.
+
+## Automation and storage
+
+`--json` writes success to stdout and one error object to stderr on failure.
+Errors retain HTTP status, code, message, fix, details and available correlation
+IDs. Approval details include `approvalRequestId`, `reviewUrl`, `state`
+and `resumeReference`. Exit 0 means success, 1 means failure or waiting for
+review, and 2 means composer refusal. JSON help is also available.
+
+Human output honors non-TTY streams, narrow terminals and NO_COLOR, including
+an empty NO_COLOR value. Identifiers are never shortened.
+
+Credentials and saved requests use macOS Keychain with an owner-only 0600 file
+fallback under `HYPERSCALE_CONFIG_DIR` or `~/.config/hyperscale`.
+`HYPERSCALE_CREDENTIAL_STORE=file` explicitly selects file storage.
+Use `--base-url` or `HYPERSCALE_BASE_URL` for the API origin and
+`--environment sandbox|live` for the environment partition.
+Neither current estate connects to real bank infrastructure.
+
+License: LicenseRef-Hyperscale-Proprietary.
+Hyperscale is a trademark of Hyperscale LLC.