@hyperscale0/cli 1.0.337 → 1.0.339

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 +131 -237
  2. package/hyperscale.js +177 -102
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -1,109 +1,87 @@
1
1
  # Hyperscale CLI
2
2
 
3
- The CLI is Hyperscale's `kubectl`: it uses the same operation API as portals, MCP and SDK. Read [how Hyperscale fits](https://hyperscale0.ai/docs/runtime.md#how-hyperscale-fits) for the operating system, providers and money retry rules.
4
-
5
- Build and operate financial products from your terminal. Work in HSX, manage
6
- products and keys, and run actions. Use Launch and Build for the visual editor
7
- and richer product design.
8
-
9
- Install with Node 20 or later:
10
-
11
- ```sh
12
- npm install -g @hyperscale0/cli
13
- hyperscale
14
- ```
15
-
16
- ## Sign in
3
+ Build and run payment Products from your terminal. The CLI calls the same
4
+ operations as the portals, MCP and the SDK, so anything you do here shows up
5
+ there. [How Hyperscale fits](https://hyperscale0.ai/docs/runtime.md#how-hyperscale-fits)
6
+ places it next to the rest.
17
7
 
18
8
  ```sh
9
+ npm install -g @hyperscale0/cli # Node 20 or later
19
10
  hyperscale auth login
20
- hyperscale whoami
21
11
  ```
22
12
 
23
- Approve the URL and code in your browser. The CLI saves your login on this
24
- device. Use `--no-open` to approve on another device. A pending sign-in resumes
25
- when you run the command again.
13
+ `bunx @hyperscale0/cli@latest <command>` runs it without the install.
26
14
 
27
- On a machine with no browser, sign in with your password and an emailed code:
28
- `hyperscale auth login --email you@example.com`. Without a terminal, pipe the
29
- password and finish in a second call:
15
+ ## Sign in
30
16
 
31
- ```sh
32
- printf '%s\n' "$PASSWORD" | hyperscale auth login --email you@example.com --json
33
- hyperscale auth login --code 123456 --json
34
- ```
17
+ | Situation | Command |
18
+ | -------------------- | ---------------------------------------------------------------------- |
19
+ | A browser is at hand | `hyperscale auth login`, then approve the code it shows |
20
+ | No browser | `hyperscale auth login --email you@example.com`, then the emailed code |
21
+ | No account yet | `hyperscale auth signup` |
22
+ | CI | Pipe a personal access token to `hyperscale auth login --with-token` |
23
+ | A coding agent | `hyperscale agent setup claude-code` (or `codex`, `cursor`) |
35
24
 
36
- A login ends after 30 days, or 7 days unused. `whoami` shows when.
37
- `hyperscale doctor` names where the token is stored: the macOS Keychain or a
38
- private file in the config folder. For CI, pipe a personal access token to
39
- `hyperscale auth login --with-token`, or set `HYPERSCALE_TOKEN`.
25
+ `hyperscale whoami` shows who is signed in and when the login ends: after 30
26
+ days, or 7 days unused. `hyperscale auth logout --revoke` signs out and revokes
27
+ the token. [Sign in](https://hyperscale0.ai/auth.md) covers every path,
28
+ including agents and the stdin form for scripts.
40
29
 
41
- To create an account without a browser, run `hyperscale auth signup`. It asks
42
- for your name, work email, company and a password, solves a short proof of work,
43
- and mails a six-digit code. Type the code and the CLI is signed in to the new
44
- sandbox account. An agent without a terminal passes the flags, pipes the
45
- password on stdin, and finishes with the code in a second call:
30
+ ## Start a project
46
31
 
47
32
  ```sh
48
- printf '%s\n' "$PASSWORD" | hyperscale auth signup --email you@example.com --name "Your name" --company Acme --json
49
- hyperscale auth signup --code 123456 --json
33
+ hyperscale init my-store
34
+ cd my-store
35
+ hyperscale scenario run day.json
50
36
  ```
51
37
 
52
- `hyperscale auth verify` confirms the email of an existing account the same
53
- way. The browser signup and its email link keep working.
38
+ `init` pulls the selected Product's HSX and settings into `product.hsx` and
39
+ `product.configuration.json`, writes a first scenario and links the folder in
40
+ `hyperscale.json`. Inside it every command uses that Product, and `hsx check`,
41
+ `plan` and `apply` need no file arguments. `link` links an existing `.hsx` file
42
+ instead. `--template storefront` also writes a Vite React shop.
54
43
 
55
- `hyperscale auth logout` removes the local login. Add `--revoke` to revoke the
56
- token too. Tokens and saved requests use macOS Keychain when available, with
57
- an owner-only file fallback (mode 0600). `HYPERSCALE_CREDENTIAL_STORE=file`
58
- selects file storage. `HYPERSCALE_CONFIG_DIR` or `--config-dir <path>` sets the
59
- settings folder. The token stays in the Keychain, one entry per folder, so
60
- deleting the folder does not sign out: run `hyperscale auth logout` first.
44
+ No Product yet? `hyperscale architect chat --brief "<your business>" --yes`
45
+ drafts, checks and saves one, or write HSX and run
46
+ `hyperscale product create --source product.hsx --name Desks`.
61
47
 
62
- ## Work on a product
48
+ ## Change the Product
63
49
 
64
50
  ```sh
65
- hyperscale product list
66
- hyperscale product select <id>
67
- hyperscale hsx pull product.hsx
68
- hyperscale hsx check product.hsx
69
- hyperscale pricing
70
- hyperscale hsx plan product.hsx --config settings.json --json > plan.json
71
- hyperscale hsx apply product.hsx --config settings.json --plan-file plan.json --yes
72
- hyperscale hsx watch product.hsx --plan --config settings.json
73
- hyperscale open --portal build
51
+ hyperscale hsx check
52
+ hyperscale hsx plan --json > plan.json
53
+ hyperscale hsx apply --plan-file plan.json
54
+ hyperscale hsx watch --plan
74
55
  ```
75
56
 
76
- Edit the HSX file in your editor. Watch checks each saved change. With `--plan`,
77
- it also plans after each successful check. Apply uses the saved plan and
78
- requires `--confirm` for a person or `--yes` for automation. Product settings
79
- contain `partyBindings`, a map of participant names to IDs.
57
+ `plan` shows the diff and the price; `apply` saves exactly that plan and asks
58
+ first (`--yes` skips the question). `watch` checks each save, and plans too
59
+ with `--plan`. `hyperscale pricing` shows the price list and this Product's
60
+ fees. Sandbox use is free.
80
61
 
81
- Create a new product with `product create --source product.hsx --name Savings
82
- --config settings.json`. Use `product show` for the current product, or pass
83
- an ID. `--product <id>` selects a product for one command. `pricing` shows the
84
- price list and the selected product's own monthly and activation fees; sandbox
85
- use is free.
86
-
87
- ## Develop against the sandbox
62
+ ## Run it in the sandbox
88
63
 
89
64
  ```sh
90
- hyperscale init my-store
91
- cd my-store
92
- hyperscale hsx plan
93
- hyperscale hsx apply --confirm
94
- hyperscale scenario run day.json
65
+ hyperscale customer create Noura --test
66
+ hyperscale account open <customer-id>
67
+ hyperscale fund <account-id> 5000
68
+ hyperscale object create membership --on-behalf-of <customer-id>
69
+ hyperscale object actions membership <object-id>
70
+ hyperscale object run membership <object-id> activate --on-behalf-of <customer-id>
71
+ hyperscale clock advance 1mo
72
+ hyperscale books report
95
73
  ```
96
74
 
97
- `init` pulls the Product's HSX and settings, writes a first scenario and
98
- links the directory with `hyperscale.json`. Inside a linked directory every
99
- command uses its Product and environment, and `hsx check`, `plan`, `apply` and
100
- `watch` need no file arguments: plan saves its review in `.hyperscale/` and
101
- apply reads it from there. `link` links an existing `.hsx` file instead.
102
- `--template storefront` also writes a Vite React shop whose server holds the
103
- Product key; it runs in mock mode until you add one.
75
+ - Money is in major units everywhere in the CLI: `fund <account> 5000` is SAR
76
+ 5,000.00, and output reads `"5000.00"`. Only `api call` shows raw API minor
77
+ units.
78
+ - `object run` reads the object's revision and Build itself. Add
79
+ `--attachment` or `--instance` when two agreements offer the same action.
80
+ - An action bound to a customer runs with `--on-behalf-of <customer-id>`.
81
+ - `clock advance` takes a duration or a date and runs every clock action due by
82
+ then. `clock reset` returns to wall time.
104
83
 
105
- A scenario is a JSON story that runs in the sandbox and stops at the first
106
- step that fails:
84
+ A scenario is the same story as a file. It stops at the first step that fails:
107
85
 
108
86
  ```json
109
87
  {
@@ -119,176 +97,92 @@ step that fails:
119
97
  { "run": "agree_rental", "on": "camera", "by": "maya" },
120
98
  { "advance": "4d" },
121
99
  { "fund": "maya", "amount": "50" },
122
- {
123
- "name": "Maya has her change",
124
- "expect": { "balances": { "maya": { "settled": "300.00" } } }
125
- }
100
+ { "expect": { "balances": { "maya": { "settled": "300.00" } } } }
126
101
  ]
127
102
  }
128
103
  ```
129
104
 
130
- Each customer is created, given a sandbox account and funded first. `create`
131
- makes an object, `run` runs an action on it, `fund` adds sandbox money,
132
- `advance` moves the sandbox clock (`30m`, `4h`, `2d`, `1w` or an ISO time) and
133
- `expect` checks balances. The clock is the Product's, shared by every record in
134
- it, so `scenario run` names its advances before the first step. The starter
135
- `init` writes takes one payment and never moves the clock. A plain balance compares to `available`; an object
136
- can name `available`, `settled` or `pending`. Amounts are major units, as
137
- `fund` takes them (`"750"` or `"750.50"` in SAR), in money fields and action
138
- input too; the runner sends the API minor units. Funding and actions need the
139
- Product key in `HYPERSCALE_API_KEY`. `scenario init` writes a working example for the
140
- Product.
141
-
142
- ```sh
143
- hyperscale listen --forward-to http://localhost:3000/webhooks
144
- hyperscale event resend <event-id> --forward-to http://localhost:3000/webhooks
145
- hyperscale log tail --status failed --since 1h
146
- hyperscale log explain <request-id>
147
- hyperscale doctor
148
- hyperscale docs operate
149
- hyperscale export records --type receipts --from 2026-07-01 > receipts.csv
150
- ```
151
-
152
- `listen` forwards the Product's sandbox events as Standard Webhooks
153
- deliveries: `webhook-id`, `webhook-timestamp` and `webhook-signature`, signed
154
- with the `whsec_` secret it prints. The secret stays the same for a profile,
155
- so your handler keeps verifying across restarts. `log tail` reads the developer
156
- log of your API calls with their request ids; `log explain` shows one call's
157
- inputs, error, fix and receipt with secrets redacted. `doctor` checks the CLI,
158
- config directory, API, login, token store, Product and sandbox clock and prints a fix for
159
- each failure. `export records` prints transfers, receipts or one account's
160
- statements as CSV.
105
+ | Step | Does |
106
+ | --------- | -------------------------------------------------------------------- |
107
+ | `create` | Makes an object for a customer |
108
+ | `run` | Runs an action on it |
109
+ | `fund` | Adds sandbox money to a customer |
110
+ | `advance` | Moves the Product's sandbox clock: `30m`, `4h`, `2d`, `1w` or a date |
111
+ | `expect` | Checks `available`, `settled` or `pending` balances |
161
112
 
162
- Profiles keep separate logins: `hyperscale profile use work`, then
163
- `hyperscale auth login`. `--profile <name>` or `HYPERSCALE_PROFILE` picks one
164
- for a single command, and `hyperscale.json` can name one with `profile`.
113
+ `hyperscale scenario init` writes one that fits your Product.
165
114
 
166
- ## Run actions and work with objects
167
-
168
- ```sh
169
- hyperscale action list
170
- hyperscale action show <action>
171
- hyperscale action run <action> --input-file request.json
172
- hyperscale object kinds
173
- hyperscale object list <kind>
174
- hyperscale object create <kind> --fields-file fields.json
175
- hyperscale object show <kind> <object>
176
- hyperscale object actions <kind> <object>
177
- hyperscale object run <kind> <object> <action> --fields-file fields.json --input-file request.json
178
- ```
115
+ ## Watch and debug
179
116
 
180
- Object fields are plain business data. The CLI fetches the object's current
181
- revision and the action's product settings before running it. If several
182
- agreements offer the same action, choose `--attachment` or `--instance`.
183
- Use `--on-behalf-of` to act for a customer. Mutations accept
184
- `--idempotency-key`; reuse a key only for the same request.
117
+ | Command | Shows |
118
+ | ----------------------------------------------------------- | ---------------------------------------------------------------- |
119
+ | `hyperscale listen --forward-to http://localhost:3000/hook` | Sandbox events as signed Standard Webhooks deliveries |
120
+ | `hyperscale log tail --status failed --since 1h` | Your API calls, with request ids |
121
+ | `hyperscale log explain <request-id>` | One call's input, error, fix and receipt, secrets redacted |
122
+ | `hyperscale activity list` | What changed in the company, newest first |
123
+ | `hyperscale doctor` | CLI, login, token store, API, Product and clock, with a fix each |
124
+ | `hyperscale export records --type receipts > receipts.csv` | Transfers, receipts or statements as CSV |
185
125
 
186
- ## Keys, activity and API access
126
+ ## Keys and the API
187
127
 
188
128
  ```sh
189
- hyperscale key create --name Agent
190
- hyperscale key list
191
- hyperscale key revoke <api-key-id> --yes
192
- hyperscale activity list --limit 20
193
- hyperscale activity tail --follow
194
- hyperscale api list --catalog
195
- hyperscale api call <operation> --input-file request.json --json
196
- hyperscale api resume <reference> --json
197
- hyperscale architect chat --brief "Review this product" --json
198
- hyperscale open
129
+ hyperscale key create --name Checkout
130
+ hyperscale api list transfer
131
+ hyperscale api call transfer.list --json
199
132
  ```
200
133
 
201
- `key create --name` names the key, and `key list` shows each name and expiry.
202
- A key made from a CLI login ends when that login ends; `key create` prints the
203
- date. A key made in the browser lasts 90 days.
204
-
205
- API access covers all published operations. A request that needs browser
206
- review prints a URL and a saved reference. Approve it, then use `api resume`.
207
- Approval alone does not mean the request completed.
208
-
209
- ## Every operation as a command
210
-
211
- Customers, accounts, transfers, webhooks, events, reports and the rest of the
212
- tenant API are commands too: `hyperscale customer list`,
213
- `hyperscale webhook add --url <url> --events '*'`, `hyperscale transfer show <id>`.
214
- [`command-map.js`](command-map.js) names each operation's command and writes its
215
- help by hand. [`operation-commands.js`](operation-commands.js) derives the
216
- arguments, flags, scopes and paging from the generated OpenAPI documents.
217
- Operations a founder never runs from a terminal stay reachable through
218
- `api call` and are listed with a reason by `hyperscale help --all`.
219
-
220
- Path IDs are arguments. Tenant and product IDs come from the login and the
221
- selected product. Enum flags list their values in help. Nested input comes
222
- through `--input`, `--input-file` or `--input -` for stdin, with flags merged
223
- over it. Lists fetch one page; `--limit <n>` and `--all` follow cursors.
224
- Mutations send a generated idempotency key, accept `--idempotency-key` and print
225
- the receipt ID. In a terminal, a missing required value prompts; secrets are
226
- read hidden. Without a terminal it is a usage error that names the flag.
227
-
228
- [`docs/cli.md`](../../docs/cli.md) is the full reference, generated from
229
- `hyperscale help --all --json` by `bun distribution/cli/reference.ts`. A spec
230
- fails when it drifts.
231
-
232
- ## Output and settings
233
-
234
- Every command supports `--json`. Success goes to stdout and errors go to stderr.
235
- Ordinary commands print one JSON value. `hsx watch --json` prints one event per
236
- line with type `check`, `plan` or `error`. `activity tail --json` prints one
237
- `activity` event per line. Stop watch and follow with Ctrl+C.
238
-
239
- Piped output is plain. TTY output uses the Hyperscale wordmark, blue headers,
240
- aligned fields and tables. `NO_COLOR` suppresses colour, banners and animation.
241
- `FORCE_COLOR=0` also disables colour. Truecolor terminals use brand RGB colours;
242
- other terminals use 256 or 16 colours. A non-TTY stream never receives ANSI codes.
243
-
244
- `hyperscale -v` shows the version, resolved install path, active API and
245
- environment, portal origins and saved identity, company and product on a colour
246
- TTY. It also links to [docs](https://hyperscale0.ai/docs) and the
247
- [agent guide](https://hyperscale0.ai/agents/SKILL.md). Plain output stays one
248
- version string. `--version --json` returns install and origin fields too.
249
-
250
- Interactive commands show one update notice after their output when npm has a
251
- newer CLI. A detached check caches each attempt for a day in the config directory
252
- and times out after 1.5 seconds. The next run can use its result. JSON, pipes,
253
- CI and `HYPERSCALE_NO_UPDATE_CHECK=1` suppress checks and notices. To upgrade,
254
- run `npm install -g @hyperscale0/cli@latest`.
255
-
256
- `hyperscale help --json` returns the whole command tree with flags, examples,
257
- scopes and operations; `help --all` adds the advanced operations.
258
- Use `hyperscale <group> <command> --help` for one command.
259
-
260
- | Exit | Meaning |
261
- | ---- | --------------------------------------------------------------------------------------------------------------------- |
262
- | 0 | Success. |
263
- | 1 | The server refused the request or could not finish it. |
264
- | 2 | Usage: an unknown command or option, an argument, flag or input refused before any request, or an HSX check failure. |
265
- | 3 | A live action is waiting for a person to approve it. |
266
- | 4 | Sign in: no login, or the login or key was not accepted (HTTP 401). Code `auth_required` when the CLI finds no login. |
267
- | 5 | The thing named does not exist (HTTP 404). |
268
- | 6 | The request conflicts with the current state (HTTP 409). |
269
- | 7 | Signed in, but this login, its role or the key may not do that (HTTP 403). The Code names the missing permission. |
270
-
271
- `help --json` lists the same table under `exitCodes`. A mistyped command or
272
- option suggests the nearest one, and every refusal carries a runnable `fix`.
273
-
274
- Set `HYPERSCALE_BASE_URL` for the API origin and `HYPERSCALE_ENVIRONMENT` for
275
- `sandbox` or `live`. `HYPERSCALE_TOKEN` supplies a login token and
276
- `HYPERSCALE_API_KEY` supplies a product key. Each has a matching command flag.
277
- Product commands use the first one set: `--api-key`, `HYPERSCALE_API_KEY`,
278
- `--token`, `HYPERSCALE_TOKEN`, then the stored login. `whoami` names it.
279
- `agent setup <host>` gives a coding agent its own sandbox token for both MCP
280
- and the CLI; see https://hyperscale0.ai/auth.md.
281
-
282
- The API defaults to `https://hyperscale0.ai`, which maps to the Launch and
283
- Build portals. `open` refuses other API origins because they do not identify
284
- a configured portal host. The about
285
- screen reads local profile data. Login and human `whoami` save the company name
286
- when the API supplies it; older profiles show "not saved" until then.
287
-
288
- The terminal covers HSX files and product operations. The portals own the visual
289
- editor, full product design, company administration and provider setup.
290
- Infrastructure logs have no public CLI endpoint; activity and `log tail` are the
291
- public record.
134
+ A key lasts until you revoke it; to rotate one, create the new key before you
135
+ revoke the old. A live key needs you in the browser: `hyperscale key create-live`.
136
+ Every published operation is a command, such as `hyperscale customer list` or
137
+ `hyperscale webhook add --url <url> --events '*'`. The rest run through
138
+ `api call`, and `hyperscale help --all` lists them. A request that needs browser
139
+ approval prints a link and a reference; approve it, then
140
+ `hyperscale api resume <reference>`.
141
+
142
+ ## Output
143
+
144
+ - Every command takes `--json`. Results go to stdout, errors to stderr.
145
+ `--pick items.id,items.status` prints only those fields.
146
+ - Every list takes `--limit` and `--cursor`; `--all` follows every page.
147
+ - Every refusal prints one reason and a runnable Next line, also `error.fix`
148
+ under `--json`.
149
+ - Mutations send an idempotency key and print the receipt id. Pass
150
+ `--idempotency-key` to retry the same request.
151
+ - `NO_COLOR` turns off colour; piped output is always plain.
152
+
153
+ | Exit | Means |
154
+ | ---- | ---------------------------------------------------- |
155
+ | 0 | Done |
156
+ | 1 | The server refused or could not finish |
157
+ | 2 | Usage, input or HSX check error, before any request |
158
+ | 3 | A live action waits for a person to approve it |
159
+ | 4 | Not signed in, or the login or key was refused (401) |
160
+ | 5 | Not found (404) |
161
+ | 6 | Conflicts with the current state (409) |
162
+ | 7 | Signed in, but not allowed (403) |
163
+
164
+ ## Settings
165
+
166
+ | Variable | Flag | Sets |
167
+ | ------------------------ | --------------- | --------------------------------- |
168
+ | `HYPERSCALE_API_KEY` | `--api-key` | A Product key |
169
+ | `HYPERSCALE_TOKEN` | `--token` | A login token |
170
+ | `HYPERSCALE_PROFILE` | `--profile` | A saved login, from `profile use` |
171
+ | `HYPERSCALE_ENVIRONMENT` | `--environment` | `sandbox` or `live` |
172
+ | `HYPERSCALE_BASE_URL` | `--base-url` | The API origin |
173
+ | `HYPERSCALE_CONFIG_DIR` | `--config-dir` | The settings folder |
174
+
175
+ A command uses the first credential set: `--api-key`, `HYPERSCALE_API_KEY`,
176
+ `--token`, `HYPERSCALE_TOKEN`, then the stored login. `whoami` names it. Logins live in the macOS Keychain or an owner-only file;
177
+ `hyperscale doctor` says which.
178
+
179
+ ## Reference
180
+
181
+ `hyperscale help --json` returns every command with its flags and examples, and
182
+ `hyperscale <command> --help` shows one. [`docs/cli.md`](../../docs/cli.md) is
183
+ the full reference, generated from `help --all --json`.
184
+ [`command-map.js`](command-map.js) names each operation's command;
185
+ [`operation-commands.js`](operation-commands.js) derives its flags from OpenAPI.
292
186
 
293
187
  License: Tier 2 Source Available under LicenseRef-Hyperscale-IPCL-1.0. See [LICENSE.md](LICENSE.md) and [NOTICE.md](NOTICE.md).
294
188
  Hyperscale is a trademark of Hyperscale LLC.