planka

Interact with a self-hosted Planka instance. Planka is a Trello-like kanban board.

See README.md for setup instructions, usage examples, and advanced use cases.

Setup

Required environment variables:

• PLANKA_URL — Base URL (e.g. https://planka.example.com)
• PLANKA_API_KEY — API key (generated in Planka UI → User Settings)

These can be set in:

1. The current project's .env file (most common)
2. ~/.env (global, for cross-project use)
3. Shell environment (e.g. ~/.bashrc or ~/.zshrc)

API

Base path: $PLANKA_URL/api/

Auth header: X-Api-Key: $PLANKA_API_KEY

Full OpenAPI spec: https://plankanban.github.io/planka/swagger-ui/swagger.json

CRITICAL: How to look up endpoints

1. NEVER guess endpoints. Always look them up first.
2. Do NOT trust WebFetch summaries of the swagger.json. WebFetch summarizes content and frequently returns incorrect/shortened paths (e.g. /card-labels instead of /cards/{cardId}/card-labels).
3. Instead, fetch the raw JSON and parse it yourself:

   curl -sL https://plankanban.github.io/planka/swagger-ui/swagger.json | python3 -c "
   import json, sys
   spec = json.load(sys.stdin)
   for path, methods in spec.get('paths', {}).items():
       for method in methods:
           if method in ('get','post','put','patch','delete'):
               print(f'{method.upper()} {path}')
   " | grep -i "SEARCH_TERM"
   

4. On 404 errors: Do NOT retry the same endpoint. Immediately fetch the spec and find the correct path. The server version may differ from the spec -- try path variations (e.g. /cards/{id}/card-labels vs /card-labels).

Key Concepts

• Hierarchy: Project → Board → List → Card → Task List → Task
• Responses: {"item": {...}} for single, {"items": [...]} for collections, related data in "included"
• Positioning: Numeric, multiples of 65536. Lower = higher on the board.
• Colors (for lists/labels): e.g. dark-granite, lagoon-blue, orange-peel, bright-moss, berry-red, light-mud, midnight-blue, light-cocoa, summer-sky, pumpkin-orange

How to Use

The user can talk naturally or use optional shorthand commands:

These are shortcuts — the user can also just describe what they want freely: "create a card for Feature X", "move Bug Y to Done", "set up a new board with labels", etc.

Understand the intent, look up the right endpoints from the OpenAPI spec if needed, and execute.

Finding boards: Never hardcode IDs. Always list projects first, find boards from the included data, and match by name.

Null safety: Many Planka fields can be None/null — name, description, color, position, etc. Always use or "", or 0, (x or "").strip() patterns in Python code. Never call methods on potentially null values without guarding.

Display formatting:

• overview: Show projects as headers with boards as bullet points. Include board card count.
• board <name>: Show each list as a section with its cards listed below. For each card show: name, labels (as colored badges), task progress (e.g. 3/5), and description preview if available. Use markdown formatting — headers for lists, bullet points for cards. Skip empty/unnamed system lists (archive, trash).

Always:

• Load env vars before API calls: source .env 2>/dev/null; source ~/.env 2>/dev/null — tries project .env first, then global ~/.env, silently skips if missing
• Use curl -sL (silent + follow redirects)
• Use python3 -c "import json; ..." for safe JSON encoding
• Ask the user when something is ambiguous (e.g. multiple boards/projects)
• Always confirm before executing: describe what you're about to do (e.g. "I'll create a card 'Dark Mode' in Backlog with labels Feature, UI") and wait for the user to approve before making any API calls. This applies to all write operations — create, update, move, delete.