pcli/openspec/changes/archive/2026-02-09-planka-cli-v1/proposal.md

Why

Planka is a self-hosted Kanban board application with a REST API, but there is no CLI tool to interact with it programmatically. AI agents and automated workflows need a simple, scriptable interface to manage cards, tasks, and comments without using the web UI. A single Go binary (pcli) provides a lightweight, dependency-free tool that can be dropped into any CI/CD pipeline or agent environment.

What Changes

• New Go binary pcli providing a Cobra-based CLI to interact with the Planka API
• Nested command structure: pcli <resource> <action> [args] [flags]
• Authentication via bearer token from environment variables (PLANKA_URL, PLANKA_TOKEN) — no login flow, no on-disk token storage
• JSON output by default with consistent {"data": ..., "error": null} response envelope
• Optional --format=table for human-readable output
• Read-only access to projects and boards
• Full CRUD for cards, comments, task lists, tasks, and labels
• Card operations: move, duplicate, assign/unassign users, add/remove labels
• Board and card activity log (actions) — read-only
• card list --board <id> enriches responses with listName (resolved from list data)
• Lists treated as an implementation detail — not exposed as top-level commands

Capabilities

New Capabilities

• api-client: HTTP client layer for Planka API — base client with auth, request/response handling, and per-resource methods
• cli-commands: Cobra command tree — project, board, card, comment, task-list, task, label subcommands with flags and argument parsing
• output-formatting: Response envelope and format switching — JSON default, table option, consistent error handling
• card-operations: Card-specific composite operations — move (list + position), duplicate, assign/unassign members, add/remove labels, enriched board-level card listing

Modified Capabilities

None — greenfield project.

Impact

• New repository structure: main.go, cmd/, client/, model/, output/ packages
• Dependencies: Go module github.com/dcgsteve/pcli, Cobra library, standard library HTTP client
• External API: Depends on Planka v2.0 API (OpenAPI 3.0 spec in planka-api.json)
• Environment: Requires PLANKA_URL and PLANKA_TOKEN environment variables at runtime