fix(workboard): hide archived cards in CLI list by default

ZengWen-DT · claude · ZengWen-DT · commit 9e5e3bdc33a7 · 2026-06-18T19:19:45.000+08:00
The `openclaw workboard list` CLI printed soft-archived cards, while the
`workboard_list` agent tool and the `/workboard list` command both hide
cards with `metadata.archivedAt` set unless archives are requested. Users
who archived cards still saw them in CLI output and assumed archive failed.

Filter archived cards by default in the CLI list handler and add an
`--include-archived` flag mirroring the tool's `includeArchived` option, so
all three list surfaces share one default. Docs updated to match.

Co-Authored-By: Claude Opus 4.8 &lt;noreply@anthropic.com&gt;
diff --git a/docs/cli/workboard.md b/docs/cli/workboard.md
@@ -22,7 +22,7 @@ openclaw gateway restart
 ## Usage
 
 ```bash
-openclaw workboard list [--board <id>] [--status <status>] [--json]
+openclaw workboard list [--board <id>] [--status <status>] [--include-archived] [--json]
 openclaw workboard create <title...> [--notes <text>] [--status <status>] [--priority <priority>] [--agent <id>] [--board <id>] [--labels <items>] [--json]
 openclaw workboard show <id> [--json]
 openclaw workboard dispatch [--url <url>] [--token <token>] [--timeout <ms>] [--json]
@@ -50,11 +50,16 @@ Columns are id prefix, status, priority, board id, optional agent id, and title.
 
 Flags:
 
-| Flag                | Purpose                                  |
-| ------------------- | ---------------------------------------- |
-| `--board <id>`      | Limit results to one board namespace     |
-| `--status <status>` | Limit results to one Workboard status    |
-| `--json`            | Print the full card list as machine JSON |
+| Flag                 | Purpose                                                       |
+| -------------------- | ------------------------------------------------------------- |
+| `--board <id>`       | Limit results to one board namespace                          |
+| `--status <status>`  | Limit results to one Workboard status                         |
+| `--include-archived` | Include archived cards (hidden by default, matching the tool) |
+| `--json`             | Print the full card list as machine JSON                      |
+
+Archived cards are hidden by default so the CLI matches the `workboard_list`
+agent tool and the `/workboard list` command. Pass `--include-archived` to show
+them.
 
 ## `create`
 
diff --git a/extensions/workboard/src/cli.test.ts b/extensions/workboard/src/cli.test.ts
@@ -106,6 +106,28 @@ describe("registerWorkboardCli", () => {
     expect(showOutput).toContain("[redacted]");
   });
 
+  it("hides archived cards by default and reveals them with --include-archived", async () => {
+    const store = new WorkboardStore(createMemoryStore());
+    const active = await store.create({ title: "Active card" });
+    const archived = await store.create({ title: "Archived card" });
+    await store.archive(archived.id, true);
+    const program = createProgram(store);
+
+    const defaultOutput = await captureStdout(async () => {
+      await program.parseAsync(["workboard", "list", "--json"], { from: "user" });
+    });
+    const includeOutput = await captureStdout(async () => {
+      await program.parseAsync(["workboard", "list", "--include-archived", "--json"], {
+        from: "user",
+      });
+    });
+
+    expect(defaultOutput).toContain(active.id);
+    expect(defaultOutput).not.toContain(archived.id);
+    expect(includeOutput).toContain(active.id);
+    expect(includeOutput).toContain(archived.id);
+  });
+
   it("does not fall back to local dispatch for explicit gateway targets", async () => {
     const store = new WorkboardStore(createMemoryStore());
     const card = await store.create({ title: "Remote target", status: "ready" });
diff --git a/extensions/workboard/src/cli.ts b/extensions/workboard/src/cli.ts
@@ -130,14 +130,27 @@ export function registerWorkboardCli(params: { program: Command; store: Workboar
     .description("List Workboard cards")
     .option("--board <id>", "Board id")
     .option("--status <status>", "Filter by status")
+    .option("--include-archived", "Include archived cards (default false)")
     .option("--json", "Print JSON", false)
-    .action(async (options: JsonOptions & { board?: string; status?: string }) => {
-      let cards = await params.store.list({ boardId: options.board });
-      if (options.status) {
-        cards = cards.filter((card) => card.status === options.status);
-      }
-      writeCards(cards, options);
-    });
+    .action(
+      async (
+        options: JsonOptions & {
+          board?: string;
+          status?: string;
+          includeArchived?: boolean;
+        },
+      ) => {
+        // Hide archived cards by default to match the workboard_list tool and the
+        // /workboard list command; --include-archived restores the full set.
+        let cards = (await params.store.list({ boardId: options.board })).filter(
+          (card) => options.includeArchived === true || !card.metadata?.archivedAt,
+        );
+        if (options.status) {
+          cards = cards.filter((card) => card.status === options.status);
+        }
+        writeCards(cards, options);
+      },
+    );
 
   workboard
     .command("create")
