fix: improve spawn list UX with positional filters and long flags

cli/package.json

@@ -1,6 +1,6 @@
 {
  "name": "@openrouter/spawn",
- "version": "0.2.57",
+ "version": "0.2.58",
  "type": "module",
  "bin": {
  "spawn": "cli.js"

cli/src/__tests__/cmdlist-integration.test.ts

@@ -64,6 +64,7 @@ mock.module("@clack/prompts", () => ({
 
 // Import after mock setup
 const { cmdList, resolveDisplayName } = await import("../commands.js");
+const { loadManifest, _resetCacheForTesting } = await import("../manifest.js");
 
 // ── Test Setup ──────────────────────────────────────────────────────────────────
 
@@ -90,12 +91,15 @@ describe("cmdList integration", () => {
  return consoleMocks.error.mock.calls.map((c: any[]) => c.join(" ")).join("\n");
  }
 
- beforeEach(() => {
+
+ beforeEach(async () => {
  testDir = join(tmpdir(), `spawn-cmdlist-test-${Date.now()}-${Math.random()}`);
  mkdirSync(testDir, { recursive: true });
 
  originalEnv = { ...process.env };
  process.env.SPAWN_HOME = testDir;
+ // Isolate disk cache so tests don't read/write the real ~/.cache/spawn
+ process.env.XDG_CACHE_HOME = join(testDir, "cache");
 
  consoleMocks = createConsoleMocks();
  mockLogError.mockClear();
@@ -106,6 +110,15 @@ describe("cmdList integration", () => {
  mockSpinnerStop.mockClear();
 
  originalFetch = global.fetch;
+
+ // Prime the manifest in-memory cache with mock data so tests don't
+ // depend on network availability or stale values from other test files.
+ global.fetch = mock(() =>
+ Promise.resolve({ ok: true, json: async () => mockManifest }) as any
+ );
+ await loadManifest(true);
+ global.fetch = originalFetch;
+
  processExitSpy = spyOn(process, "exit").mockImplementation((() => {
  throw new Error("process.exit");
  }) as any);
@@ -258,7 +271,8 @@ describe("cmdList integration", () => {
  it("should fall back to raw keys when manifest is unavailable", async () => {
  writeHistory(sampleRecords);
 
- // Mock fetch to fail
+ // Clear in-memory cache and mock fetch to fail
+ _resetCacheForTesting();
  global.fetch = mock(() => Promise.reject(new Error("Network error")));
 
  await cmdList();

cli/src/__tests__/list-display.test.ts

@@ -32,20 +32,26 @@ function formatTimestamp(iso: string): string {
  }
 }
 
-// ── Exact replica of parseListFilters from index.ts lines 303-316 ───────────
+// ── Exact replica of parseListFilters from index.ts ─────────────────────────
 
 function parseListFilters(args: string[]): { agentFilter?: string; cloudFilter?: string } {
  let agentFilter: string | undefined;
  let cloudFilter: string | undefined;
+ const positional: string[] = [];
  for (let i = 0; i < args.length; i++) {
- if (args[i] === "-a" && args[i + 1] && !args[i + 1].startsWith("-")) {
+ if ((args[i] === "-a" || args[i] === "--agent") && args[i + 1] && !args[i + 1].startsWith("-")) {
  agentFilter = args[i + 1];
  i++;
- } else if (args[i] === "-c" && args[i + 1] && !args[i + 1].startsWith("-")) {
+ } else if ((args[i] === "-c" || args[i] === "--cloud") && args[i + 1] && !args[i + 1].startsWith("-")) {
  cloudFilter = args[i + 1];
  i++;
+ } else if (!args[i].startsWith("-")) {
+ positional.push(args[i]);
  }
  }
+ if (!agentFilter && !cloudFilter && positional.length > 0) {
+ agentFilter = positional[0];
+ }
  return { agentFilter, cloudFilter };
 }
 
@@ -205,9 +211,9 @@ describe("parseListFilters", () => {
  expect(result.cloudFilter).toBeUndefined();
  });
 
- it("should return no filters for unrelated args", () => {
- const result = parseListFilters(["list", "extra"]);
- expect(result.agentFilter).toBeUndefined();
+ it("should use first positional arg as agent filter", () => {
+ const result = parseListFilters(["claude"]);
+ expect(result.agentFilter).toBe("claude");
  expect(result.cloudFilter).toBeUndefined();
  });
 
@@ -246,11 +252,10 @@ describe("parseListFilters", () => {
  expect(result.cloudFilter).toBe("sprite");
  });
 
- it("should not confuse -a and --agent or -c and --cloud", () => {
- // Only short flags -a and -c are supported
+ it("should support --agent and --cloud long flags", () => {
  const result = parseListFilters(["--agent", "claude", "--cloud", "sprite"]);
- expect(result.agentFilter).toBeUndefined();
- expect(result.cloudFilter).toBeUndefined();
+ expect(result.agentFilter).toBe("claude");
+ expect(result.cloudFilter).toBe("sprite");
  });
 
  it("should handle value with hyphens (e.g., agent name with hyphen)", () => {
@@ -263,6 +268,30 @@ describe("parseListFilters", () => {
  expect(result.agentFilter).toBe("x");
  expect(result.cloudFilter).toBe("y");
  });
+
+ it("should not use positional arg when -a flag is present", () => {
+ const result = parseListFilters(["-a", "aider", "extra"]);
+ expect(result.agentFilter).toBe("aider");
+ expect(result.cloudFilter).toBeUndefined();
+ });
+
+ it("should not use positional arg when -c flag is present", () => {
+ const result = parseListFilters(["-c", "sprite", "extra"]);
+ expect(result.agentFilter).toBeUndefined();
+ expect(result.cloudFilter).toBe("sprite");
+ });
+
+ it("should return no filters for empty args", () => {
+ const result = parseListFilters([]);
+ expect(result.agentFilter).toBeUndefined();
+ expect(result.cloudFilter).toBeUndefined();
+ });
+
+ it("should support mixing --agent long flag with -c short flag", () => {
+ const result = parseListFilters(["--agent", "claude", "-c", "hetzner"]);
+ expect(result.agentFilter).toBe("claude");
+ expect(result.cloudFilter).toBe("hetzner");
+ });
  });
 });
 

cli/src/commands.ts

@@ -1257,8 +1257,9 @@ ${pc.bold("USAGE")}
  spawn <agent> Show available clouds for agent
  spawn <cloud> Show available agents for cloud
  spawn list Browse and rerun previous spawns
- spawn list -a <agent> Filter spawn history by agent
- spawn list -c <cloud> Filter spawn history by cloud
+ spawn list <filter> Filter history by agent or cloud name
+ spawn list -a <agent> Filter spawn history by agent (or --agent)
+ spawn list -c <cloud> Filter spawn history by cloud (or --cloud)
  Aliases: ls, history
  spawn matrix Full availability matrix (alias: m)
  spawn agents List all agents with descriptions
@@ -1280,6 +1281,7 @@ ${pc.bold("EXAMPLES")}
  spawn claude ${pc.dim("# Show which clouds support Claude")}
  spawn hetzner ${pc.dim("# Show which agents run on Hetzner")}
  spawn list ${pc.dim("# Browse history and pick one to rerun")}
+ spawn list claude ${pc.dim("# Filter history by agent name")}
  spawn matrix ${pc.dim("# See the full agent x cloud matrix")}
 
 ${pc.bold("AUTHENTICATION")}

cli/src/index.ts

@@ -63,7 +63,7 @@ const KNOWN_FLAGS = new Set([
  "--version", "-v", "-V",
  "--prompt", "-p", "--prompt-file", "-f",
  "--dry-run", "-n",
- "-a", "-c",
+ "-a", "-c", "--agent", "--cloud",
 ]);
 
 /** Check for unknown flags and show an actionable error */
@@ -293,29 +293,39 @@ function warnExtraArgs(filteredArgs: string[], maxExpected: number): void {
  }
 }
 
-/** Parse -a <agent> and -c <cloud> filter flags from args */
+/** Parse -a/--agent <agent> and -c/--cloud <cloud> filter flags from args.
+ * Also accepts a bare positional arg as a filter (e.g. "spawn list claude"). */
 function parseListFilters(args: string[]): { agentFilter?: string; cloudFilter?: string } {
  let agentFilter: string | undefined;
  let cloudFilter: string | undefined;
+ const positional: string[] = [];
  for (let i = 0; i < args.length; i++) {
- if (args[i] === "-a") {
+ if (args[i] === "-a" || args[i] === "--agent") {
  if (!args[i + 1] || args[i + 1].startsWith("-")) {
- console.error(pc.red(`Error: ${pc.bold("-a")} requires an agent name`));
+ console.error(pc.red(`Error: ${pc.bold(args[i])} requires an agent name`));
  console.error(`\nUsage: ${pc.cyan("spawn list -a <agent>")}`);
  process.exit(1);
  }
  agentFilter = args[i + 1];
  i++;
- } else if (args[i] === "-c") {
+ } else if (args[i] === "-c" || args[i] === "--cloud") {
  if (!args[i + 1] || args[i + 1].startsWith("-")) {
- console.error(pc.red(`Error: ${pc.bold("-c")} requires a cloud name`));
+ console.error(pc.red(`Error: ${pc.bold(args[i])} requires a cloud name`));
  console.error(`\nUsage: ${pc.cyan("spawn list -c <cloud>")}`);
  process.exit(1);
  }
  cloudFilter = args[i + 1];
  i++;
+ } else if (!args[i].startsWith("-")) {
+ positional.push(args[i]);
  }
  }
+
+ // Support bare positional filter: "spawn list claude" or "spawn list hetzner"
+ if (!agentFilter && !cloudFilter && positional.length > 0) {
+ agentFilter = positional[0];
+ }
+
  return { agentFilter, cloudFilter };
 }
 

cli/src/manifest.ts

@@ -208,4 +208,9 @@ export function countImplemented(m: Manifest): number {
  return count;
 }
 
+/** Clear the in-memory manifest cache (for testing only) */
+export function _resetCacheForTesting(): void {
+ _cached = null;
+}
+
 export { RAW_BASE, REPO, CACHE_DIR };

cli/package.json

@@ -1,6 +1,6 @@
 {
  "name": "@openrouter/spawn",
- "version": "0.2.57",
+ "version": "0.2.58",
  "type": "module",
  "bin": {
  "spawn": "cli.js"

cli/src/__tests__/cmdlist-integration.test.ts

@@ -64,6 +64,7 @@ mock.module("@clack/prompts", () => ({
 
 // Import after mock setup
 const { cmdList, resolveDisplayName } = await import("../commands.js");
+const { loadManifest, _resetCacheForTesting } = await import("../manifest.js");
 
 // ── Test Setup ──────────────────────────────────────────────────────────────────
 
@@ -90,12 +91,15 @@ describe("cmdList integration", () => {
  return consoleMocks.error.mock.calls.map((c: any[]) => c.join(" ")).join("\n");
  }
 
- beforeEach(() => {
+
+ beforeEach(async () => {
  testDir = join(tmpdir(), `spawn-cmdlist-test-${Date.now()}-${Math.random()}`);
  mkdirSync(testDir, { recursive: true });
 
  originalEnv = { ...process.env };
  process.env.SPAWN_HOME = testDir;
+ // Isolate disk cache so tests don't read/write the real ~/.cache/spawn
+ process.env.XDG_CACHE_HOME = join(testDir, "cache");
 
  consoleMocks = createConsoleMocks();
  mockLogError.mockClear();
@@ -106,6 +110,15 @@ describe("cmdList integration", () => {
  mockSpinnerStop.mockClear();
 
  originalFetch = global.fetch;
+
+ // Prime the manifest in-memory cache with mock data so tests don't
+ // depend on network availability or stale values from other test files.
+ global.fetch = mock(() =>
+ Promise.resolve({ ok: true, json: async () => mockManifest }) as any
+ );
+ await loadManifest(true);
+ global.fetch = originalFetch;
+
  processExitSpy = spyOn(process, "exit").mockImplementation((() => {
  throw new Error("process.exit");
  }) as any);
@@ -258,7 +271,8 @@ describe("cmdList integration", () => {
  it("should fall back to raw keys when manifest is unavailable", async () => {
  writeHistory(sampleRecords);
 
- // Mock fetch to fail
+ // Clear in-memory cache and mock fetch to fail
+ _resetCacheForTesting();
  global.fetch = mock(() => Promise.reject(new Error("Network error")));
 
  await cmdList();

cli/src/__tests__/list-display.test.ts

@@ -32,20 +32,26 @@ function formatTimestamp(iso: string): string {
  }
 }
 
-// ── Exact replica of parseListFilters from index.ts lines 303-316 ───────────
+// ── Exact replica of parseListFilters from index.ts ─────────────────────────
 
 function parseListFilters(args: string[]): { agentFilter?: string; cloudFilter?: string } {
  let agentFilter: string | undefined;
  let cloudFilter: string | undefined;
+ const positional: string[] = [];
  for (let i = 0; i < args.length; i++) {
- if (args[i] === "-a" && args[i + 1] && !args[i + 1].startsWith("-")) {
+ if ((args[i] === "-a" || args[i] === "--agent") && args[i + 1] && !args[i + 1].startsWith("-")) {
  agentFilter = args[i + 1];
  i++;
- } else if (args[i] === "-c" && args[i + 1] && !args[i + 1].startsWith("-")) {
+ } else if ((args[i] === "-c" || args[i] === "--cloud") && args[i + 1] && !args[i + 1].startsWith("-")) {
  cloudFilter = args[i + 1];
  i++;
+ } else if (!args[i].startsWith("-")) {
+ positional.push(args[i]);
  }
  }
+ if (!agentFilter && !cloudFilter && positional.length > 0) {
+ agentFilter = positional[0];
+ }
  return { agentFilter, cloudFilter };
 }
 
@@ -205,9 +211,9 @@ describe("parseListFilters", () => {
  expect(result.cloudFilter).toBeUndefined();
  });
 
- it("should return no filters for unrelated args", () => {
- const result = parseListFilters(["list", "extra"]);
- expect(result.agentFilter).toBeUndefined();
+ it("should use first positional arg as agent filter", () => {
+ const result = parseListFilters(["claude"]);
+ expect(result.agentFilter).toBe("claude");
  expect(result.cloudFilter).toBeUndefined();
  });
 
@@ -246,11 +252,10 @@ describe("parseListFilters", () => {
  expect(result.cloudFilter).toBe("sprite");
  });
 
- it("should not confuse -a and --agent or -c and --cloud", () => {
- // Only short flags -a and -c are supported
+ it("should support --agent and --cloud long flags", () => {
  const result = parseListFilters(["--agent", "claude", "--cloud", "sprite"]);
- expect(result.agentFilter).toBeUndefined();
- expect(result.cloudFilter).toBeUndefined();
+ expect(result.agentFilter).toBe("claude");
+ expect(result.cloudFilter).toBe("sprite");
  });
 
  it("should handle value with hyphens (e.g., agent name with hyphen)", () => {
@@ -263,6 +268,30 @@ describe("parseListFilters", () => {
  expect(result.agentFilter).toBe("x");
  expect(result.cloudFilter).toBe("y");
  });
+
+ it("should not use positional arg when -a flag is present", () => {
+ const result = parseListFilters(["-a", "aider", "extra"]);
+ expect(result.agentFilter).toBe("aider");
+ expect(result.cloudFilter).toBeUndefined();
+ });
+
+ it("should not use positional arg when -c flag is present", () => {
+ const result = parseListFilters(["-c", "sprite", "extra"]);
+ expect(result.agentFilter).toBeUndefined();
+ expect(result.cloudFilter).toBe("sprite");
+ });
+
+ it("should return no filters for empty args", () => {
+ const result = parseListFilters([]);
+ expect(result.agentFilter).toBeUndefined();
+ expect(result.cloudFilter).toBeUndefined();
+ });
+
+ it("should support mixing --agent long flag with -c short flag", () => {
+ const result = parseListFilters(["--agent", "claude", "-c", "hetzner"]);
+ expect(result.agentFilter).toBe("claude");
+ expect(result.cloudFilter).toBe("hetzner");
+ });
  });
 });
 

cli/src/commands.ts

@@ -1257,8 +1257,9 @@ ${pc.bold("USAGE")}
  spawn <agent> Show available clouds for agent
  spawn <cloud> Show available agents for cloud
  spawn list Browse and rerun previous spawns
- spawn list -a <agent> Filter spawn history by agent
- spawn list -c <cloud> Filter spawn history by cloud
+ spawn list <filter> Filter history by agent or cloud name
+ spawn list -a <agent> Filter spawn history by agent (or --agent)
+ spawn list -c <cloud> Filter spawn history by cloud (or --cloud)
  Aliases: ls, history
  spawn matrix Full availability matrix (alias: m)
  spawn agents List all agents with descriptions
@@ -1280,6 +1281,7 @@ ${pc.bold("EXAMPLES")}
  spawn claude ${pc.dim("# Show which clouds support Claude")}
  spawn hetzner ${pc.dim("# Show which agents run on Hetzner")}
  spawn list ${pc.dim("# Browse history and pick one to rerun")}
+ spawn list claude ${pc.dim("# Filter history by agent name")}
  spawn matrix ${pc.dim("# See the full agent x cloud matrix")}
 
 ${pc.bold("AUTHENTICATION")}

cli/src/index.ts

@@ -63,7 +63,7 @@ const KNOWN_FLAGS = new Set([
  "--version", "-v", "-V",
  "--prompt", "-p", "--prompt-file", "-f",
  "--dry-run", "-n",
- "-a", "-c",
+ "-a", "-c", "--agent", "--cloud",
 ]);
 
 /** Check for unknown flags and show an actionable error */
@@ -293,29 +293,39 @@ function warnExtraArgs(filteredArgs: string[], maxExpected: number): void {
  }
 }
 
-/** Parse -a <agent> and -c <cloud> filter flags from args */
+/** Parse -a/--agent <agent> and -c/--cloud <cloud> filter flags from args.
+ * Also accepts a bare positional arg as a filter (e.g. "spawn list claude"). */
 function parseListFilters(args: string[]): { agentFilter?: string; cloudFilter?: string } {
  let agentFilter: string | undefined;
  let cloudFilter: string | undefined;
+ const positional: string[] = [];
  for (let i = 0; i < args.length; i++) {
- if (args[i] === "-a") {
+ if (args[i] === "-a" || args[i] === "--agent") {
  if (!args[i + 1] || args[i + 1].startsWith("-")) {
- console.error(pc.red(`Error: ${pc.bold("-a")} requires an agent name`));
+ console.error(pc.red(`Error: ${pc.bold(args[i])} requires an agent name`));
  console.error(`\nUsage: ${pc.cyan("spawn list -a <agent>")}`);
  process.exit(1);
  }
  agentFilter = args[i + 1];
  i++;
- } else if (args[i] === "-c") {
+ } else if (args[i] === "-c" || args[i] === "--cloud") {
  if (!args[i + 1] || args[i + 1].startsWith("-")) {
- console.error(pc.red(`Error: ${pc.bold("-c")} requires a cloud name`));
+ console.error(pc.red(`Error: ${pc.bold(args[i])} requires a cloud name`));
  console.error(`\nUsage: ${pc.cyan("spawn list -c <cloud>")}`);
  process.exit(1);
  }
  cloudFilter = args[i + 1];
  i++;
+ } else if (!args[i].startsWith("-")) {
+ positional.push(args[i]);
  }
  }
+
+ // Support bare positional filter: "spawn list claude" or "spawn list hetzner"
+ if (!agentFilter && !cloudFilter && positional.length > 0) {
+ agentFilter = positional[0];
+ }
+
  return { agentFilter, cloudFilter };
 }
 

cli/src/manifest.ts

@@ -208,4 +208,9 @@ export function countImplemented(m: Manifest): number {
  return count;
 }
 
+/** Clear the in-memory manifest cache (for testing only) */
+export function _resetCacheForTesting(): void {
+ _cached = null;
+}
+
 export { RAW_BASE, REPO, CACHE_DIR };

cli/package.json

@@ -1,6 +1,6 @@
 {
  "name": "@openrouter/spawn",
- "version": "0.2.57",
+ "version": "0.2.58",
  "type": "module",
  "bin": {
  "spawn": "cli.js"

cli/src/__tests__/cmdlist-integration.test.ts

@@ -64,6 +64,7 @@ mock.module("@clack/prompts", () => ({
 
 // Import after mock setup
 const { cmdList, resolveDisplayName } = await import("../commands.js");
+const { loadManifest, _resetCacheForTesting } = await import("../manifest.js");
 
 // ── Test Setup ──────────────────────────────────────────────────────────────────
 
@@ -90,12 +91,15 @@ describe("cmdList integration", () => {
  return consoleMocks.error.mock.calls.map((c: any[]) => c.join(" ")).join("\n");
  }
 
- beforeEach(() => {
+
+ beforeEach(async () => {
  testDir = join(tmpdir(), `spawn-cmdlist-test-${Date.now()}-${Math.random()}`);
  mkdirSync(testDir, { recursive: true });
 
  originalEnv = { ...process.env };
  process.env.SPAWN_HOME = testDir;
+ // Isolate disk cache so tests don't read/write the real ~/.cache/spawn
+ process.env.XDG_CACHE_HOME = join(testDir, "cache");
 
  consoleMocks = createConsoleMocks();
  mockLogError.mockClear();
@@ -106,6 +110,15 @@ describe("cmdList integration", () => {
  mockSpinnerStop.mockClear();
 
  originalFetch = global.fetch;
+
+ // Prime the manifest in-memory cache with mock data so tests don't
+ // depend on network availability or stale values from other test files.
+ global.fetch = mock(() =>
+ Promise.resolve({ ok: true, json: async () => mockManifest }) as any
+ );
+ await loadManifest(true);
+ global.fetch = originalFetch;
+
  processExitSpy = spyOn(process, "exit").mockImplementation((() => {
  throw new Error("process.exit");
  }) as any);
@@ -258,7 +271,8 @@ describe("cmdList integration", () => {
  it("should fall back to raw keys when manifest is unavailable", async () => {
  writeHistory(sampleRecords);
 
- // Mock fetch to fail
+ // Clear in-memory cache and mock fetch to fail
+ _resetCacheForTesting();
  global.fetch = mock(() => Promise.reject(new Error("Network error")));
 
  await cmdList();

cli/src/__tests__/list-display.test.ts

@@ -32,20 +32,26 @@ function formatTimestamp(iso: string): string {
  }
 }
 
-// ── Exact replica of parseListFilters from index.ts lines 303-316 ───────────
+// ── Exact replica of parseListFilters from index.ts ─────────────────────────
 
 function parseListFilters(args: string[]): { agentFilter?: string; cloudFilter?: string } {
  let agentFilter: string | undefined;
  let cloudFilter: string | undefined;
+ const positional: string[] = [];
  for (let i = 0; i < args.length; i++) {
- if (args[i] === "-a" && args[i + 1] && !args[i + 1].startsWith("-")) {
+ if ((args[i] === "-a" || args[i] === "--agent") && args[i + 1] && !args[i + 1].startsWith("-")) {
  agentFilter = args[i + 1];
  i++;
- } else if (args[i] === "-c" && args[i + 1] && !args[i + 1].startsWith("-")) {
+ } else if ((args[i] === "-c" || args[i] === "--cloud") && args[i + 1] && !args[i + 1].startsWith("-")) {
  cloudFilter = args[i + 1];
  i++;
+ } else if (!args[i].startsWith("-")) {
+ positional.push(args[i]);
  }
  }
+ if (!agentFilter && !cloudFilter && positional.length > 0) {
+ agentFilter = positional[0];
+ }
  return { agentFilter, cloudFilter };
 }
 
@@ -205,9 +211,9 @@ describe("parseListFilters", () => {
  expect(result.cloudFilter).toBeUndefined();
  });
 
- it("should return no filters for unrelated args", () => {
- const result = parseListFilters(["list", "extra"]);
- expect(result.agentFilter).toBeUndefined();
+ it("should use first positional arg as agent filter", () => {
+ const result = parseListFilters(["claude"]);
+ expect(result.agentFilter).toBe("claude");
  expect(result.cloudFilter).toBeUndefined();
  });
 
@@ -246,11 +252,10 @@ describe("parseListFilters", () => {
  expect(result.cloudFilter).toBe("sprite");
  });
 
- it("should not confuse -a and --agent or -c and --cloud", () => {
- // Only short flags -a and -c are supported
+ it("should support --agent and --cloud long flags", () => {
  const result = parseListFilters(["--agent", "claude", "--cloud", "sprite"]);
- expect(result.agentFilter).toBeUndefined();
- expect(result.cloudFilter).toBeUndefined();
+ expect(result.agentFilter).toBe("claude");
+ expect(result.cloudFilter).toBe("sprite");
  });
 
  it("should handle value with hyphens (e.g., agent name with hyphen)", () => {
@@ -263,6 +268,30 @@ describe("parseListFilters", () => {
  expect(result.agentFilter).toBe("x");
  expect(result.cloudFilter).toBe("y");
  });
+
+ it("should not use positional arg when -a flag is present", () => {
+ const result = parseListFilters(["-a", "aider", "extra"]);
+ expect(result.agentFilter).toBe("aider");
+ expect(result.cloudFilter).toBeUndefined();
+ });
+
+ it("should not use positional arg when -c flag is present", () => {
+ const result = parseListFilters(["-c", "sprite", "extra"]);
+ expect(result.agentFilter).toBeUndefined();
+ expect(result.cloudFilter).toBe("sprite");
+ });
+
+ it("should return no filters for empty args", () => {
+ const result = parseListFilters([]);
+ expect(result.agentFilter).toBeUndefined();
+ expect(result.cloudFilter).toBeUndefined();
+ });
+
+ it("should support mixing --agent long flag with -c short flag", () => {
+ const result = parseListFilters(["--agent", "claude", "-c", "hetzner"]);
+ expect(result.agentFilter).toBe("claude");
+ expect(result.cloudFilter).toBe("hetzner");
+ });
  });
 });
 

cli/src/commands.ts

@@ -1257,8 +1257,9 @@ ${pc.bold("USAGE")}
  spawn <agent> Show available clouds for agent
  spawn <cloud> Show available agents for cloud
  spawn list Browse and rerun previous spawns
- spawn list -a <agent> Filter spawn history by agent
- spawn list -c <cloud> Filter spawn history by cloud
+ spawn list <filter> Filter history by agent or cloud name
+ spawn list -a <agent> Filter spawn history by agent (or --agent)
+ spawn list -c <cloud> Filter spawn history by cloud (or --cloud)
  Aliases: ls, history
  spawn matrix Full availability matrix (alias: m)
  spawn agents List all agents with descriptions
@@ -1280,6 +1281,7 @@ ${pc.bold("EXAMPLES")}
  spawn claude ${pc.dim("# Show which clouds support Claude")}
  spawn hetzner ${pc.dim("# Show which agents run on Hetzner")}
  spawn list ${pc.dim("# Browse history and pick one to rerun")}
+ spawn list claude ${pc.dim("# Filter history by agent name")}
  spawn matrix ${pc.dim("# See the full agent x cloud matrix")}
 
 ${pc.bold("AUTHENTICATION")}

cli/src/index.ts

@@ -63,7 +63,7 @@ const KNOWN_FLAGS = new Set([
  "--version", "-v", "-V",
  "--prompt", "-p", "--prompt-file", "-f",
  "--dry-run", "-n",
- "-a", "-c",
+ "-a", "-c", "--agent", "--cloud",
 ]);
 
 /** Check for unknown flags and show an actionable error */
@@ -293,29 +293,39 @@ function warnExtraArgs(filteredArgs: string[], maxExpected: number): void {
  }
 }
 
-/** Parse -a <agent> and -c <cloud> filter flags from args */
+/** Parse -a/--agent <agent> and -c/--cloud <cloud> filter flags from args.
+ * Also accepts a bare positional arg as a filter (e.g. "spawn list claude"). */
 function parseListFilters(args: string[]): { agentFilter?: string; cloudFilter?: string } {
  let agentFilter: string | undefined;
  let cloudFilter: string | undefined;
+ const positional: string[] = [];
  for (let i = 0; i < args.length; i++) {
- if (args[i] === "-a") {
+ if (args[i] === "-a" || args[i] === "--agent") {
  if (!args[i + 1] || args[i + 1].startsWith("-")) {
- console.error(pc.red(`Error: ${pc.bold("-a")} requires an agent name`));
+ console.error(pc.red(`Error: ${pc.bold(args[i])} requires an agent name`));
  console.error(`\nUsage: ${pc.cyan("spawn list -a <agent>")}`);
  process.exit(1);
  }
  agentFilter = args[i + 1];
  i++;
- } else if (args[i] === "-c") {
+ } else if (args[i] === "-c" || args[i] === "--cloud") {
  if (!args[i + 1] || args[i + 1].startsWith("-")) {
- console.error(pc.red(`Error: ${pc.bold("-c")} requires a cloud name`));
+ console.error(pc.red(`Error: ${pc.bold(args[i])} requires a cloud name`));
  console.error(`\nUsage: ${pc.cyan("spawn list -c <cloud>")}`);
  process.exit(1);
  }
  cloudFilter = args[i + 1];
  i++;
+ } else if (!args[i].startsWith("-")) {
+ positional.push(args[i]);
  }
  }
+
+ // Support bare positional filter: "spawn list claude" or "spawn list hetzner"
+ if (!agentFilter && !cloudFilter && positional.length > 0) {
+ agentFilter = positional[0];
+ }
+
  return { agentFilter, cloudFilter };
 }
 

cli/src/manifest.ts

@@ -208,4 +208,9 @@ export function countImplemented(m: Manifest): number {
  return count;
 }
 
+/** Clear the in-memory manifest cache (for testing only) */
+export function _resetCacheForTesting(): void {
+ _cached = null;
+}
+
 export { RAW_BASE, REPO, CACHE_DIR };

cli/package.json

@@ -1,6 +1,6 @@
 {
  "name": "@openrouter/spawn",
- "version": "0.2.57",
+ "version": "0.2.58",
  "type": "module",
  "bin": {
  "spawn": "cli.js"

cli/src/__tests__/cmdlist-integration.test.ts

@@ -64,6 +64,7 @@ mock.module("@clack/prompts", () => ({
 
 // Import after mock setup
 const { cmdList, resolveDisplayName } = await import("../commands.js");
+const { loadManifest, _resetCacheForTesting } = await import("../manifest.js");
 
 // ── Test Setup ──────────────────────────────────────────────────────────────────
 
@@ -90,12 +91,15 @@ describe("cmdList integration", () => {
  return consoleMocks.error.mock.calls.map((c: any[]) => c.join(" ")).join("\n");
  }
 
- beforeEach(() => {
+
+ beforeEach(async () => {
  testDir = join(tmpdir(), `spawn-cmdlist-test-${Date.now()}-${Math.random()}`);
  mkdirSync(testDir, { recursive: true });
 
  originalEnv = { ...process.env };
  process.env.SPAWN_HOME = testDir;
+ // Isolate disk cache so tests don't read/write the real ~/.cache/spawn
+ process.env.XDG_CACHE_HOME = join(testDir, "cache");
 
  consoleMocks = createConsoleMocks();
  mockLogError.mockClear();
@@ -106,6 +110,15 @@ describe("cmdList integration", () => {
  mockSpinnerStop.mockClear();
 
  originalFetch = global.fetch;
+
+ // Prime the manifest in-memory cache with mock data so tests don't
+ // depend on network availability or stale values from other test files.
+ global.fetch = mock(() =>
+ Promise.resolve({ ok: true, json: async () => mockManifest }) as any
+ );
+ await loadManifest(true);
+ global.fetch = originalFetch;
+
  processExitSpy = spyOn(process, "exit").mockImplementation((() => {
  throw new Error("process.exit");
  }) as any);
@@ -258,7 +271,8 @@ describe("cmdList integration", () => {
  it("should fall back to raw keys when manifest is unavailable", async () => {
  writeHistory(sampleRecords);
 
- // Mock fetch to fail
+ // Clear in-memory cache and mock fetch to fail
+ _resetCacheForTesting();
  global.fetch = mock(() => Promise.reject(new Error("Network error")));
 
  await cmdList();

cli/src/__tests__/list-display.test.ts

@@ -32,20 +32,26 @@ function formatTimestamp(iso: string): string {
  }
 }
 
-// ── Exact replica of parseListFilters from index.ts lines 303-316 ───────────
+// ── Exact replica of parseListFilters from index.ts ─────────────────────────
 
 function parseListFilters(args: string[]): { agentFilter?: string; cloudFilter?: string } {
  let agentFilter: string | undefined;
  let cloudFilter: string | undefined;
+ const positional: string[] = [];
  for (let i = 0; i < args.length; i++) {
- if (args[i] === "-a" && args[i + 1] && !args[i + 1].startsWith("-")) {
+ if ((args[i] === "-a" || args[i] === "--agent") && args[i + 1] && !args[i + 1].startsWith("-")) {
  agentFilter = args[i + 1];
  i++;
- } else if (args[i] === "-c" && args[i + 1] && !args[i + 1].startsWith("-")) {
+ } else if ((args[i] === "-c" || args[i] === "--cloud") && args[i + 1] && !args[i + 1].startsWith("-")) {
  cloudFilter = args[i + 1];
  i++;
+ } else if (!args[i].startsWith("-")) {
+ positional.push(args[i]);
  }
  }
+ if (!agentFilter && !cloudFilter && positional.length > 0) {
+ agentFilter = positional[0];
+ }
  return { agentFilter, cloudFilter };
 }
 
@@ -205,9 +211,9 @@ describe("parseListFilters", () => {
  expect(result.cloudFilter).toBeUndefined();
  });
 
- it("should return no filters for unrelated args", () => {
- const result = parseListFilters(["list", "extra"]);
- expect(result.agentFilter).toBeUndefined();
+ it("should use first positional arg as agent filter", () => {
+ const result = parseListFilters(["claude"]);
+ expect(result.agentFilter).toBe("claude");
  expect(result.cloudFilter).toBeUndefined();
  });
 
@@ -246,11 +252,10 @@ describe("parseListFilters", () => {
  expect(result.cloudFilter).toBe("sprite");
  });
 
- it("should not confuse -a and --agent or -c and --cloud", () => {
- // Only short flags -a and -c are supported
+ it("should support --agent and --cloud long flags", () => {
  const result = parseListFilters(["--agent", "claude", "--cloud", "sprite"]);
- expect(result.agentFilter).toBeUndefined();
- expect(result.cloudFilter).toBeUndefined();
+ expect(result.agentFilter).toBe("claude");
+ expect(result.cloudFilter).toBe("sprite");
  });
 
  it("should handle value with hyphens (e.g., agent name with hyphen)", () => {
@@ -263,6 +268,30 @@ describe("parseListFilters", () => {
  expect(result.agentFilter).toBe("x");
  expect(result.cloudFilter).toBe("y");
  });
+
+ it("should not use positional arg when -a flag is present", () => {
+ const result = parseListFilters(["-a", "aider", "extra"]);
+ expect(result.agentFilter).toBe("aider");
+ expect(result.cloudFilter).toBeUndefined();
+ });
+
+ it("should not use positional arg when -c flag is present", () => {
+ const result = parseListFilters(["-c", "sprite", "extra"]);
+ expect(result.agentFilter).toBeUndefined();
+ expect(result.cloudFilter).toBe("sprite");
+ });
+
+ it("should return no filters for empty args", () => {
+ const result = parseListFilters([]);
+ expect(result.agentFilter).toBeUndefined();
+ expect(result.cloudFilter).toBeUndefined();
+ });
+
+ it("should support mixing --agent long flag with -c short flag", () => {
+ const result = parseListFilters(["--agent", "claude", "-c", "hetzner"]);
+ expect(result.agentFilter).toBe("claude");
+ expect(result.cloudFilter).toBe("hetzner");
+ });
  });
 });
 

cli/src/commands.ts

@@ -1257,8 +1257,9 @@ ${pc.bold("USAGE")}
  spawn <agent> Show available clouds for agent
  spawn <cloud> Show available agents for cloud
  spawn list Browse and rerun previous spawns
- spawn list -a <agent> Filter spawn history by agent
- spawn list -c <cloud> Filter spawn history by cloud
+ spawn list <filter> Filter history by agent or cloud name
+ spawn list -a <agent> Filter spawn history by agent (or --agent)
+ spawn list -c <cloud> Filter spawn history by cloud (or --cloud)
  Aliases: ls, history
  spawn matrix Full availability matrix (alias: m)
  spawn agents List all agents with descriptions
@@ -1280,6 +1281,7 @@ ${pc.bold("EXAMPLES")}
  spawn claude ${pc.dim("# Show which clouds support Claude")}
  spawn hetzner ${pc.dim("# Show which agents run on Hetzner")}
  spawn list ${pc.dim("# Browse history and pick one to rerun")}
+ spawn list claude ${pc.dim("# Filter history by agent name")}
  spawn matrix ${pc.dim("# See the full agent x cloud matrix")}
 
 ${pc.bold("AUTHENTICATION")}

cli/src/index.ts

@@ -63,7 +63,7 @@ const KNOWN_FLAGS = new Set([
  "--version", "-v", "-V",
  "--prompt", "-p", "--prompt-file", "-f",
  "--dry-run", "-n",
- "-a", "-c",
+ "-a", "-c", "--agent", "--cloud",
 ]);
 
 /** Check for unknown flags and show an actionable error */
@@ -293,29 +293,39 @@ function warnExtraArgs(filteredArgs: string[], maxExpected: number): void {
  }
 }
 
-/** Parse -a <agent> and -c <cloud> filter flags from args */
+/** Parse -a/--agent <agent> and -c/--cloud <cloud> filter flags from args.
+ * Also accepts a bare positional arg as a filter (e.g. "spawn list claude"). */
 function parseListFilters(args: string[]): { agentFilter?: string; cloudFilter?: string } {
  let agentFilter: string | undefined;
  let cloudFilter: string | undefined;
+ const positional: string[] = [];
  for (let i = 0; i < args.length; i++) {
- if (args[i] === "-a") {
+ if (args[i] === "-a" || args[i] === "--agent") {
  if (!args[i + 1] || args[i + 1].startsWith("-")) {
- console.error(pc.red(`Error: ${pc.bold("-a")} requires an agent name`));
+ console.error(pc.red(`Error: ${pc.bold(args[i])} requires an agent name`));
  console.error(`\nUsage: ${pc.cyan("spawn list -a <agent>")}`);
  process.exit(1);
  }
  agentFilter = args[i + 1];
  i++;
- } else if (args[i] === "-c") {
+ } else if (args[i] === "-c" || args[i] === "--cloud") {
  if (!args[i + 1] || args[i + 1].startsWith("-")) {
- console.error(pc.red(`Error: ${pc.bold("-c")} requires a cloud name`));
+ console.error(pc.red(`Error: ${pc.bold(args[i])} requires a cloud name`));
  console.error(`\nUsage: ${pc.cyan("spawn list -c <cloud>")}`);
  process.exit(1);
  }
  cloudFilter = args[i + 1];
  i++;
+ } else if (!args[i].startsWith("-")) {
+ positional.push(args[i]);
  }
  }
+
+ // Support bare positional filter: "spawn list claude" or "spawn list hetzner"
+ if (!agentFilter && !cloudFilter && positional.length > 0) {
+ agentFilter = positional[0];
+ }
+
  return { agentFilter, cloudFilter };
 }
 

cli/src/manifest.ts

@@ -208,4 +208,9 @@ export function countImplemented(m: Manifest): number {
  return count;
 }
 
+/** Clear the in-memory manifest cache (for testing only) */
+export function _resetCacheForTesting(): void {
+ _cached = null;
+}
+
 export { RAW_BASE, REPO, CACHE_DIR };

cli/package.json

@@ -1,6 +1,6 @@
 {
  "name": "@openrouter/spawn",
- "version": "0.2.57",
+ "version": "0.2.58",
  "type": "module",
  "bin": {
  "spawn": "cli.js"

cli/src/__tests__/cmdlist-integration.test.ts

@@ -64,6 +64,7 @@ mock.module("@clack/prompts", () => ({
 
 // Import after mock setup
 const { cmdList, resolveDisplayName } = await import("../commands.js");
+const { loadManifest, _resetCacheForTesting } = await import("../manifest.js");
 
 // ── Test Setup ──────────────────────────────────────────────────────────────────
 
@@ -90,12 +91,15 @@ describe("cmdList integration", () => {
  return consoleMocks.error.mock.calls.map((c: any[]) => c.join(" ")).join("\n");
  }
 
- beforeEach(() => {
+
+ beforeEach(async () => {
  testDir = join(tmpdir(), `spawn-cmdlist-test-${Date.now()}-${Math.random()}`);
  mkdirSync(testDir, { recursive: true });
 
  originalEnv = { ...process.env };
  process.env.SPAWN_HOME = testDir;
+ // Isolate disk cache so tests don't read/write the real ~/.cache/spawn
+ process.env.XDG_CACHE_HOME = join(testDir, "cache");
 
  consoleMocks = createConsoleMocks();
  mockLogError.mockClear();
@@ -106,6 +110,15 @@ describe("cmdList integration", () => {
  mockSpinnerStop.mockClear();
 
  originalFetch = global.fetch;
+
+ // Prime the manifest in-memory cache with mock data so tests don't
+ // depend on network availability or stale values from other test files.
+ global.fetch = mock(() =>
+ Promise.resolve({ ok: true, json: async () => mockManifest }) as any
+ );
+ await loadManifest(true);
+ global.fetch = originalFetch;
+
  processExitSpy = spyOn(process, "exit").mockImplementation((() => {
  throw new Error("process.exit");
  }) as any);
@@ -258,7 +271,8 @@ describe("cmdList integration", () => {
  it("should fall back to raw keys when manifest is unavailable", async () => {
  writeHistory(sampleRecords);
 
- // Mock fetch to fail
+ // Clear in-memory cache and mock fetch to fail
+ _resetCacheForTesting();
  global.fetch = mock(() => Promise.reject(new Error("Network error")));
 
  await cmdList();

cli/src/__tests__/list-display.test.ts

@@ -32,20 +32,26 @@ function formatTimestamp(iso: string): string {
  }
 }
 
-// ── Exact replica of parseListFilters from index.ts lines 303-316 ───────────
+// ── Exact replica of parseListFilters from index.ts ─────────────────────────
 
 function parseListFilters(args: string[]): { agentFilter?: string; cloudFilter?: string } {
  let agentFilter: string | undefined;
  let cloudFilter: string | undefined;
+ const positional: string[] = [];
  for (let i = 0; i < args.length; i++) {
- if (args[i] === "-a" && args[i + 1] && !args[i + 1].startsWith("-")) {
+ if ((args[i] === "-a" || args[i] === "--agent") && args[i + 1] && !args[i + 1].startsWith("-")) {
  agentFilter = args[i + 1];
  i++;
- } else if (args[i] === "-c" && args[i + 1] && !args[i + 1].startsWith("-")) {
+ } else if ((args[i] === "-c" || args[i] === "--cloud") && args[i + 1] && !args[i + 1].startsWith("-")) {
  cloudFilter = args[i + 1];
  i++;
+ } else if (!args[i].startsWith("-")) {
+ positional.push(args[i]);
  }
  }
+ if (!agentFilter && !cloudFilter && positional.length > 0) {
+ agentFilter = positional[0];
+ }
  return { agentFilter, cloudFilter };
 }
 
@@ -205,9 +211,9 @@ describe("parseListFilters", () => {
  expect(result.cloudFilter).toBeUndefined();
  });
 
- it("should return no filters for unrelated args", () => {
- const result = parseListFilters(["list", "extra"]);
- expect(result.agentFilter).toBeUndefined();
+ it("should use first positional arg as agent filter", () => {
+ const result = parseListFilters(["claude"]);
+ expect(result.agentFilter).toBe("claude");
  expect(result.cloudFilter).toBeUndefined();
  });
 
@@ -246,11 +252,10 @@ describe("parseListFilters", () => {
  expect(result.cloudFilter).toBe("sprite");
  });
 
- it("should not confuse -a and --agent or -c and --cloud", () => {
- // Only short flags -a and -c are supported
+ it("should support --agent and --cloud long flags", () => {
  const result = parseListFilters(["--agent", "claude", "--cloud", "sprite"]);
- expect(result.agentFilter).toBeUndefined();
- expect(result.cloudFilter).toBeUndefined();
+ expect(result.agentFilter).toBe("claude");
+ expect(result.cloudFilter).toBe("sprite");
  });
 
  it("should handle value with hyphens (e.g., agent name with hyphen)", () => {
@@ -263,6 +268,30 @@ describe("parseListFilters", () => {
  expect(result.agentFilter).toBe("x");
  expect(result.cloudFilter).toBe("y");
  });
+
+ it("should not use positional arg when -a flag is present", () => {
+ const result = parseListFilters(["-a", "aider", "extra"]);
+ expect(result.agentFilter).toBe("aider");
+ expect(result.cloudFilter).toBeUndefined();
+ });
+
+ it("should not use positional arg when -c flag is present", () => {
+ const result = parseListFilters(["-c", "sprite", "extra"]);
+ expect(result.agentFilter).toBeUndefined();
+ expect(result.cloudFilter).toBe("sprite");
+ });
+
+ it("should return no filters for empty args", () => {
+ const result = parseListFilters([]);
+ expect(result.agentFilter).toBeUndefined();
+ expect(result.cloudFilter).toBeUndefined();
+ });
+
+ it("should support mixing --agent long flag with -c short flag", () => {
+ const result = parseListFilters(["--agent", "claude", "-c", "hetzner"]);
+ expect(result.agentFilter).toBe("claude");
+ expect(result.cloudFilter).toBe("hetzner");
+ });
  });
 });
 

cli/src/commands.ts

@@ -1257,8 +1257,9 @@ ${pc.bold("USAGE")}
  spawn <agent> Show available clouds for agent
  spawn <cloud> Show available agents for cloud
  spawn list Browse and rerun previous spawns
- spawn list -a <agent> Filter spawn history by agent
- spawn list -c <cloud> Filter spawn history by cloud
+ spawn list <filter> Filter history by agent or cloud name
+ spawn list -a <agent> Filter spawn history by agent (or --agent)
+ spawn list -c <cloud> Filter spawn history by cloud (or --cloud)
  Aliases: ls, history
  spawn matrix Full availability matrix (alias: m)
  spawn agents List all agents with descriptions
@@ -1280,6 +1281,7 @@ ${pc.bold("EXAMPLES")}
  spawn claude ${pc.dim("# Show which clouds support Claude")}
  spawn hetzner ${pc.dim("# Show which agents run on Hetzner")}
  spawn list ${pc.dim("# Browse history and pick one to rerun")}
+ spawn list claude ${pc.dim("# Filter history by agent name")}
  spawn matrix ${pc.dim("# See the full agent x cloud matrix")}
 
 ${pc.bold("AUTHENTICATION")}

cli/src/index.ts

@@ -63,7 +63,7 @@ const KNOWN_FLAGS = new Set([
  "--version", "-v", "-V",
  "--prompt", "-p", "--prompt-file", "-f",
  "--dry-run", "-n",
- "-a", "-c",
+ "-a", "-c", "--agent", "--cloud",
 ]);
 
 /** Check for unknown flags and show an actionable error */
@@ -293,29 +293,39 @@ function warnExtraArgs(filteredArgs: string[], maxExpected: number): void {
  }
 }
 
-/** Parse -a <agent> and -c <cloud> filter flags from args */
+/** Parse -a/--agent <agent> and -c/--cloud <cloud> filter flags from args.
+ * Also accepts a bare positional arg as a filter (e.g. "spawn list claude"). */
 function parseListFilters(args: string[]): { agentFilter?: string; cloudFilter?: string } {
  let agentFilter: string | undefined;
  let cloudFilter: string | undefined;
+ const positional: string[] = [];
  for (let i = 0; i < args.length; i++) {
- if (args[i] === "-a") {
+ if (args[i] === "-a" || args[i] === "--agent") {
  if (!args[i + 1] || args[i + 1].startsWith("-")) {
- console.error(pc.red(`Error: ${pc.bold("-a")} requires an agent name`));
+ console.error(pc.red(`Error: ${pc.bold(args[i])} requires an agent name`));
  console.error(`\nUsage: ${pc.cyan("spawn list -a <agent>")}`);
  process.exit(1);
  }
  agentFilter = args[i + 1];
  i++;
- } else if (args[i] === "-c") {
+ } else if (args[i] === "-c" || args[i] === "--cloud") {
  if (!args[i + 1] || args[i + 1].startsWith("-")) {
- console.error(pc.red(`Error: ${pc.bold("-c")} requires a cloud name`));
+ console.error(pc.red(`Error: ${pc.bold(args[i])} requires a cloud name`));
  console.error(`\nUsage: ${pc.cyan("spawn list -c <cloud>")}`);
  process.exit(1);
  }
  cloudFilter = args[i + 1];
  i++;
+ } else if (!args[i].startsWith("-")) {
+ positional.push(args[i]);
  }
  }
+
+ // Support bare positional filter: "spawn list claude" or "spawn list hetzner"
+ if (!agentFilter && !cloudFilter && positional.length > 0) {
+ agentFilter = positional[0];
+ }
+
  return { agentFilter, cloudFilter };
 }
 

cli/src/manifest.ts

@@ -208,4 +208,9 @@ export function countImplemented(m: Manifest): number {
  return count;
 }
 
+/** Clear the in-memory manifest cache (for testing only) */
+export function _resetCacheForTesting(): void {
+ _cached = null;
+}
+
 export { RAW_BASE, REPO, CACHE_DIR };

cli/package.json

@@ -1,6 +1,6 @@
 {
  "name": "@openrouter/spawn",
- "version": "0.2.57",
+ "version": "0.2.58",
  "type": "module",
  "bin": {
  "spawn": "cli.js"

cli/src/__tests__/cmdlist-integration.test.ts

@@ -64,6 +64,7 @@ mock.module("@clack/prompts", () => ({
 
 // Import after mock setup
 const { cmdList, resolveDisplayName } = await import("../commands.js");
+const { loadManifest, _resetCacheForTesting } = await import("../manifest.js");
 
 // ── Test Setup ──────────────────────────────────────────────────────────────────
 
@@ -90,12 +91,15 @@ describe("cmdList integration", () => {
  return consoleMocks.error.mock.calls.map((c: any[]) => c.join(" ")).join("\n");
  }
 
- beforeEach(() => {
+
+ beforeEach(async () => {
  testDir = join(tmpdir(), `spawn-cmdlist-test-${Date.now()}-${Math.random()}`);
  mkdirSync(testDir, { recursive: true });
 
  originalEnv = { ...process.env };
  process.env.SPAWN_HOME = testDir;
+ // Isolate disk cache so tests don't read/write the real ~/.cache/spawn
+ process.env.XDG_CACHE_HOME = join(testDir, "cache");
 
  consoleMocks = createConsoleMocks();
  mockLogError.mockClear();
@@ -106,6 +110,15 @@ describe("cmdList integration", () => {
  mockSpinnerStop.mockClear();
 
  originalFetch = global.fetch;
+
+ // Prime the manifest in-memory cache with mock data so tests don't
+ // depend on network availability or stale values from other test files.
+ global.fetch = mock(() =>
+ Promise.resolve({ ok: true, json: async () => mockManifest }) as any
+ );
+ await loadManifest(true);
+ global.fetch = originalFetch;
+
  processExitSpy = spyOn(process, "exit").mockImplementation((() => {
  throw new Error("process.exit");
  }) as any);
@@ -258,7 +271,8 @@ describe("cmdList integration", () => {
  it("should fall back to raw keys when manifest is unavailable", async () => {
  writeHistory(sampleRecords);
 
- // Mock fetch to fail
+ // Clear in-memory cache and mock fetch to fail
+ _resetCacheForTesting();
  global.fetch = mock(() => Promise.reject(new Error("Network error")));
 
  await cmdList();

cli/src/__tests__/list-display.test.ts

@@ -32,20 +32,26 @@ function formatTimestamp(iso: string): string {
  }
 }
 
-// ── Exact replica of parseListFilters from index.ts lines 303-316 ───────────
+// ── Exact replica of parseListFilters from index.ts ─────────────────────────
 
 function parseListFilters(args: string[]): { agentFilter?: string; cloudFilter?: string } {
  let agentFilter: string | undefined;
  let cloudFilter: string | undefined;
+ const positional: string[] = [];
  for (let i = 0; i < args.length; i++) {
- if (args[i] === "-a" && args[i + 1] && !args[i + 1].startsWith("-")) {
+ if ((args[i] === "-a" || args[i] === "--agent") && args[i + 1] && !args[i + 1].startsWith("-")) {
  agentFilter = args[i + 1];
  i++;
- } else if (args[i] === "-c" && args[i + 1] && !args[i + 1].startsWith("-")) {
+ } else if ((args[i] === "-c" || args[i] === "--cloud") && args[i + 1] && !args[i + 1].startsWith("-")) {
  cloudFilter = args[i + 1];
  i++;
+ } else if (!args[i].startsWith("-")) {
+ positional.push(args[i]);
  }
  }
+ if (!agentFilter && !cloudFilter && positional.length > 0) {
+ agentFilter = positional[0];
+ }
  return { agentFilter, cloudFilter };
 }
 
@@ -205,9 +211,9 @@ describe("parseListFilters", () => {
  expect(result.cloudFilter).toBeUndefined();
  });
 
- it("should return no filters for unrelated args", () => {
- const result = parseListFilters(["list", "extra"]);
- expect(result.agentFilter).toBeUndefined();
+ it("should use first positional arg as agent filter", () => {
+ const result = parseListFilters(["claude"]);
+ expect(result.agentFilter).toBe("claude");
  expect(result.cloudFilter).toBeUndefined();
  });
 
@@ -246,11 +252,10 @@ describe("parseListFilters", () => {
  expect(result.cloudFilter).toBe("sprite");
  });
 
- it("should not confuse -a and --agent or -c and --cloud", () => {
- // Only short flags -a and -c are supported
+ it("should support --agent and --cloud long flags", () => {
  const result = parseListFilters(["--agent", "claude", "--cloud", "sprite"]);
- expect(result.agentFilter).toBeUndefined();
- expect(result.cloudFilter).toBeUndefined();
+ expect(result.agentFilter).toBe("claude");
+ expect(result.cloudFilter).toBe("sprite");
  });
 
  it("should handle value with hyphens (e.g., agent name with hyphen)", () => {
@@ -263,6 +268,30 @@ describe("parseListFilters", () => {
  expect(result.agentFilter).toBe("x");
  expect(result.cloudFilter).toBe("y");
  });
+
+ it("should not use positional arg when -a flag is present", () => {
+ const result = parseListFilters(["-a", "aider", "extra"]);
+ expect(result.agentFilter).toBe("aider");
+ expect(result.cloudFilter).toBeUndefined();
+ });
+
+ it("should not use positional arg when -c flag is present", () => {
+ const result = parseListFilters(["-c", "sprite", "extra"]);
+ expect(result.agentFilter).toBeUndefined();
+ expect(result.cloudFilter).toBe("sprite");
+ });
+
+ it("should return no filters for empty args", () => {
+ const result = parseListFilters([]);
+ expect(result.agentFilter).toBeUndefined();
+ expect(result.cloudFilter).toBeUndefined();
+ });
+
+ it("should support mixing --agent long flag with -c short flag", () => {
+ const result = parseListFilters(["--agent", "claude", "-c", "hetzner"]);
+ expect(result.agentFilter).toBe("claude");
+ expect(result.cloudFilter).toBe("hetzner");
+ });
  });
 });
 

cli/src/commands.ts

@@ -1257,8 +1257,9 @@ ${pc.bold("USAGE")}
  spawn <agent> Show available clouds for agent
  spawn <cloud> Show available agents for cloud
  spawn list Browse and rerun previous spawns
- spawn list -a <agent> Filter spawn history by agent
- spawn list -c <cloud> Filter spawn history by cloud
+ spawn list <filter> Filter history by agent or cloud name
+ spawn list -a <agent> Filter spawn history by agent (or --agent)
+ spawn list -c <cloud> Filter spawn history by cloud (or --cloud)
  Aliases: ls, history
  spawn matrix Full availability matrix (alias: m)
  spawn agents List all agents with descriptions
@@ -1280,6 +1281,7 @@ ${pc.bold("EXAMPLES")}
  spawn claude ${pc.dim("# Show which clouds support Claude")}
  spawn hetzner ${pc.dim("# Show which agents run on Hetzner")}
  spawn list ${pc.dim("# Browse history and pick one to rerun")}
+ spawn list claude ${pc.dim("# Filter history by agent name")}
  spawn matrix ${pc.dim("# See the full agent x cloud matrix")}
 
 ${pc.bold("AUTHENTICATION")}

cli/src/index.ts

@@ -63,7 +63,7 @@ const KNOWN_FLAGS = new Set([
  "--version", "-v", "-V",
  "--prompt", "-p", "--prompt-file", "-f",
  "--dry-run", "-n",
- "-a", "-c",
+ "-a", "-c", "--agent", "--cloud",
 ]);
 
 /** Check for unknown flags and show an actionable error */
@@ -293,29 +293,39 @@ function warnExtraArgs(filteredArgs: string[], maxExpected: number): void {
  }
 }
 
-/** Parse -a <agent> and -c <cloud> filter flags from args */
+/** Parse -a/--agent <agent> and -c/--cloud <cloud> filter flags from args.
+ * Also accepts a bare positional arg as a filter (e.g. "spawn list claude"). */
 function parseListFilters(args: string[]): { agentFilter?: string; cloudFilter?: string } {
  let agentFilter: string | undefined;
  let cloudFilter: string | undefined;
+ const positional: string[] = [];
  for (let i = 0; i < args.length; i++) {
- if (args[i] === "-a") {
+ if (args[i] === "-a" || args[i] === "--agent") {
  if (!args[i + 1] || args[i + 1].startsWith("-")) {
- console.error(pc.red(`Error: ${pc.bold("-a")} requires an agent name`));
+ console.error(pc.red(`Error: ${pc.bold(args[i])} requires an agent name`));
  console.error(`\nUsage: ${pc.cyan("spawn list -a <agent>")}`);
  process.exit(1);
  }
  agentFilter = args[i + 1];
  i++;
- } else if (args[i] === "-c") {
+ } else if (args[i] === "-c" || args[i] === "--cloud") {
  if (!args[i + 1] || args[i + 1].startsWith("-")) {
- console.error(pc.red(`Error: ${pc.bold("-c")} requires a cloud name`));
+ console.error(pc.red(`Error: ${pc.bold(args[i])} requires a cloud name`));
  console.error(`\nUsage: ${pc.cyan("spawn list -c <cloud>")}`);
  process.exit(1);
  }
  cloudFilter = args[i + 1];
  i++;
+ } else if (!args[i].startsWith("-")) {
+ positional.push(args[i]);
  }
  }
+
+ // Support bare positional filter: "spawn list claude" or "spawn list hetzner"
+ if (!agentFilter && !cloudFilter && positional.length > 0) {
+ agentFilter = positional[0];
+ }
+
  return { agentFilter, cloudFilter };
 }
 

cli/src/manifest.ts

@@ -208,4 +208,9 @@ export function countImplemented(m: Manifest): number {
  return count;
 }
 
+/** Clear the in-memory manifest cache (for testing only) */
+export function _resetCacheForTesting(): void {
+ _cached = null;
+}
+
 export { RAW_BASE, REPO, CACHE_DIR };

cli/package.json

@@ -1,6 +1,6 @@
 {
  "name": "@openrouter/spawn",
- "version": "0.2.57",
+ "version": "0.2.58",
  "type": "module",
  "bin": {
  "spawn": "cli.js"

cli/src/__tests__/cmdlist-integration.test.ts

@@ -64,6 +64,7 @@ mock.module("@clack/prompts", () => ({
 
 // Import after mock setup
 const { cmdList, resolveDisplayName } = await import("../commands.js");
+const { loadManifest, _resetCacheForTesting } = await import("../manifest.js");
 
 // ── Test Setup ──────────────────────────────────────────────────────────────────
 
@@ -90,12 +91,15 @@ describe("cmdList integration", () => {
  return consoleMocks.error.mock.calls.map((c: any[]) => c.join(" ")).join("\n");
  }
 
- beforeEach(() => {
+
+ beforeEach(async () => {
  testDir = join(tmpdir(), `spawn-cmdlist-test-${Date.now()}-${Math.random()}`);
  mkdirSync(testDir, { recursive: true });
 
  originalEnv = { ...process.env };
  process.env.SPAWN_HOME = testDir;
+ // Isolate disk cache so tests don't read/write the real ~/.cache/spawn
+ process.env.XDG_CACHE_HOME = join(testDir, "cache");
 
  consoleMocks = createConsoleMocks();
  mockLogError.mockClear();
@@ -106,6 +110,15 @@ describe("cmdList integration", () => {
  mockSpinnerStop.mockClear();
 
  originalFetch = global.fetch;
+
+ // Prime the manifest in-memory cache with mock data so tests don't
+ // depend on network availability or stale values from other test files.
+ global.fetch = mock(() =>
+ Promise.resolve({ ok: true, json: async () => mockManifest }) as any
+ );
+ await loadManifest(true);
+ global.fetch = originalFetch;
+
  processExitSpy = spyOn(process, "exit").mockImplementation((() => {
  throw new Error("process.exit");
  }) as any);
@@ -258,7 +271,8 @@ describe("cmdList integration", () => {
  it("should fall back to raw keys when manifest is unavailable", async () => {
  writeHistory(sampleRecords);
 
- // Mock fetch to fail
+ // Clear in-memory cache and mock fetch to fail
+ _resetCacheForTesting();
  global.fetch = mock(() => Promise.reject(new Error("Network error")));
 
  await cmdList();

cli/src/__tests__/list-display.test.ts

@@ -32,20 +32,26 @@ function formatTimestamp(iso: string): string {
  }
 }
 
-// ── Exact replica of parseListFilters from index.ts lines 303-316 ───────────
+// ── Exact replica of parseListFilters from index.ts ─────────────────────────
 
 function parseListFilters(args: string[]): { agentFilter?: string; cloudFilter?: string } {
  let agentFilter: string | undefined;
  let cloudFilter: string | undefined;
+ const positional: string[] = [];
  for (let i = 0; i < args.length; i++) {
- if (args[i] === "-a" && args[i + 1] && !args[i + 1].startsWith("-")) {
+ if ((args[i] === "-a" || args[i] === "--agent") && args[i + 1] && !args[i + 1].startsWith("-")) {
  agentFilter = args[i + 1];
  i++;
- } else if (args[i] === "-c" && args[i + 1] && !args[i + 1].startsWith("-")) {
+ } else if ((args[i] === "-c" || args[i] === "--cloud") && args[i + 1] && !args[i + 1].startsWith("-")) {
  cloudFilter = args[i + 1];
  i++;
+ } else if (!args[i].startsWith("-")) {
+ positional.push(args[i]);
  }
  }
+ if (!agentFilter && !cloudFilter && positional.length > 0) {
+ agentFilter = positional[0];
+ }
  return { agentFilter, cloudFilter };
 }
 
@@ -205,9 +211,9 @@ describe("parseListFilters", () => {
  expect(result.cloudFilter).toBeUndefined();
  });
 
- it("should return no filters for unrelated args", () => {
- const result = parseListFilters(["list", "extra"]);
- expect(result.agentFilter).toBeUndefined();
+ it("should use first positional arg as agent filter", () => {
+ const result = parseListFilters(["claude"]);
+ expect(result.agentFilter).toBe("claude");
  expect(result.cloudFilter).toBeUndefined();
  });
 
@@ -246,11 +252,10 @@ describe("parseListFilters", () => {
  expect(result.cloudFilter).toBe("sprite");
  });
 
- it("should not confuse -a and --agent or -c and --cloud", () => {
- // Only short flags -a and -c are supported
+ it("should support --agent and --cloud long flags", () => {
  const result = parseListFilters(["--agent", "claude", "--cloud", "sprite"]);
- expect(result.agentFilter).toBeUndefined();
- expect(result.cloudFilter).toBeUndefined();
+ expect(result.agentFilter).toBe("claude");
+ expect(result.cloudFilter).toBe("sprite");
  });
 
  it("should handle value with hyphens (e.g., agent name with hyphen)", () => {
@@ -263,6 +268,30 @@ describe("parseListFilters", () => {
  expect(result.agentFilter).toBe("x");
  expect(result.cloudFilter).toBe("y");
  });
+
+ it("should not use positional arg when -a flag is present", () => {
+ const result = parseListFilters(["-a", "aider", "extra"]);
+ expect(result.agentFilter).toBe("aider");
+ expect(result.cloudFilter).toBeUndefined();
+ });
+
+ it("should not use positional arg when -c flag is present", () => {
+ const result = parseListFilters(["-c", "sprite", "extra"]);
+ expect(result.agentFilter).toBeUndefined();
+ expect(result.cloudFilter).toBe("sprite");
+ });
+
+ it("should return no filters for empty args", () => {
+ const result = parseListFilters([]);
+ expect(result.agentFilter).toBeUndefined();
+ expect(result.cloudFilter).toBeUndefined();
+ });
+
+ it("should support mixing --agent long flag with -c short flag", () => {
+ const result = parseListFilters(["--agent", "claude", "-c", "hetzner"]);
+ expect(result.agentFilter).toBe("claude");
+ expect(result.cloudFilter).toBe("hetzner");
+ });
  });
 });
 

cli/src/commands.ts

@@ -1257,8 +1257,9 @@ ${pc.bold("USAGE")}
  spawn <agent> Show available clouds for agent
  spawn <cloud> Show available agents for cloud
  spawn list Browse and rerun previous spawns
- spawn list -a <agent> Filter spawn history by agent
- spawn list -c <cloud> Filter spawn history by cloud
+ spawn list <filter> Filter history by agent or cloud name
+ spawn list -a <agent> Filter spawn history by agent (or --agent)
+ spawn list -c <cloud> Filter spawn history by cloud (or --cloud)
  Aliases: ls, history
  spawn matrix Full availability matrix (alias: m)
  spawn agents List all agents with descriptions
@@ -1280,6 +1281,7 @@ ${pc.bold("EXAMPLES")}
  spawn claude ${pc.dim("# Show which clouds support Claude")}
  spawn hetzner ${pc.dim("# Show which agents run on Hetzner")}
  spawn list ${pc.dim("# Browse history and pick one to rerun")}
+ spawn list claude ${pc.dim("# Filter history by agent name")}
  spawn matrix ${pc.dim("# See the full agent x cloud matrix")}
 
 ${pc.bold("AUTHENTICATION")}

cli/src/index.ts

@@ -63,7 +63,7 @@ const KNOWN_FLAGS = new Set([
  "--version", "-v", "-V",
  "--prompt", "-p", "--prompt-file", "-f",
  "--dry-run", "-n",
- "-a", "-c",
+ "-a", "-c", "--agent", "--cloud",
 ]);
 
 /** Check for unknown flags and show an actionable error */
@@ -293,29 +293,39 @@ function warnExtraArgs(filteredArgs: string[], maxExpected: number): void {
  }
 }
 
-/** Parse -a <agent> and -c <cloud> filter flags from args */
+/** Parse -a/--agent <agent> and -c/--cloud <cloud> filter flags from args.
+ * Also accepts a bare positional arg as a filter (e.g. "spawn list claude"). */
 function parseListFilters(args: string[]): { agentFilter?: string; cloudFilter?: string } {
  let agentFilter: string | undefined;
  let cloudFilter: string | undefined;
+ const positional: string[] = [];
  for (let i = 0; i < args.length; i++) {
- if (args[i] === "-a") {
+ if (args[i] === "-a" || args[i] === "--agent") {
  if (!args[i + 1] || args[i + 1].startsWith("-")) {
- console.error(pc.red(`Error: ${pc.bold("-a")} requires an agent name`));
+ console.error(pc.red(`Error: ${pc.bold(args[i])} requires an agent name`));
  console.error(`\nUsage: ${pc.cyan("spawn list -a <agent>")}`);
  process.exit(1);
  }
  agentFilter = args[i + 1];
  i++;
- } else if (args[i] === "-c") {
+ } else if (args[i] === "-c" || args[i] === "--cloud") {
  if (!args[i + 1] || args[i + 1].startsWith("-")) {
- console.error(pc.red(`Error: ${pc.bold("-c")} requires a cloud name`));
+ console.error(pc.red(`Error: ${pc.bold(args[i])} requires a cloud name`));
  console.error(`\nUsage: ${pc.cyan("spawn list -c <cloud>")}`);
  process.exit(1);
  }
  cloudFilter = args[i + 1];
  i++;
+ } else if (!args[i].startsWith("-")) {
+ positional.push(args[i]);
  }
  }
+
+ // Support bare positional filter: "spawn list claude" or "spawn list hetzner"
+ if (!agentFilter && !cloudFilter && positional.length > 0) {
+ agentFilter = positional[0];
+ }
+
  return { agentFilter, cloudFilter };
 }
 

cli/src/manifest.ts

@@ -208,4 +208,9 @@ export function countImplemented(m: Manifest): number {
  return count;
 }
 
+/** Clear the in-memory manifest cache (for testing only) */
+export function _resetCacheForTesting(): void {
+ _cached = null;
+}
+
 export { RAW_BASE, REPO, CACHE_DIR };

cli/package.json

@@ -1,6 +1,6 @@
 {
  "name": "@openrouter/spawn",
- "version": "0.2.57",
+ "version": "0.2.58",
  "type": "module",
  "bin": {
  "spawn": "cli.js"

cli/src/__tests__/cmdlist-integration.test.ts

@@ -64,6 +64,7 @@ mock.module("@clack/prompts", () => ({
 
 // Import after mock setup
 const { cmdList, resolveDisplayName } = await import("../commands.js");
+const { loadManifest, _resetCacheForTesting } = await import("../manifest.js");
 
 // ── Test Setup ──────────────────────────────────────────────────────────────────
 
@@ -90,12 +91,15 @@ describe("cmdList integration", () => {
  return consoleMocks.error.mock.calls.map((c: any[]) => c.join(" ")).join("\n");
  }
 
- beforeEach(() => {
+
+ beforeEach(async () => {
  testDir = join(tmpdir(), `spawn-cmdlist-test-${Date.now()}-${Math.random()}`);
  mkdirSync(testDir, { recursive: true });
 
  originalEnv = { ...process.env };
  process.env.SPAWN_HOME = testDir;
+ // Isolate disk cache so tests don't read/write the real ~/.cache/spawn
+ process.env.XDG_CACHE_HOME = join(testDir, "cache");
 
  consoleMocks = createConsoleMocks();
  mockLogError.mockClear();
@@ -106,6 +110,15 @@ describe("cmdList integration", () => {
  mockSpinnerStop.mockClear();
 
  originalFetch = global.fetch;
+
+ // Prime the manifest in-memory cache with mock data so tests don't
+ // depend on network availability or stale values from other test files.
+ global.fetch = mock(() =>
+ Promise.resolve({ ok: true, json: async () => mockManifest }) as any
+ );
+ await loadManifest(true);
+ global.fetch = originalFetch;
+
  processExitSpy = spyOn(process, "exit").mockImplementation((() => {
  throw new Error("process.exit");
  }) as any);
@@ -258,7 +271,8 @@ describe("cmdList integration", () => {
  it("should fall back to raw keys when manifest is unavailable", async () => {
  writeHistory(sampleRecords);
 
- // Mock fetch to fail
+ // Clear in-memory cache and mock fetch to fail
+ _resetCacheForTesting();
  global.fetch = mock(() => Promise.reject(new Error("Network error")));
 
  await cmdList();

cli/src/__tests__/list-display.test.ts

@@ -32,20 +32,26 @@ function formatTimestamp(iso: string): string {
  }
 }
 
-// ── Exact replica of parseListFilters from index.ts lines 303-316 ───────────
+// ── Exact replica of parseListFilters from index.ts ─────────────────────────
 
 function parseListFilters(args: string[]): { agentFilter?: string; cloudFilter?: string } {
  let agentFilter: string | undefined;
  let cloudFilter: string | undefined;
+ const positional: string[] = [];
  for (let i = 0; i < args.length; i++) {
- if (args[i] === "-a" && args[i + 1] && !args[i + 1].startsWith("-")) {
+ if ((args[i] === "-a" || args[i] === "--agent") && args[i + 1] && !args[i + 1].startsWith("-")) {
  agentFilter = args[i + 1];
  i++;
- } else if (args[i] === "-c" && args[i + 1] && !args[i + 1].startsWith("-")) {
+ } else if ((args[i] === "-c" || args[i] === "--cloud") && args[i + 1] && !args[i + 1].startsWith("-")) {
  cloudFilter = args[i + 1];
  i++;
+ } else if (!args[i].startsWith("-")) {
+ positional.push(args[i]);
  }
  }
+ if (!agentFilter && !cloudFilter && positional.length > 0) {
+ agentFilter = positional[0];
+ }
  return { agentFilter, cloudFilter };
 }
 
@@ -205,9 +211,9 @@ describe("parseListFilters", () => {
  expect(result.cloudFilter).toBeUndefined();
  });
 
- it("should return no filters for unrelated args", () => {
- const result = parseListFilters(["list", "extra"]);
- expect(result.agentFilter).toBeUndefined();
+ it("should use first positional arg as agent filter", () => {
+ const result = parseListFilters(["claude"]);
+ expect(result.agentFilter).toBe("claude");
  expect(result.cloudFilter).toBeUndefined();
  });
 
@@ -246,11 +252,10 @@ describe("parseListFilters", () => {
  expect(result.cloudFilter).toBe("sprite");
  });
 
- it("should not confuse -a and --agent or -c and --cloud", () => {
- // Only short flags -a and -c are supported
+ it("should support --agent and --cloud long flags", () => {
  const result = parseListFilters(["--agent", "claude", "--cloud", "sprite"]);
- expect(result.agentFilter).toBeUndefined();
- expect(result.cloudFilter).toBeUndefined();
+ expect(result.agentFilter).toBe("claude");
+ expect(result.cloudFilter).toBe("sprite");
  });
 
  it("should handle value with hyphens (e.g., agent name with hyphen)", () => {
@@ -263,6 +268,30 @@ describe("parseListFilters", () => {
  expect(result.agentFilter).toBe("x");
  expect(result.cloudFilter).toBe("y");
  });
+
+ it("should not use positional arg when -a flag is present", () => {
+ const result = parseListFilters(["-a", "aider", "extra"]);
+ expect(result.agentFilter).toBe("aider");
+ expect(result.cloudFilter).toBeUndefined();
+ });
+
+ it("should not use positional arg when -c flag is present", () => {
+ const result = parseListFilters(["-c", "sprite", "extra"]);
+ expect(result.agentFilter).toBeUndefined();
+ expect(result.cloudFilter).toBe("sprite");
+ });
+
+ it("should return no filters for empty args", () => {
+ const result = parseListFilters([]);
+ expect(result.agentFilter).toBeUndefined();
+ expect(result.cloudFilter).toBeUndefined();
+ });
+
+ it("should support mixing --agent long flag with -c short flag", () => {
+ const result = parseListFilters(["--agent", "claude", "-c", "hetzner"]);
+ expect(result.agentFilter).toBe("claude");
+ expect(result.cloudFilter).toBe("hetzner");
+ });
  });
 });
 

cli/src/commands.ts

@@ -1257,8 +1257,9 @@ ${pc.bold("USAGE")}
  spawn <agent> Show available clouds for agent
  spawn <cloud> Show available agents for cloud
  spawn list Browse and rerun previous spawns
- spawn list -a <agent> Filter spawn history by agent
- spawn list -c <cloud> Filter spawn history by cloud
+ spawn list <filter> Filter history by agent or cloud name
+ spawn list -a <agent> Filter spawn history by agent (or --agent)
+ spawn list -c <cloud> Filter spawn history by cloud (or --cloud)
  Aliases: ls, history
  spawn matrix Full availability matrix (alias: m)
  spawn agents List all agents with descriptions
@@ -1280,6 +1281,7 @@ ${pc.bold("EXAMPLES")}
  spawn claude ${pc.dim("# Show which clouds support Claude")}
  spawn hetzner ${pc.dim("# Show which agents run on Hetzner")}
  spawn list ${pc.dim("# Browse history and pick one to rerun")}
+ spawn list claude ${pc.dim("# Filter history by agent name")}
  spawn matrix ${pc.dim("# See the full agent x cloud matrix")}
 
 ${pc.bold("AUTHENTICATION")}

cli/src/index.ts

@@ -63,7 +63,7 @@ const KNOWN_FLAGS = new Set([
  "--version", "-v", "-V",
  "--prompt", "-p", "--prompt-file", "-f",
  "--dry-run", "-n",
- "-a", "-c",
+ "-a", "-c", "--agent", "--cloud",
 ]);
 
 /** Check for unknown flags and show an actionable error */
@@ -293,29 +293,39 @@ function warnExtraArgs(filteredArgs: string[], maxExpected: number): void {
  }
 }
 
-/** Parse -a <agent> and -c <cloud> filter flags from args */
+/** Parse -a/--agent <agent> and -c/--cloud <cloud> filter flags from args.
+ * Also accepts a bare positional arg as a filter (e.g. "spawn list claude"). */
 function parseListFilters(args: string[]): { agentFilter?: string; cloudFilter?: string } {
  let agentFilter: string | undefined;
  let cloudFilter: string | undefined;
+ const positional: string[] = [];
  for (let i = 0; i < args.length; i++) {
- if (args[i] === "-a") {
+ if (args[i] === "-a" || args[i] === "--agent") {
  if (!args[i + 1] || args[i + 1].startsWith("-")) {
- console.error(pc.red(`Error: ${pc.bold("-a")} requires an agent name`));
+ console.error(pc.red(`Error: ${pc.bold(args[i])} requires an agent name`));
  console.error(`\nUsage: ${pc.cyan("spawn list -a <agent>")}`);
  process.exit(1);
  }
  agentFilter = args[i + 1];
  i++;
- } else if (args[i] === "-c") {
+ } else if (args[i] === "-c" || args[i] === "--cloud") {
  if (!args[i + 1] || args[i + 1].startsWith("-")) {
- console.error(pc.red(`Error: ${pc.bold("-c")} requires a cloud name`));
+ console.error(pc.red(`Error: ${pc.bold(args[i])} requires a cloud name`));
  console.error(`\nUsage: ${pc.cyan("spawn list -c <cloud>")}`);
  process.exit(1);
  }
  cloudFilter = args[i + 1];
  i++;
+ } else if (!args[i].startsWith("-")) {
+ positional.push(args[i]);
  }
  }
+
+ // Support bare positional filter: "spawn list claude" or "spawn list hetzner"
+ if (!agentFilter && !cloudFilter && positional.length > 0) {
+ agentFilter = positional[0];
+ }
+
  return { agentFilter, cloudFilter };
 }
 

cli/src/manifest.ts

@@ -208,4 +208,9 @@ export function countImplemented(m: Manifest): number {
  return count;
 }
 
+/** Clear the in-memory manifest cache (for testing only) */
+export function _resetCacheForTesting(): void {
+ _cached = null;
+}
+
 export { RAW_BASE, REPO, CACHE_DIR };