From 20bdfda0905a093f30a3e98a3f27bb2508551907 Mon Sep 17 00:00:00 2001
From: A <6723574+louisgv@users.noreply.github.com>
Date: Fri, 13 Feb 2026 21:41:06 +0000
Subject: [PATCH] fix: improve CLI UX with clearer credential status and help
 docs

- Change 'auth: TOKEN' to 'needs TOKEN' with yellow highlight in spawn clouds
- Always show legend footer explaining ready/needs indicators
- Add --clear hint to spawn list footer
- Show --version/-v and --help/-h aliases in help text
- Document SPAWN_UNICODE=1 env var in help
- Include HTTP status code in update fetch errors
- Bump version to next patch

Fixes #1010

Agent: issue-fixer
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 cli/package.json                             |  2 +-
 cli/src/__tests__/cmd-listing-output.test.ts |  5 +++--
 cli/src/commands.ts                          | 18 ++++++++++--------
 3 files changed, 14 insertions(+), 11 deletions(-)

diff --git a/cli/package.json b/cli/package.json
index 6f91869eb..880df8eb1 100644
--- a/cli/package.json
+++ b/cli/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openrouter/spawn",
-  "version": "0.2.75",
+  "version": "0.2.76",
   "type": "module",
   "bin": {
     "spawn": "cli.js"
diff --git a/cli/src/__tests__/cmd-listing-output.test.ts b/cli/src/__tests__/cmd-listing-output.test.ts
index c0521ce01..cacab541c 100644
--- a/cli/src/__tests__/cmd-listing-output.test.ts
+++ b/cli/src/__tests__/cmd-listing-output.test.ts
@@ -602,8 +602,9 @@ describe("cmdClouds output", () => {
       await cmdClouds();
 
       const output = captureOutput(consoleMocks.log);
-      expect(output).toContain("auth: SPRITE_TOKEN");
-      expect(output).toContain("auth: HCLOUD_TOKEN");
+      expect(output).toContain("needs");
+      expect(output).toContain("SPRITE_TOKEN");
+      expect(output).toContain("HCLOUD_TOKEN");
     });
 
     it("should display footer with usage hints", async () => {
diff --git a/cli/src/commands.ts b/cli/src/commands.ts
index f01c4a4fd..4ec4cc7bd 100644
--- a/cli/src/commands.ts
+++ b/cli/src/commands.ts
@@ -1086,7 +1086,7 @@ function showListFooter(records: SpawnRecord[], agentFilter?: string, cloudFilte
     console.log(pc.dim(`Clear filter: ${pc.cyan("spawn list")}`));
   } else {
     console.log(pc.dim(`${records.length} spawn${records.length !== 1 ? "s" : ""} recorded`));
-    console.log(pc.dim(`Filter: ${pc.cyan("spawn list -a <agent>")}  or  ${pc.cyan("spawn list -c <cloud>")}`));
+    console.log(pc.dim(`Filter: ${pc.cyan("spawn list -a <agent>")}  or  ${pc.cyan("spawn list -c <cloud>")}  |  Clear: ${pc.cyan("spawn list --clear")}`));
   }
   console.log();
 }
@@ -1317,13 +1317,15 @@ export async function cmdClouds(): Promise<void> {
         ? ""
         : hasCreds
           ? `  ${pc.green("ready")}`
-          : `  auth: ${c.auth}`;
-      console.log(`    ${pc.green(key.padEnd(NAME_COLUMN_WIDTH))} ${c.name.padEnd(NAME_COLUMN_WIDTH)} ${pc.dim(`${countStr.padEnd(6)} ${c.description}`)}${credIndicator ? (hasCreds ? credIndicator : pc.dim(credIndicator)) : ""}`);
+          : `  ${pc.yellow("needs")} ${pc.dim(c.auth)}`;
+      console.log(`    ${pc.green(key.padEnd(NAME_COLUMN_WIDTH))} ${c.name.padEnd(NAME_COLUMN_WIDTH)} ${pc.dim(`${countStr.padEnd(6)} ${c.description}`)}${credIndicator}`);
     }
   }
   console.log();
   if (credCount > 0) {
-    console.log(pc.dim(`  ${pc.green("ready")} = credentials detected in environment`));
+    console.log(pc.dim(`  ${pc.green("ready")} = credentials detected  ${pc.yellow("needs")} = credentials not set`));
+  } else {
+    console.log(pc.dim(`  ${pc.yellow("needs")} = credentials not set (run ${pc.cyan("spawn <cloud>")} for setup instructions)`));
   }
   console.log(pc.dim(`  Run ${pc.cyan("spawn <cloud>")} for setup instructions, or ${pc.cyan("spawn <agent> <cloud>")} to launch.`));
   console.log();
@@ -1524,7 +1526,7 @@ async function fetchRemoteVersion(): Promise<string> {
   const res = await fetch(`${RAW_BASE}/cli/package.json`, {
     signal: AbortSignal.timeout(FETCH_TIMEOUT),
   });
-  if (!res.ok) throw new Error("fetch failed");
+  if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`);
   const remotePkg = (await res.json()) as { version: string };
   return remotePkg.version;
 }
@@ -1595,8 +1597,8 @@ ${pc.bold("USAGE")}
   spawn agents                       List all agents with descriptions
   spawn clouds                       List all cloud providers
   spawn update                       Check for CLI updates
-  spawn version                      Show version
-  spawn help                         Show this help message
+  spawn version                      Show version (or --version, -v)
+  spawn help                         Show this help message (or --help, -h)
 
 ${pc.bold("EXAMPLES")}
   spawn                              ${pc.dim("# Pick interactively")}
@@ -1639,7 +1641,7 @@ ${pc.bold("ENVIRONMENT VARIABLES")}
   ${pc.cyan("OPENROUTER_API_KEY")}        OpenRouter API key (all agents require this)
   ${pc.cyan("SPAWN_NO_UPDATE_CHECK=1")}   Skip auto-update check on startup
   ${pc.cyan("SPAWN_NO_UNICODE=1")}        Force ASCII output (no unicode symbols)
-  ${pc.cyan("SPAWN_UNICODE=1")}           Force unicode output (override SSH auto-detection)
+  ${pc.cyan("SPAWN_UNICODE=1")}           Force Unicode output (override auto-detection)
   ${pc.cyan("SPAWN_HOME")}                Override spawn data directory (default: ~/.spawn)
   ${pc.cyan("SPAWN_DEBUG=1")}             Show debug output (unicode detection, etc.)