@ornncompute/cli 0.2.24 → 1.0.34

package/README.md

@@ -1,453 +1,378 @@
 # Ornn CLI
 
-Command-line access for Ornn compute workflows: browse Listings, buy capacity,
-bid in Exchange, manage GPU reservations, launch VM or Bare Metal machines,
-create Kubernetes or Slurm clusters, manage private networks and storage
-volumes, attach SSH keys, SSH into launched machines, watch machine health
-metrics, and view billing readouts.
+`@ornncompute/cli` installs the `ornn` command. The CLI is a catalog-backed
+client for customer compute journeys and the explicit staff namespace. It
+sends browser and CLI traffic only through the API gateway.
 
-For the end-user install, browser-login, command, and troubleshooting guide, see
-the [`docs/cli.md`](../../docs/cli.md) guide.
+For the customer install and usage guide, see [`docs/cli.md`](../../docs/cli.md).
+The shared capability catalog in `packages/capabilities` is the authority for
+command identity, role visibility, input schemas, help, and resource discovery.
+The CLI imports `@ornn/capabilities/cli`; packaging includes only that entrypoint's
+dependencies, excluding staff commerce and CRM handlers.
 
-## 0.2.24 storage compatibility update
+For GCS imports, start with the [source-bucket permissions and version-specific CLI guide](https://docs.ornn.com/cli#gcs-imports-and-storage-transfer-service).
+It documents the current CLI 1.x GCS verification limitation. Scoped
+`ornn help external-buckets connect`, `verify`, and `import` help links to the
+same guide.
 
-Version 0.2.24 restores file uploads against the current Ornn API, including
-completion and cancellation. Run `ornn update`, then use the existing command:
+## Install and sign in
+
+Node.js 20 or newer is required.
 
 ```bash
-ornn storage files upload <drive-id> ./data.json --destination datasets/data.json
+npm install -g @ornncompute/cli
+ornn login
+ornn context
+```
+
+`ornn login` uses the browser device flow. A fresh npm install defaults to
+`https://compute.ornn.com` for browser authorization and `https://api.ornn.com`
+for API requests. Use `ORNN_AUTH_BASE_URL` and `ORNN_API_BASE_URL` for explicit
+local or staging endpoints. Login links must use HTTP(S) on the configured
+authentication origin. Use `--no-browser` when the CLI must print the URL instead of opening it. Session and endpoint configuration remains
+in `~/.config/ornn`; the gateway re-derives organization and role scope from the
+bearer on every request.
+
+## Command map
+
+The three primary customer journeys are:
+
+```text
+ornn launch    # launch VM, Bare Metal, Kubernetes, or Slurm
+ornn connect   # derive SSH, kubeconfig, or Slurm-native access
+ornn check     # lifecycle, health, reachability, metrics, and logs
+```
+
+Session and platform commands are:
+
+```text
+ornn login
+ornn context
+ornn logout
+ornn status
+ornn version
+ornn update [--major]
+ornn completion <bash|fish|zsh> --format human
+ornn resources
+```
+
+Advanced customer resources are registered under one noun and one verb:
+
+```text
+capacity-offers  list | show | relist | update | delist
+reservations     list | show | invoices
+fees             show
+spot             books | book | trades | bid | orders | cancel
+schedules        list | show | buy
+offers           list | post | accept | cancel
+machines         list | show | wait | switch | reboot | reset | metrics | logs
+clusters         list | show | wait | eligible-machines | add-node | remove-node | teardown | metrics | logs
+ssh-keys         list | add | delete
+ssh-keys assignments  list | assign | sync | status
+private-networks      list | show | create | update | delete
+vpn-connections       list | configure | disconnect
+volumes          list | show | create | refresh | clear | delete
+volumes files    list | upload | download | delete
+volumes folders  delete
+volume-mounts    candidates | show | attach | wait | detach
+external-buckets list | show | connect | update-credentials | verify | import | disconnect
+filesystems      deploy | show | wait | delete
 ```
 
-Uploads update the Ornn-managed volume. Connected external source buckets are
-not modified.
+`ssh-keys list` uses backend cursors; see [pagination](../../docs/cli.md#advanced-customer-resources).
+
+Market commands call one gateway route each and print that route's JSON.
+`capacity-offers` reads Commerce listings (`/commerce/listings`) and relists a
+schedule reservation you hold, or a primary listing you own, as a secondary
+listing with an asking price, its only price: buyers buy its windows at that
+price with no acceptance. `reservations` reads Commerce
+reservations, schedule and spot alike. `spot`, `schedules`, and `offers` call
+Markets (`/v1/markets`): place 1-8 GPU spot bids (one node each), buy a
+secondary window at its asking price (`schedules buy`), post offers on a
+primary listing's schedule, and accept or cancel offers on primaries you own.
+Prices are integer micro-USD per GPU-hour (`1000000` is $1.00). Every write
+reviews its terms and needs default-no consent, or `--yes` with
+`--format json`; writes accept `--idempotency-key`. Payment methods and
+invoices are managed in the web app. Launch consumes already allocated
+capacity; internal reservation lookups remain necessary for access and
+ownership.
+
+Only admins can create primary listings or reservations through
+`ornn admin capacity-offers create` and `ornn admin reservations create`.
+They post to the role-aware `POST /commerce/listings` and
+`POST /commerce/reservations` with the admin's own session; Commerce enforces
+the admin role. Both commands retain explicit commercial-term validation and
+default-no human confirmation. A new primary listing reaches the market once
+staff attach its nodes.
+
+All staff discovery and execution starts at `ornn admin`. A fresh staff preflight
+runs before the catalog is shown. The seven roots are:
+
+```text
+ornn admin users
+ornn admin suppliers
+ornn admin facilities
+ornn admin nodes
+ornn admin enrollment-tokens
+ornn admin capacity-offers
+ornn admin reservations
+```
 
-## Install
+Every `ornn admin` command, read or mutation, requires an admin session.
+`ornn admin nodes --help` lists the authorized node commands. Node health
+returns the node detail object; metrics preserve the owner `tier` and `windows`;
+logs return `data.logs` and an opaque continuation cursor in `page.next_cursor`.
+The cursor preserves the node, stream, count, time window, and owner position;
+pass it unchanged with the same node ID. The human `Next` command includes that
+node ID. Changing filters requires a new first-page request. Legacy raw owner
+cursors require the original `--before` value and filters.
+Metrics and logs use node-scoped staff gateway routes. Exported private keys
+include the final newline required by OpenSSH, both in files and with `--print`.
+`ornn admin nodes enroll` takes optional `--filter COMPARTMENT_IDS`
+(omit to run every compartment step); the retired `--mode` flag is gone. The
+gateway, not CLI metadata, authoritatively enforces the admin role.
+Suppliers are Authorization supplier organizations: `ornn admin suppliers list`
+returns their `id` and `name`, and `--supplier UUID` on `facilities list`,
+`nodes list`, `enrollment-tokens create`, and `nodes enroll` takes that
+organization ID.
+
+Token revocation looks up the token by ID, including tokens outside the newest
+500-row list. Creation-time checks and safe retries still apply.
+
+## Catalog-generated discovery
 
 ```bash
-curl -fsSL https://compute.ornn.com/cli/install | sh
+ornn
+ornn help
+ornn help machines
+ornn machines --help
+ornn help machines reset
+ornn resources --format json
+ornn completion bash --format human > ~/.local/share/bash-completion/completions/ornn
+ornn admin
 ```
 
-The installer requires Node.js 20 or newer and npm. It installs `@ornncompute/cli`
-globally, exposes the `ornn` binary, adds the npm global bin directory to the
-user's shell profile when needed, and records the web browser handoff as
-`authBaseUrl` plus the API gateway as `apiBaseUrl` in
-`~/.config/ornn/config.json`. The
-installer prints a short Ornn Compute welcome banner and next steps; set
-`ORNN_INSTALL_BANNER=0` to skip it or `ORNN_INSTALL_ANIMATION=0` to keep it
-static.
-
-`ornn whoami`, `ornn logout`, and `ornn status` call the API gateway's
-`/v1/cli/session` and `/v1/cli/status` contracts. The gateway resolves the CLI
-bearer itself; it never trusts caller-supplied identity or authorization-admin
-headers. Logout asks the gateway to revoke the remote credential, then always
-clears the local bearer. If revocation cannot be confirmed, the CLI reports
-that the remote credential may remain active. Updated legacy installs that
-saved only a deployed web/auth
-origin map that known Ornn origin to its API gateway automatically; custom and
-localhost combined endpoints are left unchanged.
-
-## First machine
+Root help, scoped help, suggestions, and the advanced-resource index are
+rendered from the same catalog bindings used for dispatch. Customer discovery
+never contains admin children. There is no second parser or command registry.
+
+## Interaction contract
+
+An eligible human context requires TTY stdin and TTY stdout and no JSON/NDJSON
+format. Human commands may guide selection, render a normalized review, and ask
+default-no `[y/N]` consent. Empty input, EOF, and refusal submit nothing.
+
+Automation supplies complete semantic inputs and an explicit format:
 
 ```bash
-ornn login
-ornn listings forecast
-ornn buy <listing-id>
-# Complete checkout in the browser, then:
-ornn gpus list
-ornn nodes launch --interactive --wait
-ornn nodes list
-ornn ssh <machine-hostname>
+ornn status --format json
+ornn machines list --limit 100 --format ndjson
+ornn launch RESERVATION_ID --mode vm --yes \
+  --idempotency-key caller-stable-key --format json
 ```
 
-Use `ornn exchange create --interactive` instead of `ornn buy` to place a bid.
-Guided creation is explicit and TTY-only; flag-based commands remain canonical
-for scripts.
+Redirected commands require `--format human`, `--format json`, or
+`--format ndjson`. The retired `--json` alias is rejected. Machine mode never
+prompts or launches a browser. Inputs missing for a safe decision fail before
+network, browser, or process I/O.
+
+Global interaction modifiers are `--format`, `--guided`, `--yes`, `--wait`,
+`--no-wait`, `--timeout`, `--no-browser`, `--overwrite`, and
+`--idempotency-key`. Mutations that create or increase spend, erase data, tear
+down resources, or reduce access require consent. Machine retries require a
+caller-stable idempotency key and reconcile against durable owner state.
+
+Permanent deletion and teardown requests never fire without consent. Private
+networks, detached volumes, filesystem deployments, and Kubernetes or Slurm
+clusters accept `--yes` for automation or ask an eligible human for default-no
+confirmation. Clearing a volume or deleting nested content is live-terminal
+only and always asks, even when `--yes` is present.
+
+List commands use bounded `--limit` values and opaque `--cursor` values. Waits
+poll only retryable transitional states, honor the caller deadline and
+cancellation, and return the last observed state on timeout. Durable Bare Metal
+workspace flows persist local recovery pointers for `launch --resume`.
+Browser handoff is limited to login and organization authorization. Secret
+bytes are written only by an explicit export command.
+
+Human waits report throttled progress on stderr; NDJSON waits emit versioned
+progress records, and JSON stays a single terminal envelope.
+
+Eligible human output uses color when the output stream supports it.
+`NO_COLOR` (including an empty value), `FORCE_COLOR`, and the global
+`--no-color` flag are respected. JSON and NDJSON never contain ANSI escapes.
+
+Exact unique machine hostnames are accepted anywhere a machine reference is
+advertised, including JSON and NDJSON. The CLI resolves them through the
+bounded owned-machine list and sends only the canonical machine ID to the
+machine owner route. Bare `connect` discovers VM, Bare Metal,
+Kubernetes, and Slurm targets before making one safe-fact choice across the
+combined set. An unresolved target fails with
+`connect_target_not_found` before any private-network or VPN setup.
+`connect --print` renders a native direct-access command; raw
+secret `--print` rejects every explicit `--format`. Direct human `connect`
+announces the native command and explains that Ctrl-C ends only local SSH while
+the remote machine keeps running before it starts the session. Human metrics
+and logs output includes returned sample rows, not only source availability.
+
+## Machine output and exit status
+
+JSON and NDJSON use schema `ornn.cli/v1`. A terminal record contains:
+
+```json
+{
+  "schema": "ornn.cli/v1",
+  "type": "result",
+  "command": "machines show",
+  "outcome": { "class": "ready", "phase": "ready" },
+  "data": {},
+  "action": null,
+  "page": null,
+  "errors": [],
+  "resume": null
+}
+```
 
-## Commands
+NDJSON emits zero or more progress records and exactly one terminal result or
+error record. Progress is additive and contains no secret or supplier identity.
+
+| Exit | Meaning                                           |
+| ---: | ------------------------------------------------- |
+|    0 | Requested terminal goal reached                   |
+|    1 | Failed, declined, or terminal negative outcome    |
+|    2 | Usage or validation error                         |
+|    3 | Durable external action is required               |
+|    4 | Useful partial result with explicit source errors |
+|    5 | Authentication or authorization failure           |
+|    6 | Service unavailable or retryable owner failure    |
+|  124 | Deadline expired; last observed state returned    |
+|  130 | Interrupted                                       |
+
+## Migrating to vNext
+
+vNext is a clean cutover. Retired forms are never aliases: each fails before I/O
+with one replacement and <https://docs.ornn.com/cli#migrating-to-vnext>.
+
+| Retired form                                                                                    | Replacement                                                   |
+| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `ornn account`, `ornn whoami`                                                                   | `ornn context`                                                |
+| `ornn catalog search`, `gpu-types`, `availability *`, `listing *`, `listings` read leaves       | matching `ornn capacity-offers` leaf                          |
+| `ornn listings create`                                                                          | `ornn admin capacity-offers create`                           |
+| `ornn buy`                                                                                      | Use the Ornn web app.                                         |
+| `ornn bid create`, `exchange create`                                                            | Use the Ornn web app.                                         |
+| `ornn bid` or `exchange` list, show, update, withdraw                                           | Use the Ornn web app.                                         |
+| `ornn gpu` or `gpus` list, show                                                                 | Use the Ornn web app.                                         |
+| `ornn gpu` or `gpus` checkout, `reservations checkout`                                          | Use the Ornn web app.                                         |
+| `ornn nodes launch`                                                                             | `ornn launch`                                                 |
+| `ornn nodes` list, show, wait, switch, reboot, hard-reset                                       | matching `ornn machines` leaf; reset needs erase flag         |
+| `ornn ssh`, `nodes ssh-command`                                                                 | `ornn connect`                                                |
+| `ornn metrics`, `telemetry`, `logs`                                                             | `ornn check`, `machines metrics`, or `machines logs`          |
+| `ornn clusters create`, `kubernetes launch`, `slurm launch`                                     | `ornn launch --mode kubernetes` or `ornn launch --mode slurm` |
+| Kubernetes or Slurm status, credentials, SSH, teardown                                          | `ornn clusters show`, `connect`, or `clusters teardown`       |
+| `ornn network *`, `networks *`                                                                  | `ornn private-networks <verb>`                                |
+| `ornn access *`, `keys`                                                                         | exact `ornn machines` or `ornn ssh-keys` leaf printed         |
+| `ornn storage volumes *`                                                                        | `ornn volumes <verb>`                                         |
+| `ornn storage files *`                                                                          | `ornn volumes files <verb>`                                   |
+| `ornn storage buckets *`                                                                        | `ornn external-buckets <verb>`                                |
+| Storage targets, deploy, status, detach, filesystem                                             | exact `ornn volume-mounts` or `ornn filesystems` leaf printed |
+| `ornn billing`                                                                                  | Use the Ornn web app.                                         |
+| customer-root `facilities`, `tokens`, `users`, `node`, or staff `reservations *`                | exact `ornn admin ...` command printed by the error           |
+| `ornn api`, `commerce`, `orchestrator`, `cache purge`                                           | `ornn resources`; no generic replacement exists               |
+| `--json`                                                                                        | `--format json`                                               |
+| `--interactive`                                                                                 | `--guided`                                                    |
+
+Changed behavior is intentional: waits are deadline-bound, consent is semantic
+and default-no, pagination is bounded and cursor-based, machine output is always
+enveloped, and exit statuses are semantic. Old help, completion entries,
+fixtures, staff roots, and owner-route spellings are not shipped.
+
+`0.2.10` is the configured final legacy release (`legacyVersion`, dated
+`2026-09-04T00:00:00Z`). The configured vNext artifact is `@ornncompute/cli`
+at the version in `packages/config/cli-release.json` `vnextVersion`, on the
+same binary and Node 20 minimum; `minimumVersion` for legacy tombstones
+remains `1.0.0`. Publication is allowed as soon as release validation and
+approvals pass; npm `latest` selects the approved production release. The
+legacy support schedule remains anchored to `2026-10-05T00:00:00Z`, after
+the required 30-day migration-notice interval. That date does not block npm
+publication.
+
+`ornn update` stays within the installed major. Crossing into vNext requires
+`ornn update --major`. Through day 90 (ending immediately before
+`2027-01-04T00:00:00Z`), rollback is available by reinstalling the pinned final
+legacy package:
 
 ```bash
-ornn help [command]
-ornn login [--auth-base <url>] [--no-browser] [--timeout <seconds>]
-ornn update
-ornn whoami [--json]
-ornn status [--json]
-ornn listings list [--gpu-type <type>] [--facility <name>] [--json]
-ornn listings forecast [--limit <1-500>] [--cursor <opaque>] [--json]
-ornn listings show <listing-id> [--open] [--json]
-ornn listings create [--gpu-type <type>] [--node-count <n>] [--yes] [--json]
-ornn buy <listing-id> [--no-open] [--json]
-ornn exchange create <listing-id> --node-count <n> [--min-node-count <n>] --start-date <yyyy-mm-dd> --end-date <yyyy-mm-dd> --price <usd> [--no-open] [--json]
-ornn exchange create [<listing-id>] --interactive [--node-count <n>] [--min-node-count <n>] [--start-date <yyyy-mm-dd>] [--end-date <yyyy-mm-dd>] [--price <usd>] [--no-open]
-ornn exchange list [--limit <1-500>] [--cursor <cursor>] [--json]
-ornn exchange show <exchange-id> [--open] [--json]
-ornn exchange update <exchange-id> --node-count <n> --min-node-count <n> --start-date <yyyy-mm-dd> --end-date <yyyy-mm-dd> --price <usd>
-ornn exchange withdraw <exchange-id>
-
-Bid create/update prefer `--node-count` and `--min-node-count`. Legacy
-`--gpu-count` and `--min-gpu-count` remain available; they convert using the
-listing's GPUs per node before the gateway translates the request to the
-Commerce bid contract.
-
-ornn gpus list [--status <status>] [--limit <1-500>] [--cursor <cursor>] [--json]
-ornn gpus show <gpu-id> [--open] [--json]
-ornn gpus checkout <gpu-id> [--no-open] [--json]
-ornn nodes list [--json]
-ornn nodes show <node-id-or-hostname> [--json]
-ornn nodes launch <reservation-id> --key <path|id|label> [--mode bare-metal|vm] [--username <name>] [--network public|private] [--storage-load-drive-id <id>] [--storage-save-drive-id <id>] [--wait] [--json]
-ornn nodes launch [<reservation-id>] --interactive [--key <path|id|label>] [--mode bare-metal|vm] [--username <name>] [--network public|private] [--storage-load-drive-id <id>] [--storage-save-drive-id <id>] [--wait]
-ornn nodes switch <reservation-id> --network public|private --key <path|id|label> [--mode bare-metal|vm] [--username <name>] [--wait] [--json]
-ornn nodes wait <node-or-reservation-id-or-hostname> [--timeout <seconds>] [--json]
-ornn nodes reboot <node-id> [--json]
-ornn nodes hard-reset <node-id> [--json]
-ornn nodes ssh-command <node-or-reservation-id-or-hostname> [--json]
-ornn nodes keys attach <node-id> --key <path|id|label> [--json]
-ornn nodes keys list <node-id> [--json]
-ornn node health <node-id> [--json]
-ornn node diagnose <node-id> [--json]
-ornn node list [--operator <id-or-slug>] [--facility <id>] [--email <email>] [--json]
-ornn node reboot <node-id> [--json]
-ornn node hard-reset <node-id> [--json]
-ornn node off-grid <node-id> [--reason <text>] [--yes] [--json]
-ornn node on-grid <node-id> [--yes] [--json]
-ornn node exec <node-id> --command <shell> --timeout-seconds <n> [--json]
-ornn node terminate <node-id> [--reason <text>] [--force] [--yes] [--json]
-ornn node admin-key <node-id> [--generate] [--json]
-ornn reservations commerce list --tenant <email-or-id> [--listing <listing-id>] [--json]
-ornn reservations commerce create --tenant <email> --listing <listing-id> [--node-count <n>] [--node <node-id>] [--start-at <timestamp>] [--end-at <timestamp>] [--price-per-gpu-hour <rate>] [--json]
-ornn reservations deploy <node-id> --target-tenant <id> --commerce-reservation <id> [--target-user <id>] [--network public|private] [--json]
-ornn ssh <node-or-reservation-id-or-hostname> [--print] [--identity-file <path>] [--user <name>] [--json]
-ornn metrics nodes [--json]
-ornn metrics node <node-id-or-hostname> [--json]
-ornn metrics history <node-id-or-hostname> [--start <iso>] [--end <iso>] [--max-points <n>] [--json]
-ornn metrics watch <node-id-or-hostname> [--interval <seconds>] [--count <n>] [--timeout <seconds>] [--json]
-ornn clusters list [--json]
-ornn clusters reservations [--json]
-ornn clusters eligible-nodes <reservation-id> [--type kubernetes|slurm] [--network public|private] [--json]
-ornn clusters create <reservation-id> --type kubernetes|slurm [--network public|private] [--node <node-id>] [--node-count <n>] [--wait] [--json]
-ornn clusters create [<reservation-id>] --interactive [--type kubernetes|slurm] [--network public|private] [--node <node-id>] [--node-count <n>] [--wait]
-ornn clusters show <reservation-id> [--type kubernetes|slurm] [--json]
-ornn clusters wait <reservation-id> [--type kubernetes|slurm] [--timeout <seconds>] [--json]
-ornn clusters credentials <reservation-id> [--type kubernetes|slurm] [--json]
-ornn clusters kubeconfig <reservation-id> [--output <path>] [--json]
-ornn clusters ssh-command <reservation-id> [--identity-file <path>] [--user <name>] [--json]
-ornn clusters ssh <reservation-id> [--print] [--identity-file <path>] [--user <name>] [--json]
-ornn clusters add-node <reservation-id> --node <node-id> [--json]
-ornn clusters remove-node <reservation-id> --node <node-id> [--json]
-ornn clusters teardown <reservation-id> [--yes] [--type kubernetes|slurm] [--json]
-ornn slurm launch <reservation-id> [--network public|private] [--node <node-id>] [--node-count <n>] [--wait] [--wait-timeout <seconds>] [--json]
-ornn slurm teardown <reservation-id> [--yes] [--json]
-ornn slurm status <reservation-id> [--json]
-ornn slurm credentials <reservation-id> [--json]
-ornn slurm ssh <reservation-id> [--print] [--identity-file <path>] [--user <name>] [--json]
-ornn kubernetes launch <reservation-id> [--network public|private] [--node <node-id>] [--node-count <n>] [--wait] [--wait-timeout <seconds>] [--json]
-ornn kubernetes teardown <reservation-id> [--yes] [--json]
-ornn kubernetes status <reservation-id> [--json]
-ornn kubernetes credentials <reservation-id> [--json]
-ornn kubernetes kubeconfig <reservation-id> [--output <path>] [--json]
-ornn networks list [--json]
-ornn networks show <network-id> [--json]
-ornn networks create --name <name> [--cidr <cidr>] [--description <text>] [--json]
-ornn networks update <network-id> [--name <name>] [--description <text>] [--clear-description] [--json]
-ornn networks delete <network-id> [--yes] [--json]
-ornn storage volumes list [--json]
-ornn storage volumes show <drive-id> [--json]
-ornn storage volumes create --name <name> [--source <drive-id>] [--json]
-ornn storage volumes refresh <drive-id> [--json]
-ornn storage volumes clear <drive-id> [--yes] [--json]
-ornn storage volumes delete <drive-id> [--yes] [--json]
-ornn storage files ls <drive-id> [--prefix <path>] [--json]
-ornn storage files upload <drive-id> <local-file> [--destination <path>] [--content-type <type>] [--json]
-ornn storage files download <drive-id> <remote-path> [--output <path>] [--json]
-ornn storage targets [--json]
-ornn storage deploy <drive-id> --reservation <reservation-id> [--all-nodes] [--read-only|--read-write] [--json]
-ornn storage status --reservation <reservation-id> [--watch] [--interval <seconds>] [--timeout <seconds>] [--json]
-ornn storage detach --reservation <reservation-id> [--json]
-ornn storage buckets list [--json]
-ornn storage buckets show <drive-id> [--json]
-ornn storage buckets connect gcs|s3|r2 --bucket <bucket>|--url <url> [--name <name>] [--prefix <prefix>] [--region <region>] [--account-id <id>|--endpoint-url <url>] [--access-key-id <id> --secret-access-key-file <path>] [--read-only|--read-write] [--verify] [--json]
-ornn storage buckets update-credentials <drive-id> --access-key-id <id> --secret-access-key-file <path> [--json]
-ornn storage buckets verify <drive-id> [--json]
-ornn storage buckets disconnect <drive-id> [--json]
-ornn storage filesystem deploy --reservation <reservation-id> [--performance-tier <tier>] [--capacity-gib <gib>] [--json]
-ornn storage filesystem status --reservation <reservation-id> [--json]
-ornn storage filesystem delete --reservation <reservation-id> [--yes] [--json]
-ornn telemetry latest <node-id> [--span 15m] [--start <iso>] [--end <iso>] [--max-points <n>] [--json]
-ornn telemetry tail <node-id> [--duration <seconds>] [--json]
-ornn logs latest <node-id> [--stream kernel] [--count <n>] [--before <iso>] [--cursor <token>] [--json]
-ornn logs tail <node-id> [--stream kernel] [--duration <seconds>] [--json]
-ornn users query [--name <name>] [--email <email>] [--organization <name>] [--max <n>]
-ornn keys list [--json]
-ornn keys add [<public-key-file>] --label <label> [--public-key <key>] [--json]
-ornn keys delete <key-id> [--json]
-ornn access show <reservation-id> [--json]
-ornn access activate <reservation-id> --key <path|id|label> [--mode bare-metal|vm] [--username <name>] [--network public|private] [--storage-load-drive-id <id>] [--storage-save-drive-id <id>] [--wait] [--no-open] [--json]
-ornn access switch <reservation-id> --network public|private --key <path|id|label> [--mode bare-metal|vm] [--username <name>] [--wait] [--json]
-ornn access push-keys <reservation-id> --ssh-key-id <id> [--json]
-ornn access keys list <reservation-id> [--json]
-ornn access keys add <reservation-id> --public-key <key> --label <label> [--json]
-ornn access keys add <reservation-id> --public-key-file <path> --label <label> [--json]
-ornn access keys push <reservation-id> --ssh-key-id <id> [--json]
-ornn access keys status <reservation-id> [--json]
-ornn ssh-keys list [--json]
-ornn ssh-keys add --public-key <key> --label <label> [--json]
-ornn ssh-keys add --public-key-file <path> --label <label> [--json]
-ornn ssh-keys delete <key-id> [--json]
-ornn billing summary [--json]
-ornn billing invoices [--limit <1-500>] [--cursor <opaque>] [--json]
-ornn billing showback --start <yyyy-mm-dd> --end <yyyy-mm-dd> [--json]
-ornn billing open [--no-open] [--json]
-ornn api <get|post|patch|put|delete> <allowlisted-path> [--data <json>] [--raw]
-ornn logout
+npm install -g @ornncompute/cli@0.2.10
 ```
 
-`ornn access keys add` is safe before or after launch. When the reservation has
-active VM or Bare Metal machines, adding the key automatically queues the
-current user's complete reservation key set on those machines. Use
-`ornn access keys push` to explicitly re-sync keys that are already attached.
-
-`ornn storage status` prints reconciled object and byte progress once the
-managed transfer has reported progress, plus the number of target nodes that
-have acknowledged the mount. Internal placement bucket details are not shown.
-AWS S3 and external GCS sources use the managed transfer path. Cloudflare R2
-buckets can be connected and verified, but deployment support is coming soon.
-The mount path is always `/home/tenant/volume`; node agents resolve `tenant` to the
-machine's real Linux user at mount time.
-
-`ornn storage status --watch` polls the same status endpoint on an interval
-(10 seconds by default) instead of returning after a single check, re-printing
-the human summary on each poll. It exits 0 once the attachment is attached and
-every scoped node has mounted, exits 1 with an error on stderr if the
-attachment detaches before that happens, and exits 1 with a timeout message on
-stderr after 1800 seconds (or the value passed to `--timeout`) without
-success. Use `--interval <seconds>` to change the poll cadence. `--interval`
-and `--timeout` require `--watch`. Combined with `--json`, only a single JSON
-payload is printed, at the end, instead of a stream of per-poll output.
-
-`ornn storage detach` detaches the drive from the reservation's storage
-attachment. Detach is origin-aware: if your reservation individually joined a
-drive that another reservation already had attached, detach releases only
-your reservation's own mount and leaves the rest of the attachment alone. If
-your reservation started the attachment, or it is the last member still
-joined, detach flushes and unmounts every node before releasing the whole
-attachment. A node that fails to unmount is left in a retryable state with
-the reported error; run `ornn storage detach` again with the same
-`--reservation` to retry it. A reservation that detached from a shared drive
-can rejoin it later by running `ornn storage deploy` again. Mounted state is
-tracked per node, not by attachment membership, so `ornn storage status`
-can show one node as unmounted while the rest of the attachment
-stays mounted.
-
-`ornn storage files upload` adds a file to the drive's current colocated copy.
-You can upload while a direct FUSE mount is active; every mounted node sees the
-file on its next lookup without a remount. A direct FUSE drive attaches to one
-reservation by default; pass `--all-nodes` on `ornn storage deploy` to fan the
-same mount out across every compatible node in the node group. Avoid writing
-the same file path concurrently from multiple nodes because object storage is
-not a POSIX shared filesystem.
-
-`ornn storage files download` streams a single object from the drive straight
-to disk. Pass `--output <path>` to control where it's written; without it, the
-file is saved under the remote path's basename in the current directory.
-
-For a connected bucket, deploy once before uploading. The first deploy imports
-the source into an Ornn-managed colocated working copy. That copy remains the
-drive's durable data when you unmount, detach, or mount it elsewhere. Ornn
-does not write changes back to the original connected bucket.
-
-UI aliases are first-class in the CLI: `listings` maps to the older
-`availability` command, `exchange` maps to `bid`, `gpus` maps to
-`reservations`. The older command names remain available for scripts.
-Bid and reservation list commands return a bounded page (500 rows by default);
-use `--limit`, `--json`, and the response's opaque `next_cursor` to traverse
-older history. Replay that cursor exactly; it is not an item ID. `show` and `checkout`
-use exact tenant-owned item lookups, so they are not limited to the current page.
-
-`listings forecast` is a Commerce-owned view of the next 48 one-hour
-availability windows. It includes capacity that is unavailable now but frees
-up during the horizon. The CLI makes one gateway request; it does not probe
-each hour independently.
-
-`exchange create`, `nodes launch`, and `clusters create` accept
-`--interactive`. Supplied flags prefill the guided answers. The mode requires
-TTY stdin and stdout, rejects `--json`, prints the complete request, and
-submits only after an explicit default-no confirmation.
-
-Machine UUIDs remain canonical. `ornn ssh`, `nodes show`, `nodes wait`, and
-tenant metrics also accept a case-insensitive exact hostname when it uniquely
-matches one active machine; ambiguous hostnames fail and print the matching
-full IDs.
-
-## Operator commands
-
-The `ornn node` commands are for Ornn operators and reviewers, not tenants. They
-wrap internal-reviewer-gated endpoints. Run `ornn login` as an
-internal-allowed staff user. The CLI calls `/v1/cli/operator/*`; the gateway
-resolves the user bearer and applies staff authorization without downloading a
-review or service secret to the laptop. There is no direct-service break-glass
-path.
-
-- `ornn node health <node-id>` shows launch readiness (ready/blocked plus
-  reasons), passive fault reasons, and the last validation status.
-- `ornn node diagnose <node-id>` queues a manual node validation test.
-- `ornn node list [--operator <id-or-slug>] [--facility <id>] [--email <email>]` lists GPU nodes.
-  Orchestrator applies facility id and an operator UUID. Non-UUID `--operator`
-  slugs and `--email` are forwarded today and do not filter the fleet.
-- `ornn node reboot <node-id>` queues an OS reboot of the node's resolved
-  instance (its host for bare-metal, its VM for a virtual-machine instance id;
-  storage and SSH keys preserved).
-- `ornn node hard-reset <node-id>` wipes tenant storage/users and reboots, then
-  re-pushes the tenant's keys on reconnect. The tenant keeps ownership of the
-  instance.
-- `ornn node off-grid <node-id> [--reason <text>] [--yes]` takes a node off-grid
-  (remove Ornn agent management, leave the host powered on). Asks y/N unless `--yes`.
-- `ornn node on-grid <node-id> [--yes]` re-enrolls an off-grid host: orchestrator
-  SSHs with the stored admin key and re-runs the installer. Asks y/N unless `--yes`.
-- `ornn node exec <node-id> --command <shell> --timeout-seconds <n>` runs
-  one unrestricted command over orchestrator SSH with the stored admin key. Not
-  an interactive shell (`ornn ssh`). Runs immediately; no y/N.
-- `ornn node terminate <node-id> [--reason <text>] [--force] [--yes]` best-effort
-  cleans the host, removes the Ornn agent, and hard-deletes the node record.
-  It does not return the host to a tenant. Asks y/N unless `--yes`. There is no
-  `deenroll` verb; use terminate.
-- `ornn node admin-key <node-id> [--generate]` prints the Ornn admin SSH keypair
-  for the node (including the private key) so an operator can SSH into the host.
-  `--generate` always mints a new pair, stores it, and installs the public key
-  on the live host. Treat the output as a secret.
-
-The operator resource commands share the same reviewer auth:
-
-- `ornn operator list [--json]` lists operators from the capabilities
-  catalog (staff). Distinct from `ornn operators list`.
-- `ornn operators list` lists enrolled provisioning operators
-  (`GET /provisioning/operators`).
-- `ornn facilities list [--operator <id-or-slug>]` lists facilities, optionally
-  filtered to one operator.
-- `ornn tokens list` lists enrollment tokens.
-- `ornn tokens create --operator <id> [--facility <id>]
-[--expires-in <seconds>] [--ip <addr>] [--host <ip>]
-[--identity-file <path>] [--yes]` mints an enrollment token and prints a
-  `curl … | sudo bash` install command. With `--host` and `--identity-file`,
-  orchestrator SSHs and runs that curl (same as Bulk Enroll). Asks y/N unless `--yes`.
-- `ornn tokens revoke <token-id>` revokes an enrollment token.
-
-Staff Commerce reservations are listing-backed, not fleet-backed:
-
-- `reservations commerce create --tenant <email> --listing <listing-id>
-[--node-count <n>] [--node <node-id>]` creates and activates the tenant's
-  Commerce reservation. Node count defaults to the listing capacity; start,
-  end, and hourly rate default from the listing. Optional `--node` values pin
-  specific catalog ids. Start and end overrides must remain inside the
-  listing's allowed window; the hourly rate can also be overridden explicitly.
-- `reservations commerce list --tenant <email-or-id> [--listing <listing-id>]`
-  lists active reservations in their live window, optionally filtered to one
-  listing.
-
-Reservation lifecycle verbs also run under the operator surface:
-
-- `ornn reservations commerce create|list` creates or discovers a validated
-  Commerce reservation from a listing. These actions require a staff
-  `ornn login` session; the gateway `/v1/cli/operator/*` allowlist enforces
-  staff authorization — there is no review-secret break-glass that bypasses
-  that gate.
-- `ornn reservations transfer <reservation-id> --target-tenant <id>
-[--target-user <id>] [--node <id>] [--strategy reject|park] [--confirm]`
-  transfers a reservation to another tenant.
-- `ornn reservations deploy <node-id> --target-tenant <id>
---commerce-reservation <id> [--target-user <id>] [--network public|private]`
-  deploys one node only after the gateway operator contract verifies that the
-  live tenant-owned Commerce reservation and listing match that node.
-
-The tenant `ornn reservations list|show|checkout` verbs use the tenant CLI
-login and `/v1/cli/compute` gateway contract. Staff Commerce actions use the
-gateway operator contract; `transfer|deploy` retain the operator path above.
-
-Staff happy path:
-
-- `ORNN_AUTH_BASE_URL` — web/browser handoff origin
-- `ORNN_API_BASE_URL` — API gateway origin
-- `ornn login` as a user allowed by `INTERNAL_ALLOWED_*` on that environment
-
-Optional installer gateway base for `ornn tokens create` install one-liners:
-
-- `ORNN_INSTALLER_URL` - base serving `enrollment/install` (for deployed
-  gateways, `https://<gateway>/v1/orchestrator`), falling back to
-  `NEXT_PUBLIC_INSTALLER_URL`. Unset prints the token without an install command.
-
-Without a staff login session, operator commands fail with a clear error before
-making a network request.
-
-Commands print concise human-readable output by default. Customer list
-commands use aligned tables when stdout is a TTY and retain their existing
-line-oriented shape when piped or redirected. Use `--json` on
-read/show/list commands and transaction handoffs for the supported structured
-stdout contract. JSON never contains tables, progress, next-step hints, color,
-or ANSI sequences. Errors and login/browser progress go to stderr. Under
-`--json` an error is written to stderr as one object, `{"error": "<message>",
-"status": <http-status>}` (`status` only when the API supplied one); stdout
-stays empty and the exit code is unchanged.
-
-`ornn login` opens a browser to the Ornn auth origin, lets the user sign in
-with the normal web account flow, and then completes automatically in the
-terminal once the browser session approves the CLI device request. If the CLI
-cannot open a browser, copy the printed URL into any browser and sign in there;
-the terminal keeps polling until the login is approved or expires.
-
-Run `ornn --help` for the full command list and `ornn api` for the
-allowlisted gateway API escape hatch.
-
-WireGuard client configs use the current tenant-scoped `/nodes` routes:
+Both directions reuse valid `auth.json`, `config.json`, and
+`update-check.json`. `selectedOrganizationId` is an untrusted hint; the gateway
+revalidates membership. Neither direction rewrites credentials or configured
+endpoints. Rollback is unsupported from day 91. From day 91 through day 180,
+legacy compatibility calls return a non-forwarding `426 Upgrade Required`
+tombstone with `cli_version_unsupported`, minimum version `1.0.0`, and the
+migration URL. The legacy route surface is absent from day 181
+(`2027-04-04T00:00:00Z`).
+
+`ornn --version` and `ornn -v` print the semantic package version. `ornn
+version` also reports machine schema and update channel.
+
+## Development
+
+The exported `run(argv, io)` seam accepts injected streams, fetch, browser,
+process, clock, sleep, and cancellation dependencies. The packaged binary uses
+the same seam. Capability code preserves existing MCP and Slack identities;
+only canonical `cli.vnext` bindings are dispatchable by the CLI.
+
+### Packaged journey and release evidence
+
+The permanent package gate vendors the capability catalog, creates one npm
+archive, installs that exact archive under a clean temporary prefix, and tests
+only its installed `ornn` entrypoint against a deterministic loopback gateway:
 
 ```bash
-ornn api get /nodes/reservations/<reservation-id>/vpn/peers --raw
-ornn api post /nodes/reservations/<reservation-id>/vpn/peers \
-  --data '{"public_key":"<wireguard-public-key>","label":"Laptop"}' --raw
-ornn api delete /nodes/reservations/<reservation-id>/vpn/peers/<peer-id> --raw
+rm -rf /tmp/ornn-vnext-artifacts
+mkdir -p /tmp/ornn-vnext-artifacts
+npm run acceptance:packaged --workspace @ornncompute/cli -- \
+  --artifact-dir /tmp/ornn-vnext-artifacts \
+  --evidence /tmp/ornn-vnext-packaged-gate.json
 ```
 
-The legacy `/standalone-vms/*` prefix is not exposed through the gateway
-`/v1/cli/*` allowlist.
-Deleting a peer is the supported way to replace its key; switching a node
-between Public and Private VPN preserves the peer.
-
-## Updating
-
-Interactive global installations check for new releases in the background,
-using a daily interval. When a newer release has been discovered, Ornn
-installs it before your next eligible command and then runs that command
-with the updated CLI. The first check has a one-day grace period.
-
-Automatic updates are skipped in CI, with redirected input or output,
-for machine-readable output, and for help or version commands. Project
-dependencies, development checkouts, and package-runner invocations do
-not update automatically. Run `ornn update` to check and update immediately.
-
-If an installation fails, Ornn continues only when it can verify that
-the remaining CLI loads successfully. Otherwise it prints reinstall
-instructions. If another update is running, retry after it finishes.
-
-Updates publish an initialized `update-install-*.lock` directory in the Ornn
-config directory. Its unique owner file prevents competing processes from
-removing a replacement lock during recovery or release. Directory locks from
-processes that exit before installation are reclaimed on the next update
-attempt; live or inaccessible PIDs and malformed metadata remain locked. Legacy regular-file locks require
-manual cleanup after confirming that no updater is running: deleting them
-automatically could remove a live lock created by an older CLI. PID reuse can
-also require manual cleanup. An installation marker keeps the lock held if the
-CLI is killed during installation, because its package installer may still be
-running. Confirm that installer has stopped before removing the lock. Repeated
-Ctrl+C or SIGTERM releases the lock after installer teardown. An interrupted
-package installation may still require reinstalling the CLI if the package
-manager has already removed the previous version.
-
-On POSIX, SIGHUP and SIGQUIT are forwarded to the package installer so it can
-exit before the update lock is released.
-
-## Deployment
-
-`deploy-cli-pipeline.yml` publishes `@ornncompute/cli` from `main`. Staging
-publishes the package.json version to the npm `next` dist-tag; production then
-promotes that same version to `latest`. Manual rolls use
-`deploy-cli-service.yml`. Runtime changes under `apps/cli` or
-`packages/capabilities` must bump `apps/cli/package.json` so npm receives a
-new release. Re-running the pipeline is idempotent when that version is
-already published.
+The real gateway smoke and unassisted participant pass are separate release
+evidence; the deterministic fixture must never be presented as either one.
+The participant recorder installs the retained archive itself and owns the
+interactive shell used for the journey, with that installation first in
+`PATH`; it does not attest a session run in another terminal.
+Production and shared staging are refused by the smoke runner. See
+[`docs/packaged-vnext-release-gate.md`](docs/packaged-vnext-release-gate.md) for
+the non-production inputs, redacted evidence schemas, participant checklist,
+pass criteria, and exact commands.
+
+Private networks and VPN peers belong to the selected organization. There is no
+per-reservation network attachment step. Durable Bare Metal workspaces use
+`--network shared --volume <volume-id> --mount-access read-only|read-write`;
+private Kubernetes and Slurm launches continue to use `--network private`.
+
+### Storage list pages
+
+Ornn CLI 1.0.22 and later request storage lists one page at a time.
+`ornn volumes list` and `ornn external-buckets list` accept `--limit 1` through
+`--limit 100` (default 25), ordered by last updated. Pass the returned
+`page.next_cursor` to `--cursor` for the next page; null means the end.
+Refresh from the first page after changes. Older CLI versions receive an
+upgrade error for storage lists. File-list pagination is unchanged.
+
+### Reliable retries and discovery
+
+CLI 1.0.28 forwards staff facility/node `--cursor` and `--limit` to the owner
+and preserves filters in the printed next-page command. A repeated owner cursor
+fails explicitly. Volume mount discovery uses the authenticated
+`/v1/orchestrator/storage-targets` route.
+
+File uploads include a SHA-256 request fingerprint. Reusing `--idempotency-key`
+with the same volume, path, bytes, and content type reuses the upload; a completed
+replay returns its original upload ID without sending bytes again. A changed
+request conflicts, and an expired incomplete request requires a new key.
+`ornn volumes refresh <volume>` reconciles recorded usage against stored files.
+The upload replay contract requires the matching gateway/orchestrator release;
+see [the service contract](../../services/orchestrator/README.md#file-upload-replay-and-usage).