@allscale/cli 0.1.0

package/README.md

@@ -0,0 +1,482 @@
+# `@allscale/cli`
+
+Command-line interface for AllScale — drives the same actions a user can take in [app.allscale.io](https://app.allscale.io). Designed for AI agents and humans alike.
+
+Sign in, issue and pay invoices, create claim links, inspect transactions, and withdraw stablecoins from your AllScale wallet — with JSON on stdout and stable exit codes, so scripts and agents can drive it without screen-scraping.
+
+## Important legal, risk, security, and privacy notice
+
+This CLI provides command-line access to supported AllScale features. Availability depends on your account, permissions, jurisdiction, applicable law, risk controls, and service version. Use of AllScale services is governed by the [Terms of Use](https://www.allscale.io/agreement), [Privacy Policy](https://www.allscale.io/policy), and applicable risk disclosures. AllScale's role and the non-custodial features of the services are described in the Terms of Use.
+
+AllScale Services are available only to eligible users in supported jurisdictions. Transactions may be delayed, rejected, suspended, returned, or require additional information to comply with applicable law, sanctions, AML/CTF requirements, fraud controls, network conditions, or service-provider requirements.
+
+Digital assets and stablecoins are not bank deposits, may not be protected by deposit insurance, and may lose value. Blockchain transactions may be irreversible. Verify the recipient, wallet address, network, token, amount, and fees before approving any transaction. AllScale does not provide investment, legal, tax, or accounting advice.
+
+Do not expose passwords, agent keys, OTPs, API secrets, Claim Link tokens, or personal data in shell history, logs, prompts, tickets, or shared files. CLI output and optional event logs may contain personal, confidential, and transaction data.
+
+### AI and automation use
+
+Commands submitted through scripts, AI agents, or other automation may create legal, financial, and irreversible consequences. Scope controls limit categories of permitted calls but do not verify an agent's authority, accuracy, business purpose, recipient, legality, or safety. You are responsible for configuring and supervising third-party agents and models. Use least-privilege scopes, short-lived credentials, idempotency controls, testing, and appropriate human review for irreversible actions.
+
+## Install
+
+```bash
+npm install -g @allscale/cli
+allscale --help
+```
+
+Requires Node.js >= 20.10.
+
+To upgrade: `npm install -g @allscale/cli@latest`. To remove: `npm uninstall -g @allscale/cli`.
+
+## Quick start
+
+```bash
+# Device-pairing login — the browser approves the CLI session. Use an existing
+# web session or sign in there with Passkey or Email; enter any Email OTP on the
+# webpage, never in this terminal flow.
+# The current CLI login flows issue a SCOPED AGENT KEY:
+# the backend checks requests against the scopes chosen on the approval screen, and the
+# key expires (re-run device-login to renew).
+# A BARE run at a terminal first says what it is about to do (register a
+# pairing session, open the browser, wait for approval) and asks to confirm;
+# declining exits 12 having created nothing. Any flag skips the prompt, as do
+# piped/--json/non-tty-CI callers and a redirected stderr. (A pty-allocating
+# harness running it BARE looks human and is prompted — pass --yes.)
+# Polling stops at the
+# pairing's expiry or after 15 minutes, whichever comes first — the CLI prints
+# that deadline before it starts waiting.
+allscale device-login                          # opens browser; sign in there if needed, then approve
+allscale device-login --yes                    # explicit "don't prompt me"
+allscale device-login --device-label my-laptop # add a label shown in the approval UI
+
+# Or, terminal-only Email OTP (headless/scripted). The OTP enters this CLI and
+# the backend mints the same scoped agent key — pass the scopes with --scopes
+# (required; there is deliberately no full-permission default).
+allscale otp-login --email me@example.com --scopes invoice:read_only                             # interactive: prompts for OTP
+allscale otp-login --email me@example.com --scopes invoice:all --otp-id <id> --otp <code>       # scripted: reuse a prior `otp-send`
+
+# Who am I signed in as?
+allscale whoami
+
+# What capabilities did this CLI session get? (chosen on the approval screen)
+allscale scope
+
+# Create a store for your business — returns its one-time API secret on stdout.
+# `payout send` requires a live store credential from Payout onboarding.
+allscale store create --name "My Shop"
+
+# List your invoices (defaults to 50 rows; --all requests one bounded response)
+allscale invoice list
+allscale invoice list --input '{"limit":50,"skip":50}'   # second page
+
+# Filter without hand-writing a query: repeat a flag to match any of its values.
+allscale invoice list --status SENT --status OVERDUE      # still owed
+allscale invoice list --payment-type USDC                 # only USDC invoices
+allscale invoice list --from 2026-07-01 --to 2026-08-01   # exactly July: --from is
+                                                          # inclusive, --to exclusive
+allscale invoice list --to-email client@example.com       # what you billed that
+                                                          # customer (email must match
+                                                          # an existing contact)
+
+# IMPORTANT: Financial commands are available only to eligible users in supported
+# jurisdictions and are subject to applicable law, sanctions/AML/CTF checks,
+# risk controls, network conditions, and service-provider requirements.
+# Transactions may be delayed, rejected, suspended, returned, or require
+# additional information.
+
+# Send a new invoice — authenticated `create_payment` mutation, no browser
+# ceremony. USDT/USDC totals must be at least 0.10. --wallet-id is OPTIONAL:
+# pin one or more receiving wallets (the backend resolves them, so an
+# invoice-scope-only key works), or omit it to auto-select your eligible
+# wallets (that read needs the wallet:read_only scope on an agent key).
+allscale invoice send --to-email client@example.com --amount 1.00
+allscale invoice send --to-email client@example.com --amount 1.00 --wallet-id <wallet-id>
+
+# Itemized invoice — `--line "<description>|<quantity>|<amount>"` carries per-line
+# qty + amount. `--amount` is optional when EVERY --line uses the 3-field form —
+# the CLI sums the lines to derive the total.
+allscale invoice send --to-email client@example.com \
+  --wallet-id <wallet-id> \
+  --line "Discovery (4h)|4|25.00" --line "Implementation (10h)|10|25.00" \
+  --memo "Q2 engagement"
+
+# Mixed — explicit --amount + display-only lines. With single-field --line,
+# `--amount` is required (no way to derive); three-field display rows round
+# their quantity × rate to cents and warn if the visible total differs.
+allscale invoice send --to-email client@example.com --amount 250 --wallet-id <wallet-id> \
+  --payment-type 2 --currency-label USDC --memo "January retainer" --due 2026-06-01 \
+  --line "Discovery (4h)" --line "Implementation (10h)"
+
+# First-time invoice to a new email? Add --auto-create-contact to create the
+# contact in one shot. Name defaults to the FULL email address (essentially
+# unique — sidesteps the per-business name-uniqueness rule).
+# Override with --contact-name for a curated display name.
+# If the contact already exists, no new contact is created. Before using this
+# option, confirm that you are authorized to provide the recipient's information
+# and send the invoice, and comply with applicable privacy, marketing, and
+# recordkeeping requirements.
+allscale invoice send --to-email newclient@example.com --amount 100 \
+  --wallet-id <wallet-id> --auto-create-contact
+allscale invoice send --to-email billing@acme.com --amount 100 \
+  --wallet-id <wallet-id> --auto-create-contact --contact-name "Acme Inc"
+
+# Send a stablecoin from your AllScale wallet to an external EVM address
+allscale wallet send --idempotency-key order-1042 \
+  --to 0xabc... --amount 0.1 --chain base --stable-coin USDC
+
+# (`wallet send --headless` skips the browser, but it signs with the user token
+# of a legacy JWT session — a credential this build's logins never mint, so it
+# cannot succeed here. Use the browser-bridge form above.)
+
+# Drop credentials
+allscale logout
+```
+
+## Commands
+
+### Auth
+| Command | Description |
+|---|---|
+| `device-login` | **Recommended for AllScale Pay Accounts.** Opens the browser; use an existing web-app session or sign in there with **Passkey or Email**. On the Email path, enter the **Email OTP on the webpage**, not in the terminal, then approve the CLI. The backend mints a **scoped agent API key** — the credential issued by the current CLI login flows. Scopes chosen on the approval screen are **checked by the backend**. Scope controls reduce access but do not prevent credential compromise, misuse within a granted scope, configuration errors, or unauthorized actions by an otherwise authenticated caller. The key expires and does not refresh (re-run `device-login` when it does; the CLI prints the expiry). A **bare** `device-login` at a terminal first prints what it is about to do and asks to confirm; declining exits **12** (`user.cancelled`) having created nothing. The prompt is bare-invocation only — any flag (including `--yes`) skips it — and never appears for `--json`, a pipe, a sidecar, ordinary non-tty CI, or a redirected stderr. Automation that allocates a pty for all three streams *and* runs the command bare is indistinguishable from a human and is prompted; pass `--yes`. Polling stops at the pairing's expiry or **15 minutes**, whichever is earlier; the CLI prints that deadline before it starts waiting. |
+| `otp-login` | **Terminal-only** Email-OTP path for headless / scripted shells. Works with **any account email** — external domains included, not just `@allscale.io` (the account must already exist — sign up in the web app first). Sends the code and reads it in the terminal (flag / env / stdin / interactive prompt), then mints the same **scoped agent API key** with the scopes passed via `--scopes` (required — there is deliberately no full-permission default). |
+| `otp-send` | Granular: send the email OTP only (login only, any account email). Returns the otp_id; pair with `otp-login --otp-id <id> --otp <code>` for scripted flows. |
+| `whoami` | Show the current authenticated identity. No network call. Agent-key sessions (the normal case) print the key-mode identity from the stored bundle: `credential: "agent_key"`, `business_id`, `user_type`, `scopes`, and the key expiry. |
+| `scope` | Show the capabilities granted to the current CLI session (chosen on the browser approval screen at `device-login`, or via `--scopes` on `otp-login`). Scopes are **checked by the backend** for each request. Scope controls reduce access but do not prevent credential compromise, misuse within a granted scope, configuration errors, or unauthorized actions by an otherwise authenticated caller; the key expiry is shown. No network call. |
+| `logout` | Drop cached session and store credentials for a profile. A bare logout requests a full plaintext + OS-keychain sweep and exits non-zero after file cleanup if the keychain cannot be inspected; `--insecure-storage` performs an explicit file-only cleanup and never probes keychain. |
+
+### Authorization model
+
+One page, no archaeology:
+
+- **The current CLI auth flows issue a scoped agent API key.** Both `device-login` (browser approval) and `otp-login` (terminal OTP, for headless/CI) mint one. There is no cookie mode and no full-permission default — every key carries an explicit scope set.
+- **Scopes** are `<category>:<tier>` strings (e.g. `invoice:read_only`, `claim_link:all`), chosen on the browser approval screen (`device-login`) or via `--scopes` (`otp-login`). Requested scopes are clipped to your account's role at mint; the granted set is echoed back and recorded locally (`allscale scope` shows it without a network call). The backend **checks** the set on each request; an out-of-scope call is expected to fail with exit 6. Scope controls limit permitted call categories but do not verify the caller's authority, purpose, accuracy, legality, or safety.
+- **Keys expire and do not refresh.** The CLI prints the expiry at login and in `scope` / `whoami`; re-run `device-login` or `otp-login` to mint a new key. Revoke keys in the AllScale web dashboard, then log in again for a fresh one — the CLI has no key-management command (see the Keys section).
+- **Some actions stay human-only by design.** Two of them are not CLI commands at all — key management lives in the dashboard (see the Keys section) and payout authorization lives in Store Settings → Payout Authorization. Headless Turnkey signing (`--headless` on either `wallet send` or `invoice pay`) is unavailable in this build at all: it needs the user token of a legacy JWT session, which neither login flow mints. The browser-bridge flows (`wallet send`, `invoice pay`) work under an agent key: the human approves in the browser — note `invoice pay` needs **two** scopes, `invoice:all` to create, report and confirm the pay intent and `wallet:read_only` to look up the payer address. Neither login flow grants `invoice:all` for you: on `device-login` the **Invoices** toggle starts at Read, so tick its write tier on the approval screen (the **Wallets** toggle that grants `wallet:read_only` *is* on by default); with `otp-login`, pass BOTH `--scopes invoice:all --scopes wallet:read_only`, because naming any scope turns every unnamed category off.
+- **Password login is not part of this CLI.** AllScale Pay Accounts are passkey-only and have no usable password; `device-login` and `otp-login` are the two ways in, and both mint a scoped agent key.
+
+### Discovery
+
+The schema-introspection commands below are opt-in (default off) — enable with `ALLSCALE_ALLOW_RAW=1`.
+
+| Command | Description |
+|---|---|
+| `operations` | List every operation in the schema (filter by `--kind`, `--grep`). |
+| `describe <op>` | Full type info for one operation: args, return type, example document. |
+
+### Ergonomic wrappers
+
+The CLI's user-facing surface matches the AllScale web app: what users call an **invoice** is internally a `Payment` in the backend GraphQL. The `invoice *` commands below wrap `payments` / `payment` / `sender_payments` / `recipient_payments` / `create_payment` / `update_payment` accordingly.
+
+**Important:** The financial commands below are available only to eligible users in supported jurisdictions. Execution may be delayed, rejected, suspended, returned, or require additional information to comply with applicable law, sanctions, AML/CTF requirements, fraud controls, network conditions, or service-provider requirements.
+
+| Command | Description |
+|---|---|
+| `invoice list` | List invoices for a business. Wraps `payments`. Defaults `--business-id` from the JWT. **Defaults to the first 50 rows** — pass `--input '{"limit":N,"skip":M}'` to paginate, or `--all` to request the backend's unpaginated result in one response. Read-only responses remain subject to the CLI's 32 MiB safety limit. Filter with `--status` / `--payment-type` (both repeatable — repeated values match any of them) and the creation-date range `--from` / `--to`. **The range is half-open: `--from` is inclusive, `--to` is exclusive**, so `--from 2026-07-01 --to 2026-08-01` is exactly July and consecutive ranges tile without double-counting a boundary row. Both accept a plain date, a naive datetime (read as UTC), or an offset datetime, and are normalized to the backend's required `YYYY-MM-DDTHH:MM:SS.ffffffZ`. `--to-email <email>` narrows to the invoices you **issued** to that contact — an invoice's contact record belongs to the business that issued it, so on this both-directions view the flag selects the issued half. The email is resolved to an existing contact first, and an email with no contact is a structured `input.invalid` error (exit 2), not an empty list. On an agent key that lookup additionally needs the `contact:read_only` scope. `--input` accepts only the documented QueryInput fields. |
+| `invoice get <id>` | Fetch one invoice by id. Wraps `payment`. |
+| `invoice sent` | Invoices where **you are the payer** — your business owes the money. Wraps `sender_payments` (the backend's `sender` is the payer). Invoices you issued with `invoice send` are **not** here; see `invoice received`. Same pagination defaults and the same `--status` / `--payment-type` / `--from` / `--to` filters as `invoice list`. **No `--to-email`**: an invoice's contact record belongs to the business that issued it, so your own contacts never appear on the invoices you owe — the flag is refused here with `input.invalid` rather than answering with a misleading empty page. |
+| `invoice received` | Invoices where **you are the payee** — the money is owed to your business. Wraps `recipient_payments` (the backend's `recipient` is the payee). **Includes everything you issued with `invoice send`.** Same pagination defaults and the same `--status` / `--payment-type` / `--from` / `--to` / `--to-email` filters as `invoice list`; this is the command `--to-email` fits exactly, since every row here is one you issued. |
+| `invoice send` | Issue an invoice by email. Resolves `--to-email` to a contact (auto-creates via `--auto-create-contact` if missing), renders the invoice HTML body locally, and submits `create_payment` through the authenticated session. USDT/USDC totals below 0.10 are rejected before contact or wallet lookup. Pass `--wallet-id` to pin receiving wallets (backend-resolved — works with an invoice-scope-only key), or omit it to auto-select from your wallets via the narrow `business_wallets` query (needs `wallet:read_only` on an agent key). **No browser ceremony** — the payer signs when paying; the inviter doesn't sign at issue. |
+| `invoice update <id>` | Update an existing invoice. Wraps `update_payment`. |
+| `invoice pay <id>` | Pay a received invoice from your AllScale wallet. Resolves the invoice's destination + amount, moves the funds via the same signing path as `wallet send` (the transfer is confirmed in the browser at `/cli`), then reports and confirms the payment. **Needs TWO scopes** — `invoice:all` to create, report and confirm the pay intent, and `wallet:read_only` for the payer-address lookup (the narrow `business_wallets` query). Neither login flow grants `invoice:all` for you: on `device-login` the Invoices toggle starts at Read, so tick its write tier on the approval screen; on `otp-login` pass BOTH `--scopes invoice:all --scopes wallet:read_only`, because naming any scope turns every unnamed category off. |
+| `transaction list` | Paginated transactions. `--scope mine\|business\|activities`. Wraps `my_transactions` / `business_transaction_records` / `activities`. Defaults to the first 50 rows; pass `--input` (mine/business) or `--limit N` (activities) to override, or `--all` to request one unpaginated response (still capped at 32 MiB by the CLI). |
+| `transaction get <id>` | Fetch one transaction by id. |
+| `wallet list` | Your noncustodial wallets and per-coin balances via the narrow `business_wallets` query. Works with an agent key holding `wallet:read_only`; the owner is derived from the authenticated identity. |
+| `wallet send` | Withdraw USDT/USDC from your AllScale wallet to an external EVM address. Registers a `withdraw_token` op with the broker, opens the browser at `/cli` for the passkey + Turnkey signing ceremony, returns `tx_hash` through the loopback listener. The browser is the only path this build offers: `--headless` exists but signs with the user token of a legacy JWT session, **which this build cannot create**, so it fails closed with exit 6 (`auth.permission_denied`). |
+
+### Claim links
+
+**Important:** The financial commands below are available only to eligible users in supported jurisdictions. Execution may be delayed, rejected, suspended, returned, or require additional information to comply with applicable law, sanctions, AML/CTF requirements, fraud controls, network conditions, or service-provider requirements.
+
+Sender-side reads (`get` / `list` / `preview`) need a CLI login and `claim_link:read_only` under an agent-key session. `claim-link create` needs `claim_link:all`: the CLI fixes the amount, stablecoin, chain, claim window, optional sender metadata, and caller-stable idempotency key before registering the `create_claim_link` broker op. The AllScale-hosted browser approval page shows that immutable intent as a read-only review, then performs creation, signing, and funding after the payer authorizes it; verify the exact AllScale origin before approval. It does not ask the payer to re-enter or edit the payment. Before opening the browser and again after any callback, cancellation, invalid receipt, or timeout, the CLI reconciles the complete intent through `claim_link_funding_by_idempotency_key`; the browser receipt is advisory. `status` and `claim` drive the public receiver-facing REST surface — no login; the bearer claim token IS the credential.
+
+| Command | Description |
+|---|---|
+| `claim-link create` | Create and fund a fixed-intent Claim Link through an AllScale-hosted browser approval flow. Verify the exact AllScale origin before approval. Requires `--idempotency-key` (1–128 trimmed characters), `--amount` (exact decimal string, 0.1–10000, at most 6 effective decimal places), `--chain`, and agent-key scope `claim_link:all`; `--stable-coin` defaults to USDT and `--expires` to 14d. `--no-browser` skips only local auto-open: the CLI still prints the `/cli` URL and waits for callback/paste. A recovered key must match every immutable field; a pre-browser mismatch exits 2 as `claim_link.intent_conflict` without opening the browser. Success is emitted only when the authoritative lookup returns the same intent, a validated AllScale claim URL, and either `LINK_SENT`, `CLAIMING`, or `CLAIMED`, or returns `EXPIRED` or `CANCELLED` with a validated non-empty funding transaction hash. A signed/broadcast/unknown, still-pending, failed-reconciliation, post-browser intent race, or `EXPIRED`/`CANCELLED` result without that funding proof exits 9 as `claim_link.funding_ambiguous`; follow its retry metadata and never substitute a new key. Only an explicit cancellation before creation plus a successful authoritative miss exits 12 as `claim_link.browser_cancelled`. |
+| `claim-link get <id>` | Fetch one of your own Claim Links by id. Wraps `claim_link`; a non-owned id is indistinguishable from an unknown one. Agent-key scope: `claim_link:read_only`. |
+| `claim-link list` | Your own Claim Links, newest first. Wraps `my_claim_links`. Defaults to the first 50 rows; `--input` paginates and `--all` requests one unpaginated response (still capped at 32 MiB by the CLI); `--status` filters. Agent-key scope: `claim_link:read_only`. |
+| `claim-link preview` | Fee breakdown for a would-be link without creating it. Wraps `claim_link_fee_preview`; mirrors create's asset validation. Agent-key scope: `claim_link:read_only`. |
+| `claim-link status` | Public receiver-facing status snapshot for a bearer claim token/URL. Canonical URLs are parsed locally; a same-origin `/s/` URL is resolved through one credential-free 302. No login — the token is the credential. |
+| `claim-link claim` | Claim a link from a raw token, canonical URL, or same-origin `/s/` short URL: Path A without AllScale account sign-in with `--to <0x address>` (no login), or `--to-wallet` into the authenticated business's AllScale wallet (cookie session). This does not make the transaction anonymous: network, request, compliance, and public blockchain data may still be processed or observable. Only the on-chain-proven `claimed` outcome exits 0; unavailable/expired links exit 12, while pending/unproven payouts exit 9 and must be reconciled before another claim. |
+
+### Store
+
+| Command | Description |
+|---|---|
+| `store create` | Create a store for the logged-in business (no store key, no browser ceremony). Wraps `create_store`. Defaults `--business-id` from the session token — the JWT `user_id` for cookie sessions, or the owner business id stored at login for agent-key sessions (re-run `device-login` if an older agent-key login has none stored); `--live` creates a live store (default is sandbox). Returns the API key and **one-time** API secret on stdout; capture it securely. This command does not enroll the store for Payout. Business must have checkout enabled; only one sandbox store is allowed per business. |
+
+### Payout
+
+**Important:** The financial commands below are available only to eligible users in supported jurisdictions. Execution may be delayed, rejected, suspended, returned, or require additional information to comply with applicable law, sanctions, AML/CTF requirements, fraud controls, network conditions, or service-provider requirements.
+
+**Authorization is set up in the dashboard, not here.** Enabling auto-payout,
+changing its limits, and turning it off all complete with a passkey in a human
+web session — a credential this CLI's logins never mint. Do those in **Store
+Settings → Payout Authorization**. The CLI reads the resulting session and
+spends from it.
+
+| Command | Description |
+|---|---|
+| `payout status` | Read the current claim-link auto-payout session, limits, remaining budget, and expiry. |
+| `payout send` | Create and synchronously fund a claim link using a live, Payout-onboarded store key. `--reference-id` is required for idempotent retry. Store HMACs go only to the standalone partner API at `https://openapi.allscale.io`, which is the default — `--payout-api-base` / `ALLSCALE_PAYOUT_API_BASE` exist to set it explicitly, not because you need to change it. |
+
+### Keys
+
+Agent API keys are managed in the **AllScale web dashboard**: Settings → Security → Sessions · Agents & Devices. It lists every credential and offers per-key revoke plus a revoke-all kill-switch. Creating a key stays where it always was — the login flows below — and rotation is revoke-then-log-in-again; there is no separate rotate control.
+
+The CLI mints a key for its own session when you log in (`device-login` / `otp-login`) and prints its scopes and expiry via `allscale scope` / `allscale whoami`. It does not provide key administration: those are control-plane actions that the current backend is designed to reject for an agent-key session, which is the credential type issued by the current CLI login flows.
+
+## Configuration
+
+- **Tokens**: stored in the OS keychain (macOS Keychain / Windows Credential Manager / libsecret) by default. On POSIX, pass `--insecure-storage` (or set `ALLSCALE_INSECURE_STORAGE=1`) to **force** a plaintext file at `~/.allscale/credentials.json` (mode 0600) instead of the keychain — it takes precedence and is intended for headless / CI / agent use where a keychain is unavailable. Plaintext credential storage is not supported on Windows in the current implementation because Node's POSIX mode APIs cannot reliably verify owner-only ACL/link safety; use Windows Credential Manager instead. Without the opt-in, the CLI is designed to return an error rather than silently downgrade when the keychain is unavailable. `ALLSCALE_NO_KEYCHAIN=1` makes the CLI treat the keychain as unavailable at runtime and is designed not to probe it.
+- **Store credentials**: `store create` returns the one-time secret on stdout and does not persist it. Historical credentials in the OS keychain or `~/.allscale/store-credentials.json` are still removed by `logout`; the current implementation does not write them to config.toml.
+- **Logout storage scope**: `allscale logout` with no insecure-storage flag or environment opt-in requests a full sweep of both plaintext credential files and the OS keychain. If keychain access is suppressed, missing, or broken, it still clears the files but exits non-zero because historical keychain credentials may remain. `allscale logout --insecure-storage` (or `ALLSCALE_INSECURE_STORAGE=1`) is designed as file-only and does not intentionally probe the keychain, to avoid GUI prompts for headless/CI agents. On Windows, an absent plaintext target is treated as a no-op; logout can remove a valid legacy file when the requested profile is its only remaining profile. A shared, malformed, or unverifiable legacy file is expected to remain unchanged and requires deliberate manual cleanup.
+- **Profile metadata**: `~/.allscale/config.toml` (mode 0600) records `api_base` and `user_type` per profile. Non-secret.
+- **Profiles pin their backend.** Logging in saves the backend it used into `~/.allscale/config.toml`, and a saved profile beats the built-in default. The CLI does **not** switch a configured endpoint automatically: stored credentials are bound to the origin used at login.
+- **Default backend**: `https://app.allscale.io` (production). Published builds are configured for their bound AllScale environment. The current implementation accepts a credential-bearing api-base only for exact AllScale origins (plus an explicit loopback origin for development), and validates session credentials against the origin recorded at login. `payout send` uses a separate approved partner API origin selected with `--payout-api-base` / `ALLSCALE_PAYOUT_API_BASE`. Embedded URL userinfo (`user:password@host`) is rejected. Browser targets must be `https://`, or `http://` to loopback only. The current implementation is designed not to follow redirects when a request carries credentials; callers should still verify the destination origin and TLS before approving or transmitting sensitive data.
+- **Sidecar event log** (opt-in, off by default): set **`ALLSCALE_OUTPUT_FILE_PATH=/path/to/run.ndjson`** to append a machine-readable NDJSON event stream for the run, or **`ALLSCALE_OUTPUT_FILE_DIRECTORY=/path/to/dir`** to give every run its own randomly named file in that directory. Events may cover the command, argv fields designed to redact specified authentication secrets, request URLs, responses, refreshes, bridge steps, and errors — intended for agent supervisors and orchestrators that need structured progress without parsing stdout. Redaction is not a guarantee that the log contains no sensitive information.
+
+  **Important:** Sidecar logs are designed to redact specified authentication secrets, but may still contain personal, business-confidential, and transaction data. Treat them as sensitive. Do not place them in shared directories or transmit them to third-party agents or support channels without review. Configure appropriate access controls, retention, and secure deletion.
+
+  On POSIX systems, the current implementation attempts to create files with mode 0600. A directory selected through `ALLSCALE_OUTPUT_FILE_DIRECTORY` is intended to be created owner-only; if it already grants group/other access, the CLI is designed to refuse writing rather than change a potentially shared directory such as `/tmp`. For an explicit `_PATH`, the current implementation does not change permissions on an existing parent directory, so choose a private parent yourself; it is designed to refuse an existing output file unless it is owner-only (rotate/remove an older loose file first). Sidecar output is currently disabled on Windows because Node's mode APIs cannot reliably enforce or verify owner-only NTFS ACLs. **It is still a file on disk that describes your session**: prefer `_DIRECTORY`, which generates an unpredictable filename, over a fixed `_PATH` on a shared machine. A `_PATH` that is a symlink is designed to be refused rather than written through. The file is append-only with no rotation and is currently capped at 64 MB, after which the sidecar is designed to disable itself for the run with a warning on stderr.
+
+## Output contract
+
+JSON to stdout by default. Stable shapes — agents can parse without quoting hacks.
+
+```bash
+$ allscale whoami
+{
+  "data": {
+    "profile": "default",
+    "api_base": "https://app.allscale.io",
+    "credential": "cookie",
+    "user_id": "...",
+    "user_email": "you@example.com",
+    "expires_at": "2026-05-07T03:35:02.000Z",
+    "expired": false,
+    "storage": "keychain"
+  }
+}
+```
+
+In an agent-key session (no JWT) the shape is key-mode instead:
+
+```bash
+$ allscale whoami
+{
+  "data": {
+    "profile": "default",
+    "api_base": "https://app.allscale.io",
+    "credential": "agent_key",
+    "business_id": "...",
+    "user_type": "business",
+    "scopes": ["invoice:all", "contact:read_only"],
+    "expires_at": "2026-05-07T03:35:02.000Z",
+    "expired": false,
+    "storage": "keychain"
+  }
+}
+```
+
+Errors go to stderr as JSON with stable codes:
+
+```bash
+$ allscale whoami
+# stderr:
+{
+  "error": {
+    "code": "auth.no_token",
+    "message": "No tokens stored for profile 'default'. Run `allscale device-login --profile <profile>` with the same profile (recommended), use `allscale otp-login --profile <profile> --email <you@example.com> --scopes <scope> --otp-stdin` for headless automation."
+  }
+}
+# exit code: 4
+```
+
+### Exit codes
+
+Stable contract — branch on these. Every error code the CLI can emit maps to
+exactly one of them, and a mapping is never renumbered once shipped.
+
+| Exit | Meaning | Error codes |
+| ---- | ------- | ----------- |
+| `0`  | success | — |
+| `1`  | generic / unexpected | `internal` |
+| `2`  | caller-actionable input or local limit — fix the invocation and re-run | `input.invalid`, `storage.unavailable`, `transport.response_too_large`, `auth.unknown_profile`, `claim_link.intent_conflict`, `signing.key_unavailable` |
+| `3`  | network / transport failure (**see the retry warning below**) | `transport.network`, `transport.timeout`, `auth.credential_changed`, `wallet.bridge_timeout` |
+| `4`  | not authenticated — run `allscale device-login` | `auth.no_token` |
+| `5`  | credential expired — re-authenticate | `auth.token_expired` |
+| `6`  | not fixable by this invocation: permission denied, or a capability gap | `auth.permission_denied`, `wallet.requires_browser_auth`, `wallet.headless_not_supported`, `wallet.headless_setup_required`, `wallet.headless_config_missing` |
+| `7`  | not found — the object you named does not exist | `not_found` |
+| `8`  | rate limited | `rate_limited` |
+| `9`  | backend internal, or an **ambiguous** mutation result | `backend.internal`, `claim.payout_ambiguous`, `claim_link.funding_ambiguous`, `wallet.bridge_invalid_response`, `wallet.headless_sign_failed` |
+| `10` | escape hatch disabled — export `ALLSCALE_ALLOW_RAW=1` | `raw.disabled` |
+| `11` | this build's request signature was rejected — **upgrade the CLI** (re-login does not help) | `auth.signature_rejected` |
+| `12` | did not complete; nothing was created | `claim.not_claimable`, `claim.expired`, `claim_link.browser_cancelled`, `user.cancelled` |
+
+> **An exit code is NOT a retry-safety signal. Branch on the `code` string when
+> you need to decide whether re-running is safe.**
+>
+> Exit `3` is the trap: `transport.network` never reached the server, but
+> `wallet.bridge_timeout` is **post-signing** — the browser may already have
+> signed and the backend may already have broadcast. Retrying blindly on exit
+> `3` can **double-pay**. Exit `9` mixes a plain 5xx with the `*_ambiguous`
+> codes and `wallet.headless_sign_failed`, all of which must be reconciled
+> against the original idempotency key rather than retried.
+
+Note that exit `6` and exit `9` each cover five distinct codes, so a branch that
+must tell them apart reads `error.code`. **Credential precedence** below states
+the same caveat for exit `2`.
+
+**Under `--json`, stderr is parseable too — for `payout send` and
+`device-login`.** On those, human progress prose is suppressed entirely and
+every stderr line is one complete JSON object: the `{error}` envelope above is
+rendered compact in that mode, and notices you may need before the stdout
+document exists arrive as structured event lines:
+
+```bash
+$ allscale payout send --json --amount 10 --chain base ...
+# stderr:
+{"version":"1","event":"payout_destination","payout_api_base":"https://..."}
+{"error":{"code":"input.invalid","message":"Missing store API key..."}}
+```
+
+Branch on `version` (currently `"1"`), ignore an `event` type you don't
+recognise, and note that a stderr JSON line is not necessarily an error —
+check for the `error` key. Event fields are designed to be scrubbed and length-bounded, so
+treat them as best-effort: an oversize record degrades to
+`{"version", "event", "output_truncated": true}`.
+
+**Treat the two commands named above as an allow-list, not a caveat: any other
+command still writes human prose to stderr, so do not read its stderr as
+NDJSON.** That includes the browser-bridge money paths (`wallet send`,
+`invoice pay`, `claim-link create`) and the ordinary read and auth commands
+(`scope`, `whoami`, `otp-send`, `otp-login`, `invoice send`, `store create`).
+Converting those is tracked separately. The `--show-doc` debug flag also prints
+a raw GraphQL document to stderr wherever it is offered; that one is
+caller-requested and stays that way, so don't combine it with a machine-parsed
+stderr. stdout stays a single JSON document on every command either way — this
+rule is about stderr only, and the compact `{error}` envelope is global.
+
+One deliberate exception to "every failure is an `{error}` document": a command
+that cannot run without input, invoked with **no arguments at all**, prints its
+help on stdout and exits 0 instead — the same as a bare topic
+(`allscale wallet`). Machine callers never take that path. A partial call still
+exits 2 with `input.invalid`, and a bare call is treated as machine mode —
+error document, exit 2 — whenever **any** of these applies:
+
+- **stdin and stdout are not both a terminal** — a pipe, `$(...)`, a CI runner,
+  an agent harness, or a terminal script with either stream redirected
+  (`allscale wallet send < /dev/null`). This is the one signal that needs no
+  opt-in, and it is how most machine callers show up.
+- `--json`
+- `ALLSCALE_CONTENT_TYPE=json`
+- a configured sidecar (`ALLSCALE_OUTPUT_FILE_PATH` / `ALLSCALE_OUTPUT_FILE_DIRECTORY`)
+
+The last three matter even at a terminal, because none of them appear in argv:
+`--json` is an argument so it never reaches a bare call, while oclif resolves
+JSON mode from its env var before it inspects argv, and the sidecar is pure
+environment.
+
+The sidecar counts because it is the audit stream a supervisor consumes: a bare
+call there must record `command-end` with `ok: false`, never a success for a
+command that did not run. **Setting the variable is what counts** — a sidecar the
+CLI *refuses* to open (Windows, a `_DIRECTORY` that is not owner-only, a stale
+`0644` file) still means a supervisor is watching, and that is the worst moment
+to change the outcome, since no stream then exists to contradict the exit code.
+
+**Known limit:** two terminals are treated as a human, and that is not a proof.
+A harness that allocates a pty for *both* streams — `expect`, a PTY-configured CI
+job — will get help and exit 0 on a bare invocation. Set any one of the three
+opt-ins above in those harnesses to restore the `{error}` / exit 2 contract.
+
+```bash
+$ allscale wallet send                                     # at a terminal: help on stdout, exit 0
+$ allscale wallet send | cat                                # piped: {"error": ...} on stderr, exit 2
+$ allscale wallet send --json                              # → {"error": {"code": "input.invalid", ...}}, exit 2
+$ ALLSCALE_CONTENT_TYPE=json allscale wallet send          # → same {"error": ...}, exit 2
+$ ALLSCALE_OUTPUT_FILE_PATH=run.ndjson allscale wallet send # → same, and the stream ends ok:false
+```
+
+## Auto-refresh
+
+Cookie-session tokens are refreshed automatically when the backend returns 401 — single-flight per process (concurrent calls share one refresh round-trip). When the refresh token itself is rejected, the CLI exits with `auth.token_expired` (code 5) and asks the user to re-login. If the profile's credential changes to an agent key while a refresh is in flight, the refresh is abandoned rather than overwriting it and the CLI exits with `auth.credential_changed` (code 3) — a valid credential exists, so the command just needs re-running, not a re-login.
+
+**Agent keys don't refresh.** A 401 in agent-key mode means the key expired or was revoked; the CLI surfaces `auth.token_expired` with a clear "re-run `allscale device-login`" message and does not attempt the refresh endpoint in the current implementation.
+
+## Upgrade-required signal
+
+Requests include a build identifier and an `x-allscale-cli-version` header. The service may use these values to enforce minimum supported versions, but they are not proof that a client build, environment, or request is uncompromised. If a release is no longer accepted, the CLI exits with **`auth.signature_rejected` (code 11)** and directs the user to install the latest version with `npm install -g @allscale/cli@latest`. If the latest version is already installed and the same code persists, contact AllScale support. When running from source or an internal build without a baked key for the selected destination, configure `ALLSCALE_SIGNING_KEY` or `ALLSCALE_BUILD_PAIRS`; if no signing key resolves for that destination, the CLI exits **2** (`signing.key_unavailable`). Do not rely on this version-enforcement mechanism as an authentication or integrity boundary.
+
+## Credential precedence
+
+Highest priority first:
+
+1. `ALLSCALE_TOKEN` env var
+2. `--profile <name>` flag → keychain entry for that profile. A name with no
+   entry in `~/.allscale/config.toml` errors with `auth.unknown_profile`
+   (exit 2) when no credential is found for it and at least one profile is
+   saved, listing the saved profiles — a typo'd profile is an input error,
+   not a login prompt. (An empty registry is a fresh machine: that stays
+   `auth.no_token`.)
+3. `ALLSCALE_PROFILE` env var → keychain entry (same `auth.unknown_profile`
+   rule as the flag).
+4. Default profile from `~/.allscale/config.toml`
+5. Otherwise → `auth.no_token` (exit 4)
+
+`auth.unknown_profile` deliberately shares exit 2 with other input errors
+(e.g. `input.invalid`, `storage.unavailable`); when an exit-2 branch needs to
+know which one fired, the `error.code` field is the load-bearing
+discriminator, not the exit number.
+
+## Capabilities
+
+- Codegen-driven `operations` / `describe` discovery commands (opt-in escape hatches).
+- Ergonomic wrappers: `invoice`, `transaction`, `claim-link`, `wallet list`.
+- Agent-key invoice creation: explicit, backend-resolved `--wallet-id`s, or automatic wallet selection via the narrow `business_wallets` query; invoice issuance itself needs no browser ceremony.
+- `device-login` (device-pairing OAuth) / `otp-login` (terminal OTP for headless shells), and `wallet send` (Turnkey-direct EVM withdraw through the `/cli` bridge).
+- Current CLI login flows issue scoped agent-key sessions: `device-login` and `otp-login` both mint an agent API key checked against its granted scopes; `scope` reports the granted set + key expiry.
+- Agent-key sessions store the owner `business_id` at login, so `--business-id` auto-fills (no JWT needed) and `whoami` prints a key-mode identity instead of erroring.
+- Store creation returns its one-time API secret through the structured stdout result.
+
+## Security
+
+Report a vulnerability by email to **security@allscale.io** — please do **not**
+open a public issue. Include the impact, a minimal reproduction (commands,
+environment, `allscale --version`), and whether it is exploitable without an
+AllScale account. We aim to acknowledge within 3 business days and to ship a fix
+or mitigation for high-severity issues within 30 days, coordinating disclosure
+with you.
+
+In scope: this package and its bundled code — the loopback browser bridge, token
+storage (keychain vs. plaintext-file fallback and its file permissions), and
+argv/URL redaction in the sidecar event log. Out of scope, and best reported to
+the AllScale platform team through the same address: the backend API and the web
+app at `https://app.allscale.io`.
+
+**Two values baked into the shipped bundle are not secrets, by design**: the
+request-signing key and the static API bearer. Both are recoverable from any
+installed copy and are build-identity markers only — they assert "this request
+came from an official AllScale client build" and are not intended as an
+authorization boundary. In the current implementation, the backend is designed
+to authorize requests using the per-user credential — a session JWT, or an agent
+key whose granted scopes it checks on each request.
+Extracting either value from the bundle is expected behavior rather than a
+finding, unless you can also show the backend making an **authorization**
+decision from one of them.
+
+Only the latest published version on npm receives security fixes; pin a recent
+version in CI.
+
+## License
+
+Proprietary — `@allscale/cli` is licensed, not sold, and is not open source.
+Your use of it, and of the AllScale services it reaches, is governed by the
+AllScale User Agreement & Terms of Service:
+
+https://www.allscale.io/agreement
+
+That agreement is the whole of the terms — this package ships no separate
+licence file, and `package.json` declares `UNLICENSED` to say there is no
+open-source grant. Runtime dependencies are installed separately by your
+package manager and keep their own licenses.

package/bin/dev.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// Dev entry — TS-aware via ts-node, no build step required.
+process.env.NODE_ENV = "development";
+
+require("ts-node/register");
+
+const oclif = require("@oclif/core");
+const { runOclif } = require("./run-oclif");
+
+oclif.settings.debug = true;
+void runOclif(oclif, { dir: __dirname });

package/bin/run-oclif.js

@@ -0,0 +1,69 @@
+"use strict";
+
+function isUnknownCommandError(oclif, error) {
+  return (
+    error instanceof oclif.Errors.CLIError &&
+    error.oclif?.exit === 2 &&
+    typeof error.message === "string" &&
+    // Deliberately NARROW: only oclif's command-RESOLUTION error, which is
+    // lowercase and period-less (`config.js`: `command ${id} not found`). The
+    // help path's capitalised variant is handled in AllscaleHelp, where its
+    // provenance is known — widening this pattern to cover both would relabel
+    // any CLIError whose text happened to end that way, and since every CLIError
+    // defaults to exit 2, nothing here could tell them apart.
+    /^command .+ not found$/s.test(error.message)
+  );
+}
+
+function emitUnknownCommandError() {
+  // Match `serializeErrorEnvelope`'s mode-dependent rendering:
+  // compact for a machine reading stderr as one JSON object per line, indented
+  // for a human. This runs before oclif resolves a command, so `jsonEnabled()`
+  // does not exist yet — read the same two signals it would from argv/env,
+  // resolved exactly as `AllscaleHelp.jsonModeRequested` does (`help.ts`), the
+  // other place that has to answer this without a Command. Keeping the two
+  // answers identical is the point: a caller must not get compact output from
+  // one path and indented from the other for the same command line.
+  const raw = process.argv.slice(2);
+  // After `--` everything is a passthrough operand, so a literal `--json`
+  // there is data, not a flag.
+  const passThrough = raw.indexOf("--");
+  const json = raw.indexOf("--json");
+  // Case-insensitive, matching oclif's own `CONTENT_TYPE` check and help.ts:
+  // a caller who exported `CONTENT_TYPE=JSON` gets machine output from every
+  // other path, and must not get an indented document from this one. The
+  // `ALLSCALE_` prefix is hard-coded because this file is plain JS and cannot
+  // import the TS helper or reach `config.scopedEnvVar`; it is safe because
+  // `oclif.bin` is pinned to "allscale" in package.json.
+  const machine =
+    (json !== -1 && (passThrough === -1 || json < passThrough)) ||
+    process.env.ALLSCALE_CONTENT_TYPE?.toLowerCase() === "json";
+  process.stderr.write(
+    `${JSON.stringify(
+      {
+        error: {
+          code: "input.invalid",
+          message: "Unknown command. Run `allscale --help` to list available commands.",
+        },
+      },
+      null,
+      machine ? undefined : 2,
+    )}\n`,
+  );
+  process.exitCode = 2;
+}
+
+async function runOclif(oclif, options = {}) {
+  try {
+    await oclif.run(process.argv.slice(2), options.dir);
+    await oclif.flush();
+  } catch (error) {
+    if (isUnknownCommandError(oclif, error)) {
+      emitUnknownCommandError();
+      return;
+    }
+    await oclif.Errors.handle(error);
+  }
+}
+
+module.exports = { runOclif };

package/bin/run.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Production entry — runs the bundled dist/.
+const oclif = require("@oclif/core");
+const { runOclif } = require("./run-oclif");
+
+void runOclif(oclif, { dir: __dirname });