@thermai/flightdeck-cli 0.1.0-pilot.2 → 0.1.0-pilot.3

package/README.md

@@ -9,23 +9,34 @@ service; downloading the CLI does not create an account or grant compute credit.
 
 The package is `@thermai/flightdeck-cli`. The first pilot, `0.1.0-pilot.1`, was
 published manually on 5 September 2026 and its anonymous install was verified.
-This revision prepares `0.1.0-pilot.2` to qualify GitHub Actions trusted
-publishing; it is not published merely by merging the version change. The
-installation command below targets that candidate once its release completes.
+`0.1.0-pilot.2` subsequently passed GitHub Actions trusted publishing and an
+anonymous install check on the same date. Releases publish through the
+versioned GitHub Release workflow, not merely by merging a version change. The
+installation command below follows the published `next` channel without
+tracking an unpublished candidate version.
 Proprietary terms in `LICENSE` permit redistribution of unchanged official
 releases. Internal service qualification is still in progress; package
 availability does not open partner onboarding.
 
+This checkout prepares **`0.1.0-pilot.3`**, including complete log pagination and
+concise authentication errors. Until its GitHub prerelease is published and
+verified, `next` still installs `0.1.0-pilot.2`; merging this candidate is not
+publication. Use the operator-approved exact version for a recorded rehearsal.
+
 ## Installation and login
 
 Requires Node.js 22 and npm. Use a user-owned Node installation or npm prefix;
 the CLI does not require administrator/root privileges.
 
+<!-- flightdeck-cli-install:start -->
+
 ```sh
-npm install -g @thermai/flightdeck-cli@0.1.0-pilot.2
+npm install -g @thermai/flightdeck-cli@next
 flightdeck login
 ```
 
+<!-- flightdeck-cli-install:end -->
+
 Login prints a URL and verification code. Open that URL, sign into
 `https://portal.thermai.uk`, and approve the named CLI credential and requested
 scopes. The CLI waits for approval; no API key needs to be copied manually.
@@ -44,6 +55,53 @@ permissions. Never share that file or include it in a workload bundle. Use
 `flightdeck logout` to revoke the credential and remove the local login. Portal
 credential management can revoke an individual workstation as well.
 
+`--name` labels a credential, not a local account profile. There is one saved
+login per OS user. If already logged in, use `whoami` to inspect it; `login`
+refuses to replace it. Do not revoke an operator's working credential merely to
+try a second account: use a separate OS user for the internal member rehearsal.
+
+## Pilot quick-start
+
+Before live use, your ThermAI operator must provision your organization/account,
+provide a single-use portal invitation, and approve your policy and credit.
+Activate through the portal, then follow the installation/login commands above.
+Confirm the expected account with `whoami` and the available credit with
+`balance`. The internal proving run comes before partner invitations.
+
+For a **local-only** readiness check, save the following as `readiness.sbatch`
+in a new empty directory. Run the dry run from that directory; no account,
+upload, API request, or paid resource is needed:
+
+<!-- flightdeck-cli-readiness-script:start -->
+
+```bash
+#!/bin/bash
+#SBATCH --array=1-2
+#SBATCH --gres=gpu:A10:1
+#SBATCH --time=00:01:00
+#SBATCH --output=%A_%a.out
+echo smoke
+```
+
+<!-- flightdeck-cli-readiness-script:end -->
+
+```sh
+flightdeck --version
+flightdeck sbatch readiness.sbatch --dry-run
+```
+
+Expect A10 x1, 60 seconds and **two flights would be submitted**, with no
+warnings. Keep `--dry-run`: this is a translation exercise, not the approved
+pilot workload or permission to launch it. A dry run does not check provider
+capacity, account policy/credit, bundle contents, image access or GPU execution.
+
+For the real workload, obtain the reviewed private bundle, exact runner-image
+digest, provider selection and runtime from the operator. Review its dry run,
+then use the supplied submission command only after execution approval. Do not
+copy internal test data into public packages or partner bundles. Use explicit
+`--files` selections from a clean directory; the submission default includes
+the current directory. Never include credentials or private workstation files.
+
 ## Workload commands
 
 After internal qualification and explicit policy/credit approval:
@@ -62,6 +120,65 @@ Submission, including `flightdeck slurm-test`, can provision paid resources.
 supports a subset of single-node Slurm directives, not an arbitrary HPC cluster.
 Workload images must satisfy the Flightdeck runner contract.
 
+An array prints a separate Flightdeck ID for each accepted task. Record them
+all: inspect, download and cancel each flight individually. Partial submission
+can leave accepted flights running even if the command exits unsuccessfully;
+do not blindly resubmit the whole array. Choose a fresh download directory for
+each flight: downloads use filename basenames and refuse to overwrite existing
+files. Check terminal status and exit code as well as the expected artifacts;
+successful submission or download alone does not mean the workload succeeded.
+
+For an incident, stop submitting, cancel the known active flights, and contact
+your named ThermAI operator. Logging out does **not** stop jobs. The operator
+must confirm provider teardown and reconcile any outstanding charges before a
+retry. Support contact, supported hours and credit increases come from your
+agreed pilot handoff; this client does not promise unattended support.
+
+### Slurm differences
+
+- Single-node jobs only; this is not a full Slurm scheduler or an HPC login node.
+- Array `%N` concurrency throttles are not enforced: tasks are submitted
+  immediately. Admission ceilings may reject excess tasks rather than queue
+  them for later admission. Review every warning before real submission.
+- Use explicit `%A_%a` output names for arrays, and write results under
+  `$OUTPUTS_DIR`. There is no shared university filesystem or implicit `module`,
+  Singularity, nested Docker, or cluster software environment.
+- Hardware, runtime, image and credit must fit the operator-approved policy.
+  A compatible runner image is required, not just any CUDA image.
+
+### Reading logs completely
+
+In `0.1.0-pilot.3` (the candidate containing the #99 pagination fix), `flightdeck logs`
+drains all pages in the current stored-log snapshot, then returns. For a running
+job it may append one current live tail after the stored pages. `--follow`
+drains those pages immediately, then polls every two seconds until the job is
+terminal and its stored backlog is exhausted. Every new invocation starts at
+the beginning; stdout/stderr retain their respective output streams.
+
+**Rollout order:** deploy and verify the pagination-capable backend before
+releasing/upgrading this CLI. A backend without the `has_more` response field
+produces an explicit compatibility error and exit status 1, not a silently
+partial read. The currently published `0.1.0-pilot.2` does not contain this fix;
+merging source alone neither replaces that immutable package nor publishes a
+new version. Older non-following clients still need upgrading for full paging.
+
+### Error handling and support
+
+The candidate exits with status 1 on command failure. Expected authentication,
+network and HTTP failures have concise diagnostics instead of a Node stack.
+An already-configured login leaves the saved credential unchanged; a failed
+logout/revocation retains it so you can retry. `logout --local` deliberately
+removes only the local copy and does not revoke remote access; use portal
+credential management if remote revocation is needed.
+
+For unexpected faults, `flightdeck --debug <command>` adds allowlisted error
+types/codes and bundled CLI line locations, not raw stacks or error bodies.
+It is not a dry-run flag: only repeat an operation that is safe to repeat.
+Provide support with the CLI/Node versions, exit status, redacted command and
+flight ID if available. Review output before sharing: account details and
+workload logs/results can contain private information. Never send passwords,
+tokens, activation links or `~/.flightdeck/config.json`.
+
 ## Versions
 
 ```sh
@@ -69,8 +186,10 @@ flightdeck --version
 npm install -g @thermai/flightdeck-cli@<approved-version>
 ```
 
-Stable releases use npm's `latest` tag. Explicit pilot/prerelease versions use
-`next`; they do not automatically replace stable installations. Updating is an
+Stable releases will use npm's `latest` tag. Explicit pilot/prerelease versions use
+`next`; they do not automatically replace stable installations. Currently
+`latest` still points at the initial pilot.1 bootstrap, not a qualified stable
+release; use `next` or the approved exact pilot version. Updating is an
 explicit install, not an automatic mutation performed when the CLI runs.
 Once a stable release exists, `npm install -g @thermai/flightdeck-cli` selects it.
 

package/dist/index.js

@@ -23,16 +23,69 @@ import {
 } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+
+// src/errors.ts
+var CliError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "CliError";
+  }
+};
+function httpError(action, status2) {
+  const guidance = status2 === 401 ? " Check the account with flightdeck whoami; sign in again if the credential expired or was revoked." : status2 === 403 ? " Check the account permissions and requested credential scopes." : status2 === 429 ? " Wait briefly before retrying." : "";
+  return new CliError(`${action} (HTTP ${status2}).${guidance}`);
+}
+var ERROR_TYPES = /* @__PURE__ */ new Set(["Error", "TypeError", "RangeError", "SyntaxError", "CliError", "AbortError"]);
+var ERROR_CODES = /* @__PURE__ */ new Set([
+  "EACCES",
+  "EPERM",
+  "ENOENT",
+  "ENOSPC",
+  "EEXIST",
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "ETIMEDOUT",
+  "ABORT_ERR",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "ERR_TLS_CERT_ALTNAME_INVALID",
+  "CERT_HAS_EXPIRED",
+  "UNABLE_TO_VERIFY_LEAF_SIGNATURE"
+]);
+function commandFailure(error, debug = false) {
+  const message = error instanceof CliError ? error.message.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").slice(0, 1e3) : "Unexpected command failure. Retry with --debug for safe diagnostics and contact your ThermAI operator if it persists.";
+  if (!debug) return `Flightdeck: ${message}`;
+  const details = [];
+  let current = error;
+  for (let depth = 0; depth < 3 && current instanceof Error; depth += 1) {
+    const code = current.code;
+    details.push(`${depth ? "cause" : "error"}=${ERROR_TYPES.has(current.name) ? current.name : "Error"}`);
+    if (code && ERROR_CODES.has(code)) details.push(`code=${code}`);
+    const frame = current.stack?.match(/\/dist\/index\.js:(\d+):(\d+)/);
+    if (frame) details.push(`cli=index.js:${frame[1]}:${frame[2]}`);
+    current = current.cause;
+  }
+  return `Flightdeck: ${message}
+Diagnostic: ${details.join("; ") || "unknown error type"}`;
+}
+
+// src/client.ts
 var DEFAULT_API_URL = "https://api.flightdeck.thermai.uk";
 var CONFIG_PATH = join(homedir(), ".flightdeck", "config.json");
 function normalizeApiUrl(value) {
-  const url = new URL(value);
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new CliError("Invalid FlightDeck API URL. Use an HTTPS URL.");
+  }
   const localHost = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
   if (url.protocol !== "https:" && !(url.protocol === "http:" && localHost)) {
-    throw new Error("FlightDeck API URLs must use HTTPS (HTTP is allowed only for localhost)");
+    throw new CliError("FlightDeck API URLs must use HTTPS (HTTP is allowed only for localhost)");
   }
   if (url.username || url.password || url.search || url.hash) {
-    throw new Error("FlightDeck API URL must not contain credentials, a query, or a fragment");
+    throw new CliError("FlightDeck API URL must not contain credentials, a query, or a fragment");
   }
   url.pathname = url.pathname.replace(/\/$/, "");
   return url.toString().replace(/\/$/, "");
@@ -61,11 +114,7 @@ function readConfig(path = CONFIG_PATH) {
 function loadConfig() {
   const config = readConfig();
   if (!config) {
-    console.error(
-      `No valid login found at ${CONFIG_PATH}.
-Run: flightdeck login`
-    );
-    process.exit(1);
+    throw new CliError("No valid local login found. Run flightdeck login.");
   }
   const stat = statSync(CONFIG_PATH);
   if ((stat.mode & 63) !== 0) {
@@ -109,7 +158,7 @@ function endpoint(apiUrl, path) {
 }
 async function publicApiRequest(apiUrl, method, path, body) {
   const headers = {};
-  return fetch(endpoint(apiUrl, path), {
+  return request(endpoint(apiUrl, path), {
     method,
     headers,
     body: requestBody(body, headers)
@@ -120,12 +169,19 @@ async function apiRequest(method, path, body) {
   const headers = {
     Authorization: `Bearer ${config.api_key}`
   };
-  return fetch(endpoint(config.api_url, path), {
+  return request(endpoint(config.api_url, path), {
     method,
     headers,
     body: requestBody(body, headers)
   });
 }
+async function request(url, options) {
+  try {
+    return await fetch(url, options);
+  } catch (cause) {
+    throw new CliError("Could not reach the Flightdeck API. Check your network connection and API URL before retrying.", { cause });
+  }
+}
 
 // ../backend/contracts/environment.js
 var MAX_CUSTOMER_ENV_ENTRIES = 64;
@@ -216,7 +272,7 @@ function parseEnvironmentArguments(envArgs) {
   const result = {};
   for (const arg of envArgs ?? []) {
     const equals = arg.indexOf("=");
-    if (equals < 1) throw new Error(`invalid env var format: ${arg} (expected KEY=VALUE)`);
+    if (equals < 1) throw new CliError("invalid env var format (expected KEY=VALUE)");
     result[arg.slice(0, equals)] = arg.slice(equals + 1);
   }
   assertEnvironmentContract(result, "customer");
@@ -896,11 +952,8 @@ ${submitted.length} submitted, ${failures} failed.`);
 // src/commands/status.ts
 async function status(flightId) {
   const response = await apiRequest("GET", `/flights/${flightId}`);
+  if (!response.ok) throw httpError("Unable to read flight status", response.status);
   const body = await response.json();
-  if (!response.ok) {
-    console.error(`Failed (${response.status}):`, JSON.stringify(body, null, 2));
-    process.exit(1);
-  }
   console.log(`Flight: ${body.flight_id}`);
   console.log(`  Name:     ${body.name}`);
   console.log(`  Status:   ${body.status}`);
@@ -914,37 +967,67 @@ async function status(flightId) {
   if (body.cost_pence) console.log(`  Cost:     ${body.cost_pence}p`);
 }
 
-// src/commands/logs.ts
-async function logs(flightId, options) {
+// src/log-reader.ts
+async function drainLogs(follow, deps) {
   let cursor;
-  do {
-    const query = cursor ? `?cursor=${encodeURIComponent(cursor)}` : "";
-    const response = await apiRequest("GET", `/flights/${flightId}/logs${query}`);
-    const body = await response.json();
-    if (!response.ok) throw new Error(`Failed (${response.status}): ${JSON.stringify(body)}`);
-    for (const entry of body.logs) {
-      const target = entry.stream === "stderr" ? process.stderr : process.stdout;
-      target.write(entry.content);
+  const seen = /* @__PURE__ */ new Set();
+  while (true) {
+    const body = await deps.readPage(cursor);
+    if (typeof body.has_more !== "boolean") {
+      throw new CliError("This backend does not support complete log pagination. Deploy the updated backend before using this CLI log command.");
+    }
+    if (!Array.isArray(body.logs) || !body.logs.every((entry) => entry && typeof entry.stream === "string" && typeof entry.content === "string") || typeof body.complete !== "boolean" || typeof body.next_cursor !== "string" || !body.next_cursor || body.has_more && body.complete) {
+      throw new CliError("Invalid log pagination response from backend.");
+    }
+    if (body.has_more && (body.next_cursor === cursor || seen.has(body.next_cursor))) {
+      throw new CliError("Log pagination cursor did not advance; stopping to avoid repeated output.");
     }
+    for (const entry of body.logs) deps.write(entry.stream, entry.content);
     cursor = body.next_cursor;
-    if (!options.follow || body.complete) break;
-    await new Promise((resolve4) => setTimeout(resolve4, 2e3));
-  } while (true);
+    if (body.has_more) {
+      seen.add(cursor);
+      continue;
+    }
+    if (!follow || body.complete) return;
+    seen.clear();
+    await deps.wait();
+  }
+}
+
+// src/commands/logs.ts
+async function logs(flightId, options) {
+  try {
+    await drainLogs(options.follow ?? false, {
+      async readPage(cursor) {
+        const query = cursor ? `?cursor=${encodeURIComponent(cursor)}` : "";
+        const response = await apiRequest("GET", `/flights/${flightId}/logs${query}`);
+        if (!response.ok) throw httpError("Log request failed", response.status);
+        const body = await response.json();
+        return body;
+      },
+      write(stream, content) {
+        (stream === "stderr" ? process.stderr : process.stdout).write(content);
+      },
+      wait: () => new Promise((resolve4) => setTimeout(resolve4, 2e3))
+    });
+  } catch (error) {
+    if (error instanceof CliError) throw new CliError(`Unable to read logs: ${error.message}`, { cause: error });
+    throw error;
+  }
 }
 
 // src/commands/cancel.ts
 async function cancel(flightId) {
   const response = await apiRequest("DELETE", `/flights/${flightId}`);
-  const body = await response.json();
-  if (!response.ok) throw new Error(`Failed (${response.status}): ${JSON.stringify(body)}`);
+  if (!response.ok) throw httpError("Unable to cancel flight", response.status);
   console.log(`Cancelled ${flightId}`);
 }
 
 // src/commands/outputs.ts
 async function listOutputs(flightId) {
   const response = await apiRequest("GET", `/flights/${flightId}/outputs`);
+  if (!response.ok) throw httpError("Unable to list outputs", response.status);
   const body = await response.json();
-  if (!response.ok) throw new Error(`Failed (${response.status}): ${JSON.stringify(body)}`);
   const outputs = body.outputs ?? [];
   if (!outputs.length) console.log("No outputs available.");
   for (const output of outputs) console.log(`${output.artifact_id}  ${output.size_bytes} bytes  ${output.filename}`);
@@ -956,13 +1039,13 @@ import { mkdir, writeFile } from "node:fs/promises";
 import { basename, join as join3, resolve as resolve3 } from "node:path";
 async function download(flightId, options) {
   const manifestResponse = await apiRequest("GET", `/flights/${flightId}/outputs`);
+  if (!manifestResponse.ok) throw httpError("Unable to list outputs for download", manifestResponse.status);
   const manifest = await manifestResponse.json();
-  if (!manifestResponse.ok) throw new Error(`Failed (${manifestResponse.status}): ${JSON.stringify(manifest)}`);
   const root = resolve3(options.outputDir);
   await mkdir(root, { recursive: true });
   for (const output of manifest.outputs ?? []) {
     const response = await apiRequest("GET", `/flights/${flightId}/outputs/${output.artifact_id}`);
-    if (!response.ok) throw new Error(`Download failed for ${output.filename} (${response.status})`);
+    if (!response.ok) throw httpError("Unable to download output", response.status);
     const target = join3(root, basename(output.filename));
     await writeFile(target, Buffer.from(await response.arrayBuffer()), { flag: "wx" });
     console.log(`Downloaded ${target}`);
@@ -1000,14 +1083,14 @@ printf 'FLIGHTDECK_SLURM_CONFORMANCE task=%s
 `;
 function positiveSeconds(value, option) {
   if (!/^\d+$/.test(value) || Number(value) < 1) {
-    throw new Error(`${option} must be a positive number of seconds`);
+    throw new CliError(`${option} must be a positive number of seconds`);
   }
   return Number(value);
 }
 async function readFlight(flightId) {
   const response = await apiRequest("GET", `/flights/${flightId}`);
+  if (!response.ok) throw httpError("Unable to read conformance flight", response.status);
   const body = await response.json();
-  if (!response.ok) throw new Error(`status ${flightId} failed (${response.status}): ${JSON.stringify(body)}`);
   return body;
 }
 async function verifyResults(flightId, taskId) {
@@ -1015,16 +1098,16 @@ async function verifyResults(flightId, taskId) {
     apiRequest("GET", `/flights/${flightId}/logs`),
     apiRequest("GET", `/flights/${flightId}/outputs`)
   ]);
+  if (!logsResponse.ok) throw httpError("Unable to read conformance logs", logsResponse.status);
+  if (!outputsResponse.ok) throw httpError("Unable to read conformance outputs", outputsResponse.status);
   const logs2 = await logsResponse.json();
   const outputs = await outputsResponse.json();
-  if (!logsResponse.ok) throw new Error(`logs ${flightId} failed (${logsResponse.status}): ${JSON.stringify(logs2)}`);
-  if (!outputsResponse.ok) throw new Error(`outputs ${flightId} failed (${outputsResponse.status}): ${JSON.stringify(outputs)}`);
   const combinedLogs = (logs2.logs ?? []).map((entry) => entry.content).join("\n");
   if (!combinedLogs.includes(`FLIGHTDECK_SLURM_CONFORMANCE task=${taskId}`)) {
-    throw new Error(`${flightId}: provider logs do not contain the task ${taskId} conformance marker`);
+    throw new CliError(`${flightId}: provider logs do not contain the task ${taskId} conformance marker`);
   }
   if (!(outputs.outputs ?? []).some((output) => output.size_bytes > 0)) {
-    throw new Error(`${flightId}: provider returned no non-empty output artifact`);
+    throw new CliError(`${flightId}: provider returned no non-empty output artifact`);
   }
 }
 async function slurmTest(options) {
@@ -1042,7 +1125,7 @@ async function slurmTest(options) {
   } finally {
     rmSync2(tempDir, { recursive: true, force: true });
   }
-  if (submitted.length !== 2) throw new Error(`expected 2 conformance flights, submitted ${submitted.length}`);
+  if (submitted.length !== 2) throw new CliError(`expected 2 conformance flights, submitted ${submitted.length}`);
   const deadline = Date.now() + timeoutMs;
   const pending = new Map(submitted.map((task) => [task.flightId, task]));
   const finished = /* @__PURE__ */ new Map();
@@ -1058,12 +1141,12 @@ async function slurmTest(options) {
     if (pending.size > 0) await new Promise((resolve4) => setTimeout(resolve4, pollIntervalMs));
   }
   if (pending.size > 0) {
-    throw new Error(`timed out waiting for: ${[...pending.keys()].join(", ")}`);
+    throw new CliError(`timed out waiting for: ${[...pending.keys()].join(", ")}`);
   }
   for (const task of submitted) {
     const flight = finished.get(task.flightId);
     if (flight.status !== "completed" || flight.exit_code !== 0) {
-      throw new Error(`${task.flightId} failed conformance: ${flight.error_message ?? `exit ${flight.exit_code}`}`);
+      throw new CliError(`${task.flightId} failed conformance. Inspect flightdeck status and logs for this flight.`);
     }
     await verifyResults(task.flightId, task.taskId);
   }
@@ -1076,24 +1159,32 @@ var SCOPES = ["jobs:read", "jobs:submit", "jobs:cancel", "account:read"];
 function sleep(milliseconds) {
   return new Promise((resolve4) => setTimeout(resolve4, milliseconds));
 }
-async function errorMessage(response) {
+async function loginFailure(response) {
   try {
     const body = await response.json();
-    return body.error ?? response.statusText;
+    if (body.error === "device_authorization_denied") {
+      return new CliError("Login was not approved. Run flightdeck login to try again.");
+    }
+    if (body.error === "expired_device_code") {
+      return new CliError("Login expired before it was approved. Run flightdeck login to try again.");
+    }
+    if (body.error === "credential_name_in_use") {
+      return new CliError("That credential name is already in use. Choose another --name or revoke the old credential in the portal.");
+    }
   } catch {
-    return response.statusText;
   }
+  return httpError("Login failed", response.status);
 }
 async function login(options) {
   if (readConfig()) {
-    throw new Error("Already logged in. Run `flightdeck logout` before replacing this credential.");
+    throw new CliError("Already logged in. Run flightdeck whoami to check the account, or flightdeck logout before signing in again.");
   }
   const apiUrl = normalizeApiUrl(options.apiUrl ?? DEFAULT_API_URL);
   const started = await publicApiRequest(apiUrl, "POST", "/auth/device/code", {
     credential_name: options.name ?? "flightdeck-cli",
     scopes: SCOPES
   });
-  if (!started.ok) throw new Error(`Unable to start login: ${await errorMessage(started)}`);
+  if (!started.ok) throw httpError("Unable to start login", started.status);
   const authorization = await started.json();
   console.log(`Open this URL to approve the CLI:
 ${authorization.verification_uri_complete}`);
@@ -1112,13 +1203,13 @@ Verification code: ${authorization.user_code}`);
       if (Number.isFinite(retryAfter) && retryAfter > 0) intervalSeconds = retryAfter;
       continue;
     }
-    if (!response.ok) throw new Error(`Login failed: ${await errorMessage(response)}`);
+    if (!response.ok) throw await loginFailure(response);
     const token = await response.json();
     saveConfig({ api_url: apiUrl, api_key: token.access_token, credential_id: token.credential_id });
     console.log("Logged in. The credential was stored in ~/.flightdeck/config.json.");
     return;
   }
-  throw new Error("Login expired before it was approved. Run `flightdeck login` to try again.");
+  throw new CliError("Login expired before it was approved. Run flightdeck login to try again.");
 }
 
 // src/commands/logout.ts
@@ -1131,11 +1222,11 @@ async function logout(options) {
     let response;
     try {
       response = await apiRequest("POST", "/auth/credential/revoke");
-    } catch (error) {
-      throw new Error(`Credential revocation failed; local login retained: ${String(error)}`);
+    } catch (cause) {
+      throw new CliError("Credential revocation failed; local login retained. Check your connection and retry flightdeck logout.", { cause });
     }
     if (!response.ok && response.status !== 401) {
-      throw new Error(`Credential revocation failed (${response.status}); local login retained.`);
+      throw new CliError(`Credential revocation failed (HTTP ${response.status}); local login retained. Retry flightdeck logout.`);
     }
   }
   deleteConfig();
@@ -1145,20 +1236,20 @@ async function logout(options) {
 // src/commands/whoami.ts
 async function whoami() {
   const response = await apiRequest("GET", "/auth/me");
-  if (!response.ok) throw new Error(`Unable to read account (${response.status}).`);
+  if (!response.ok) throw httpError("Unable to read account", response.status);
   console.log(JSON.stringify(await response.json(), null, 2));
 }
 
 // src/commands/balance.ts
 async function balance() {
   const response = await apiRequest("GET", "/billing/summary");
-  if (!response.ok) throw new Error(`Unable to read credit balance (${response.status}).`);
+  if (!response.ok) throw httpError("Unable to read credit balance", response.status);
   console.log(JSON.stringify(await response.json(), null, 2));
 }
 
 // src/index.ts
 var program = new Command();
-program.name("flightdeck").description("FlightDeck CLI \u2014 submit GPU compute jobs").version(JSON.parse(readFileSync4(new URL("../package.json", import.meta.url), "utf8")).version);
+program.name("flightdeck").description("FlightDeck CLI \u2014 submit GPU compute jobs").option("--debug", "include safe error type/code and CLI frame diagnostics (no raw stack or credentials)").version(JSON.parse(readFileSync4(new URL("../package.json", import.meta.url), "utf8")).version);
 program.command("login").description("Log in through the FlightDeck portal").option("--api-url <url>", "FlightDeck API URL", DEFAULT_API_URL).option("--name <name>", "name for this CLI credential", "flightdeck-cli").action(login);
 program.command("logout").description("Revoke this CLI credential and remove the local login").option("--local", "remove the local login without revoking the credential").action(logout);
 program.command("whoami").description("Show the current FlightDeck account").action(whoami);
@@ -1173,4 +1264,9 @@ program.command("logs").description("Stream flight logs").argument("<flight_id>"
 program.command("cancel").description("Cancel a flight").argument("<flight_id>").action(cancel);
 program.command("outputs").description("List flight outputs").argument("<flight_id>").action(listOutputs);
 program.command("download").description("Download all flight outputs").argument("<flight_id>").option("-o, --output-dir <dir>", "destination directory", ".").action(download);
-program.parse();
+try {
+  await program.parseAsync();
+} catch (error) {
+  console.error(commandFailure(error, program.opts().debug === true));
+  process.exitCode = 1;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thermai/flightdeck-cli",
-  "version": "0.1.0-pilot.2",
+  "version": "0.1.0-pilot.3",
   "description": "FlightDeck CLI — submit GPU compute jobs",
   "license": "SEE LICENSE IN LICENSE",
   "publishConfig": {
@@ -23,7 +23,8 @@
   "scripts": {
     "build": "tsc -p tsconfig.json --noEmit && esbuild src/index.ts --bundle --platform=node --target=node22 --format=esm --external:commander --external:tar --outfile=dist/index.js",
     "dev": "tsx src/index.ts",
-    "test": "node --import tsx --test \"src/**/*.test.ts\" && node --test scripts/release-policy.test.mjs",
+    "test": "node --import tsx --test \"src/**/*.test.ts\" && node --test scripts/release-policy.test.mjs && node scripts/sync-install-instructions.mjs --check",
+    "sync:install": "node scripts/sync-install-instructions.mjs --write",
     "prepack": "npm run build",
     "test:package": "node scripts/test-package.mjs"
   },