@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.

Install

npm install -g @hyperscale0/cli
# or run directly with bunx / npx
bunx @hyperscale0/cli --help

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.

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
• Developer entry point
• Documentation

Security and license

• Security: https://hyperscale0.ai/security
• License: LicenseRef-Hyperscale-Proprietary