pcli/openspec/changes/archive/2026-02-11-add-status-command/design.md

Context

pcli is a Cobra-based CLI for the Planka project management API. Commands follow a pcli <resource> <action> pattern (e.g., pcli board get, pcli card list). The client layer already provides ListBoards() (via /api/projects) and GetBoard(id) (via /api/boards/:id), where GetBoard returns the board's lists and cards in the included block. Output is handled by output.Print() which dispatches to JSON envelope or table rendering based on the --format flag.

Goals / Non-Goals

Goals:

• Provide a single top-level pcli status command that summarizes all boards, their lists, and card counts
• Reuse existing client methods with no new API endpoints
• Support both JSON and table output formats via the existing --format flag
• Show open card counts as the primary number, with closed cards noted separately

Non-Goals:

• Concurrent/parallel board fetching (sequential is sufficient for expected board counts)
• Filtering by project, board, or list (this is a full overview command)
• Showing card-level detail (names, assignees, due dates) — that's what card list is for
• Caching or incremental updates

Decisions

1. Top-level command, not a subcommand

The status command will be registered directly on rootCmd, not under board or any other resource group. It's a cross-cutting summary, not a resource operation.

Alternative considered: pcli board status — rejected because the command spans all boards and is conceptually similar to git status as a quick overview.

2. Data aggregation in the command layer

The status command will call ListBoards() then GetBoard(id) for each board, aggregating card counts per list in the command handler. No new client method is needed.

Alternative considered: A dedicated client.GetStatus() method — rejected because there's no single Planka API endpoint for this; the aggregation is purely a CLI concern.

3. New model types for status data

A StatusSummary struct will hold the aggregated data, containing a slice of BoardSummary structs (board name + list summaries), each containing a slice of ListSummary structs (list name, open count, closed count). This gives both JSON and table formatters a clean data structure to work with.

Alternative considered: Reusing existing Board/List types with card slices — rejected because the status output is a derived summary, not raw API data.

4. Table output uses per-board sections

In table format, each board is rendered as a headed section with a list/cards table beneath it. A total board count line appears first. This matches the natural reading pattern for a summary view.

5. JSON output uses the standard envelope

JSON output wraps the StatusSummary in the existing {"data": ..., "error": null} envelope, consistent with all other commands.

Risks / Trade-offs

• N+1 API calls — One ListBoards call plus one GetBoard per board. For typical usage (< 20 boards) this is fine. If it becomes a problem, concurrent fetching can be added later without changing the interface. → Mitigation: defer optimization until needed.
• Stale data between calls — Board state could change between sequential GetBoard calls. → Mitigation: acceptable for a summary view; not a transactional operation.