# Hyperscale quickstart

Install the CLI, create an account, describe a business and run a test
customer through it. Then call the same Product over HTTP, from the TypeScript
SDK and from an agent. Every client calls the same operations and reads the
same state. The CLI takes money in major units, like 300.50; the HTTP API and
MCP take minor-unit strings, like "30050".

People read the docs in the console at https://console.hyperscale0.ai/docs/.
The console runs the same loop without a terminal: describe the Product to the
Architect and save it, make a sandbox key on the Keys page under Connect, send
one request from your client and read the result on the Logs page.

## 1. Install the CLI

Node 22 or later. Without the install, `bunx @hyperscale0/cli@latest <command>`
runs the same commands.

```sh
npm i -g @hyperscale0/cli
```

## 2. Create your account

`auth signup` makes the account and its company without a browser. It asks
for a password, emails a six-digit code to the address, then asks for the
code. The code works for 15 minutes and five tries.

```sh
hyperscale auth signup --name "Maya Lindqvist" --email maya@example.com --company "Lumen"
```

A script or an agent pipes the password on stdin. A person who reads that
mailbox gives the code to a second run, which takes the same password, since
the code works only with the password that asked for it:

```sh
hyperscale auth signup --name "Maya Lindqvist" --email maya@example.com --company "Lumen" < password-file
hyperscale auth signup --email maya@example.com --code 123456 < password-file
```

Already have an account? `hyperscale auth login` signs in through the browser.
[Sign in](https://hyperscale0.ai/auth.md) covers every path.

## 3. Describe your business

Say what you sell and who pays whom. The Architect drafts and checks the
Product, and `--yes` saves and selects it. The Architect is free. The second
line keeps the Product id for step 6; it needs `jq`.

```sh
hyperscale architect chat --brief "Desks by the month: SAR 1,200, a SAR 500 deposit, SAR 50 late fee" --yes
PRD=$(hyperscale product show --json | jq -r .productId)
```

## 4. Run a test customer through it

In an empty folder, `init` writes the Product's files and day.json. The
scenario funds a new test customer with SAR 10,000.00 of sandbox money and walks
it to its first payment. Each run adds another customer.

```sh
hyperscale init
hyperscale scenario run day.json
```

## 5. Change it

Edit product.hsx, check it, save the plan, read it, then apply that plan.

```sh
hyperscale hsx check product.hsx
hyperscale hsx plan --json > plan.json
hyperscale hsx apply --plan-file plan.json --yes
```

## 6. Call the HTTP API

Make a sandbox Product key, then call any route with it. The key prints
once, so the first line keeps it.
[HTTP API](/docs/api.md) walks one customer through money with curl.

```sh
KEY=$(hyperscale key create --json | jq -r .shown_once)
curl "https://hyperscale0.ai/v1/customers?productId=$PRD" -H "Authorization: Bearer $KEY"
```

## 7. Use the TypeScript SDK

Call the Product from your app with the same key.
[TypeScript SDK](https://www.npmjs.com/package/@hyperscale0/sdk) generates your Core's types, with a quickstart for its first action.

```sh
npm i @hyperscale0/sdk
```

## 8. Connect an agent

Add the MCP server and approve it in the browser. A coding agent in a terminal
gets its own sandbox login with `hyperscale agent setup`.
[Connect an agent with MCP](/docs/mcp.md) covers every client.

```sh
claude mcp add --transport http hyperscale https://hyperscale0.ai/v1/mcp
```

## CLI exit codes

A script branches on the exit code. `hyperscale help --json` prints the same
table.

| Code | Name      | Meaning                                                                                                                                                                                                                                                                |
| ---- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0    | ok        | Success.                                                                                                                                                                                                                                                               |
| 1    | failed    | The server refused the request or could not finish it, or the command failed after it started.                                                                                                                                                                         |
| 2    | usage     | Usage: an unknown command or option, or an argument, flag or input the CLI refused before sending anything. An HSX check failure also exits 2.                                                                                                                         |
| 3    | approval  | Waiting for a person to approve the action in the browser.                                                                                                                                                                                                             |
| 4    | auth      | Sign in: no login, or the login or key was not accepted (HTTP 401). The CLI's own check prints Code auth_required.                                                                                                                                                     |
| 5    | notFound  | The thing named does not exist (HTTP 404).                                                                                                                                                                                                                             |
| 6    | conflict  | The request conflicts with the current state (HTTP 409), such as an action that already ran or an idempotency key reused with other input.                                                                                                                             |
| 7    | forbidden | Signed in, but this login, its role or the key may not do that (HTTP 403). Signing in again does not help. The Code names the missing permission, such as missing_required_scope or missing_required_permission, or live_not_enabled when the company has no live yet. |

For agents: [OpenAPI document](https://hyperscale0.ai/openapi.json) · [MCP manifest](https://hyperscale0.ai/.well-known/mcp.json) · [HTTP API guide](https://hyperscale0.ai/docs/api.md) · [MCP guide](https://hyperscale0.ai/docs/mcp.md)