@ornncompute/cli 0.2.17 → 0.2.19

package/README.md

@@ -34,6 +34,23 @@ 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
+
+```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>
+```
+
+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.
+
 ## Commands
 
 ```bash
@@ -42,12 +59,14 @@ 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>] [--operator <name>] [--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 list [--limit <1-500>] [--cursor <last-id>] [--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>
@@ -57,17 +76,18 @@ Bid create/update prefer `--node-count` and `--min-node-count`. Legacy
 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 <last-id>] [--json]
+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> [--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> [--timeout <seconds>] [--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> [--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]
@@ -83,15 +103,16 @@ 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> [--print] [--identity-file <path>] [--user <name>] [--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> [--json]
-ornn metrics history <node-id> [--start <iso>] [--end <iso>] [--max-points <n>] [--json]
-ornn metrics watch <node-id> [--interval <seconds>] [--count <n>] [--timeout <seconds>] [--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]
@@ -100,14 +121,14 @@ ornn clusters ssh-command <reservation-id> [--identity-file <path>] [--user <nam
 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> [--type kubernetes|slurm] [--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> [--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> [--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]
@@ -115,7 +136,7 @@ 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> [--json]
+ornn networks delete <network-id> [--yes] [--json]
 ornn networks reservation <reservation-id> [--json]
 ornn networks attach <reservation-id> --network <network-id> [--json]
 ornn networks detach <reservation-id> [--json]
@@ -123,8 +144,8 @@ 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> [--json]
-ornn storage volumes delete <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]
@@ -140,7 +161,7 @@ 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> [--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]
@@ -163,7 +184,7 @@ 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 [--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]
@@ -232,6 +253,21 @@ 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
@@ -271,12 +307,15 @@ path.
 
 The operator resource commands share the same reviewer auth:
 
-- `ornn operators list` lists enrolled operators.
+- `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>] [--mode bare-metal|vm] [--ip <addr>] [--host <ip>]
+[--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`.
@@ -328,9 +367,15 @@ Optional installer gateway base for `ornn tokens create` install one-liners:
 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. Use `--json` on
-read/show/list commands and transaction handoffs when you need structured
-stdout for scripts. Errors and login/browser progress go to stderr.
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ornncompute/cli",
-  "version": "0.2.17",
+  "version": "0.2.19",
   "description": "Command-line interface for Ornn compute access workflows.",
   "type": "module",
   "bin": {

package/src/api-client.mjs

@@ -2,11 +2,13 @@ import { clearAuthSession, configuredApiBaseUrl, loadAuthSession } from "./auth-
 import { resolveAuthBaseUrl } from "./device-auth.mjs";
 
 export class CliApiError extends Error {
-  constructor(message, { status, detail } = {}) {
+  constructor(message, { status, detail, genericFallback = false } = {}) {
     super(message);
     this.name = "CliApiError";
     this.status = status;
     this.detail = detail;
+    // Signals `formatCliError` to append its generic actionable trailer.
+    this.genericFallback = genericFallback;
   }
 }
 
@@ -122,14 +124,19 @@ export async function cliRequest({
       );
     }
     const message = error instanceof Error ? error.message : String(error);
-    throw new CliApiError(`Could not reach Ornn at ${baseUrl}: ${message}`);
+    throw new CliApiError(
+      `Could not reach Ornn at ${baseUrl} (${message}). Check your network connection and that ${baseUrl} is the correct Ornn API endpoint, then try again.`,
+    );
   }
 
   if (raw) {
     const text = await response.text();
     if (!response.ok) {
       await handleAuthExpiry({ env, response, hadToken: Boolean(authSession?.accessToken) });
-      throw new CliApiError(text || response.statusText, { status: response.status });
+      throw new CliApiError(text || response.statusText, {
+        status: response.status,
+        genericFallback: true,
+      });
     }
     return text;
   }
@@ -178,10 +185,20 @@ export async function raiseForFailedResponse({
   await handleAuthExpiry({ env, response, hadToken });
   const data = text ? parseJson(text, url, response) : null;
   const detail = data?.detail ?? data?.error ?? response.statusText;
-  const message = detailMessage(detail) || fallbackMessage || response.statusText;
+  const detailText = detailMessage(detail);
+  const message = detailText || fallbackMessage || response.statusText;
+  // A generic-trailer candidate for `formatCliError`: either the API
+  // actually sent a `detail`/`error` value (even if the CLI doesn't
+  // recognize its shape), or nothing usable came back at all and this call
+  // site had no hand-authored `fallbackMessage` of its own to fall back to
+  // — i.e. the rendered message is nothing but the bare HTTP status text.
+  // A call site that supplies its own `fallbackMessage` has already made
+  // that fallback self-contained and actionable; leave it alone.
+  const genericFallback = Boolean(detailText) || !fallbackMessage;
   throw new CliApiError(formatMessage(message), {
     detail: data,
     status: response.status,
+    genericFallback,
   });
 }
 
@@ -274,6 +291,7 @@ function parseJson(text, url, response) {
     const hint = isHtml ? " The Ornn host may not have this CLI endpoint deployed yet." : "";
     throw new CliApiError(`Ornn returned a non-JSON response from ${url}.${hint}`, {
       status: response?.status,
+      genericFallback: response?.ok === false,
     });
   }
 }