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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +61 -124
  2. package/hyperscale.js +52 -50
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -1,131 +1,68 @@
1
1
  # @hyperscale0/cli
2
2
 
3
- Hyperscale™ CLI: the founder command line. It logs a founder in, discovers
4
- public Blueprints, composes Products, manages sandbox API keys, and runs one
5
- Product's frozen public actions.
3
+ The Hyperscale developer command line.
6
4
 
7
- ## Install
5
+ ## Start
8
6
 
9
- ```bash
7
+ ```sh
10
8
  npm install -g @hyperscale0/cli
11
- # or run directly with bunx / npx
12
- bunx @hyperscale0/cli --help
9
+ hyperscale auth login --base-url https://dev.hyperscale0.ai
10
+ hyperscale whoami --json
13
11
  ```
14
12
 
15
- ## Quickstart
16
-
17
- Mint a founder PAT in Hyperscale Portal at https://hyperscale0.ai/desk. Open
18
- Security, then Personal access tokens. Unapproved founders can request access at
19
- https://hyperscale0.ai/request-access.
20
-
21
- ```bash
22
- export HYPERSCALE_TOKEN="<your founder PAT>"
23
- bunx @hyperscale0/cli auth login --no-browser
24
- bunx @hyperscale0/cli whoami
25
- bunx @hyperscale0/cli start --blueprint vehicle-escrow-marketplace --json
26
- bunx @hyperscale0/cli blueprint list
27
- bunx @hyperscale0/cli product create --blueprint luxury-goods-consignment-escrow --name "Luxury Consignment"
28
- bunx @hyperscale0/cli product create --source product.hsx --name "Custom Escrow"
29
- bunx @hyperscale0/cli product select <Product id>
30
- bunx @hyperscale0/cli key create --name "Founder laptop"
31
- bunx @hyperscale0/cli compose check product.hsx
32
- bunx @hyperscale0/cli compose plan product.hsx
33
- bunx @hyperscale0/cli compose apply product.hsx --yes
34
- bunx @hyperscale0/cli activity list
35
- bunx @hyperscale0/cli ops list payment
36
-
37
- export HYPERSCALE_API_KEY="<your Product API key>"
38
- bunx @hyperscale0/cli product actions
39
- bunx @hyperscale0/cli product actions escrow_order.placeBuyerHold --json
40
- bunx @hyperscale0/cli product run escrow_order.placeBuyerHold --input '{"escrowOrderId":"eord_sandbox_..."}'
41
- bunx @hyperscale0/cli call account.list --input '{"limit":5}'
42
- ```
43
-
44
- ## Commands
45
-
46
- `product actions` lists the frozen Product surface. Pass one exact public
47
- operation id such as `escrow_order.placeBuyerHold` to return its full input
48
- schema, output schema, policies, build id, surface version, and operation-set
49
- digest.
50
- `product create` creates and selects a new Product with `--name <name>`
51
- from either `--blueprint <slug>` or `--source <file.hsx>`.
52
- `start` asks which catalog company to build in a terminal. Scripts and agents
53
- pass `--blueprint <slug>` to skip the prompt. `product select <Product id>`
54
- stores the default Product used by compose, key, and Product commands when
55
- `--product` is absent.
56
- `compose check` compiles textual HSX and runs the independent composer check.
57
- `compose plan` diffs it against the selected Product. `compose apply`
58
- recomposes that Product and requires `--confirm`, or `--yes` for an agent.
59
- Compiler or composer refusal exits 2. Transport and server failure exit 1.
60
- `npx @hyperscale0/cli` runs the same commands. Add
61
- `--json` for machine-readable success and failure output.
62
- `auth login --no-browser` skips the localhost browser callback. Without a PAT,
63
- it prints the PAT desk and request-access URL. With `--token` or
64
- `HYPERSCALE_TOKEN`, it validates and stores that founder PAT without opening a
65
- browser.
66
-
67
- Founder PAT commands are `auth`, `whoami`, `product create/list/show/select`,
68
- `compose plan/apply`, `key`, and `activity`. They use
69
- `--token`, `HYPERSCALE_TOKEN`, or a stored login in that order. Product API
70
- key commands are `product actions/run`, `ops list`, and `call`. They use
71
- `HYPERSCALE_API_KEY` and need no founder login profile. `compose check`
72
- runs locally when no founder credential exists. On a clean machine, set the
73
- Product API key and pass `--product <id>`. Use `--base-url` and
74
- `--environment` when their defaults do not name the Product's plane.
75
-
76
- Point it at another host with `--base-url`, and at the live plane with
77
- `--environment live`. Live keys and sandbox keys are never interchangeable.
78
- The CLI stores the founder PAT in macOS Keychain by default. If Keychain is
79
- unavailable, it falls back to an owner-only 0600 file under
80
- `HYPERSCALE_CONFIG_DIR`, or `~/.config/hyperscale` by default. Set
81
- `HYPERSCALE_CREDENTIAL_STORE=file` to choose that file store and skip
82
- Keychain access. `auth logout` deletes local state and does not revoke the
83
- PAT. `auth logout --revoke` revokes the active PAT before deleting local
84
- state. Passkey login stays in the portal at
85
- https://hyperscale0.ai/signin.
86
-
87
- Run `bunx @hyperscale0/cli --help` for the full option list.
88
-
89
- ## Command shapes and automation
90
-
91
- When passing `--json`, commands emit structured JSON to stdout on success.
92
- Commands that create or switch active resources (`product create`, `product select`,
93
- `product show`, `blueprint show`, `key create`, and `start`) include a
94
- `nextCommands` string array in their success envelope with recommended follow-up
95
- commands.
96
-
97
- Failures under `--json` emit a single JSON object strictly to stderr, leaving
98
- stdout empty. The stderr failure envelope contains:
99
- - `status`: the numeric HTTP status when the failure came from the API; absent otherwise
100
- - `error.code`: stable error code string
101
- - `error.message`: sanitized diagnostic message (capped at 1024 characters)
102
- - `error.fix`: actionable corrective step
103
- - `error.details`: structured error details or contextual payload
104
- - Correlation fields: `requestId`, `operationId`, `receiptId`, and `traceId` when reported by the upstream API
105
-
106
- ## Pricing and compose flags
107
-
108
- `compose apply` takes one confirmation form:
109
- - `--confirm`: confirm the mutation for a person
110
- - `--yes`: confirm the mutation without a prompt for an agent; accepts the candidate price current at apply time
111
- - `--pricing-identity <id>`: candidate pricing identity from `compose plan`; required with `--confirm` only when scheduled pricing exists
112
- - `--plan-file <path>`: saved JSON plan file from `compose plan --json`; used with `--confirm` to read the pricing identity when scheduled pricing exists
113
-
114
- ## Exit codes
115
-
116
- - `0`: Success
117
- - `1`: General failure (validation error, transport failure, server error, or unknown option)
118
- - `2`: Compiler or composer refusal (such as contract incompatibility or invalid composition)
119
-
120
- ## Reference
121
-
122
- - [Portal desk](https://hyperscale0.ai/desk)
123
- - [Developer entry point](https://hyperscale0.ai/developers)
124
- - [Documentation](https://hyperscale0.ai/docs)
125
-
126
- ## Security and license
127
-
128
- - Security: https://hyperscale0.ai/security
129
- - License: LicenseRef-Hyperscale-Proprietary
130
-
131
- Hyperscale™ is a trademark of Hyperscale LLC.
13
+ Use `bunx @hyperscale0/cli@latest` or `npx @hyperscale0/cli@latest`
14
+ without a global install. Browser login requests read-only scopes through
15
+ portal consent. Request different scopes with `auth login --scopes <scope,...>`.
16
+ The login summary shows the authority actually returned by the server.
17
+ Headless callers can use `auth login --no-browser --token <pat>`.
18
+
19
+ ## Product commands
20
+
21
+ `product select <id>` saves a Product. Member PATs use that Product's route.
22
+ `product actions` lists the selected Build's exact public action names.
23
+ `product run <instrument.action> --input-file request.json` runs one.
24
+ Product API keys still work through `HYPERSCALE_API_KEY` or `--api-key`.
25
+ The server's frozen operation set resolves aliases, never the bundled catalog.
26
+
27
+ `ops list --catalog` browses catalog command data without authentication.
28
+ `ops list` discovers operations for the active credential and Product.
29
+ `call <operation>` calls one with `--input` or `--input-file`.
30
+ `compose check/plan/apply <file.hsx>` uses the server composer.
31
+ Run `hyperscale help <command>` for options and examples.
32
+
33
+ ## Review and resume
34
+
35
+ HTTP 409 `approval_required` prints the server review URL, approval request
36
+ ID, waiting state and a local resume reference. Review happens in the browser.
37
+ Then run `hyperscale resume <reference>`. Resume replays the same origin,
38
+ environment, credential, path, body bytes and idempotency key from secure local
39
+ storage. Body and credential overrides are refused. `--yes` cannot approve
40
+ money. Approval is not evidence of execution.
41
+
42
+ A lost response does not mean failure. Keep the printed operation reference
43
+ and read its status before retrying. Resume never creates a new idempotency key.
44
+ Successful requests remove their saved credential copy. Review and uncertain
45
+ requests remain local until they complete. Logout removes the login credential;
46
+ it does not revoke separately saved pending requests. Use portal token revocation
47
+ if those requests must lose server authority.
48
+
49
+ ## Automation and storage
50
+
51
+ `--json` writes success to stdout and one error object to stderr on failure.
52
+ Errors retain HTTP status, code, message, fix, details and available correlation
53
+ IDs. Approval details include `approvalRequestId`, `reviewUrl`, `state`
54
+ and `resumeReference`. Exit 0 means success, 1 means failure or waiting for
55
+ review, and 2 means composer refusal. JSON help is also available.
56
+
57
+ Human output honors non-TTY streams, narrow terminals and NO_COLOR, including
58
+ an empty NO_COLOR value. Identifiers are never shortened.
59
+
60
+ Credentials and saved requests use macOS Keychain with an owner-only 0600 file
61
+ fallback under `HYPERSCALE_CONFIG_DIR` or `~/.config/hyperscale`.
62
+ `HYPERSCALE_CREDENTIAL_STORE=file` explicitly selects file storage.
63
+ Use `--base-url` or `HYPERSCALE_BASE_URL` for the API origin and
64
+ `--environment sandbox|live` for the environment partition.
65
+ Neither current estate connects to real bank infrastructure.
66
+
67
+ License: LicenseRef-Hyperscale-Proprietary.
68
+ Hyperscale is a trademark of Hyperscale LLC.