plnk-cli

Use plnk as the canonical interface to Planka. Do not invent a parallel task API or assume a fixed kanban workflow. Operate through the CLI, prefer machine-readable output, and resolve ambiguity before mutating state.

When to use this skill

Use this skill when the user wants to:

• inspect Planka projects, boards, lists, cards, task lists, tasks, comments, labels, attachments, memberships, or users
• create, update, move, archive, unarchive, or delete Planka resources
• find cards, lists, boards, or labels by name/title
• add comments, tasks, assignees, labels, custom field values, or attachments to cards
• understand or debug plnk command behavior

Core Rules

• Use plnk as the source of truth for Planka operations.
• Prefer --output json for agent work unless the user explicitly asked for table or markdown output.
• IDs are opaque strings. Pass them through exactly as returned.
• Use get for exact ID lookup.
• Use find for name/title lookup.
• find may return multiple results. Do not guess when matches are ambiguous.
• Prefer the narrowest scope possible: --list over --board, --board over --project.
• Read before write when current state is unclear.
• After discovery, perform mutations using IDs, not names.
• Ask before destructive or bulk operations unless the user was already explicit.
• Do not maintain a parallel TODO system unless the user explicitly asks for one.

Resource Hierarchy

All operations are hierarchical.

project
  board
    list
      card
        task list ── task
        comment
        attachment
        custom field group ── custom field ── value
    label
    custom field group ── custom field
  membership
  base custom field group ── custom field   (reusable template)

Implications:

• project find is the only unscoped find.
• board find requires --project.
• list find requires --board.
• card find requires exactly one of --list, --board, or --project.
• tasks and comments live under cards; every task belongs to one of the card's task lists
• labels live under boards
• field-group list requires exactly one of --project, --board, or --card
• field list requires exactly one of --group or --base-group
• custom field values live under cards: card field list|set|clear

Default Operating Procedure

When the user asks to inspect or modify Planka state:

1. Identify the narrowest possible scope.
   • Prefer known IDs if already available.
   • Otherwise resolve names to IDs using find or list.
2. Prefer JSON output.
   • Use --output json for anything the agent needs to read, compare, or pipe.
3. Resolve names before mutation.
   • Find the project, board, list, card, label, or user first.
   • If multiple candidates match, summarize them and ask the user which one they mean.
4. Read current state before writing when context is incomplete.
   • Inspect the current board/list/card/task state before moving or editing if the target is not fully specified.
5. Mutate by ID.
   • Once a target has been identified, use the returned IDs for update, move, archive, delete, label add/remove, assignee add/remove, and similar operations.
6. Confirm destructive or broad actions.
   • Ask before delete, archive, bulk edits, or wide-scope moves unless the user was explicit.
7. Report back with resolved names and IDs when useful.
   • Especially after create/move/find operations or when ambiguity was resolved.

Lists and Workflow

Lists are board-defined and may vary across users, teams, and boards. Do not assume canonical columns.

Never assume that a board has any specific list names such as:

• Backlog
• In Progress
• Review
• Done
• Blocked
• WontDo

When the user expresses workflow intent such as “move this to in progress”, “send this to review”, “put it in backlog”, or “mark this blocked”:

1. inspect the board's actual lists first
2. map the user's intent to an existing list
3. ask for confirmation if multiple lists plausibly match

Auth and Output

Credential precedence:

1. CLI flags: --server, --token
2. Environment: PLANKA_SERVER, PLANKA_TOKEN
3. Config: ~/.config/planka/config.toml

Useful auth checks:

plnk auth status
plnk auth whoami

Prefer JSON output for agent work:

plnk board list --project <projectId> --output json
plnk card find --board <boardId> --title "auth" --output json

JSON envelopes are shaped like:

{"success": true, "data": [...], "meta": {"count": 3}}

and errors like:

{"success": false, "error": {"type": "ResourceNotFound", "message": "..."}}

Important Constraints

• get requires an ID. Never use get with a name.
• find returns collections, including zero or many matches.
• card find selects cards by any combination of --title, --label, --due-after, --due-before, and --closed. Due bounds are strict (<) ISO 8601 or relative-date comparisons; relative dates include now (the current instant), which makes --due-before now the overdue query. Cards without a due date are excluded when a bound is set, and there is no server-side due-date filter — filtering happens over the fetched snapshot. card list accepts the same --due-after / --due-before bounds.
• Lists have a type: active or closed. Moving a card into a closed list marks it closed. Create one with plnk list create --board <id> --name Done --type closed; list list shows a Type column.
• A due query (a card list / card find with a due bound) excludes closed cards by default. Pass --include-closed to keep them. --closed keeps only closed cards. The two flags conflict and exit 2 together. Without a due bound, closed cards are returned as before.
• Custom fields have three surfaces — do not conflate them:
  • plnk field-group — the groups (project-level ones are reusable templates)
  • plnk field — the named slots inside a group
  • plnk card field — the values a card stores
• A card group adopted from a template has name: null and no fields of its own — its fields belong to the base group. field list --group <adoptedId> returning nothing is correct; ask field list --base-group <baseId>. See references/api-quirks.md.
• card field set/clear accept an ID or a name for --group and --field, resolving through the base group. Values are capped at 512 chars, cannot be empty, and clear is idempotent.
• There is no server-side filter by custom field value — filter a snapshot locally.
• task create on a card with more than one task list requires --task-list <id|name>; it exits 2 listing the candidates rather than guessing. With no task list on the card it creates one named "Tasks"; with exactly one it uses it. task list --task-list <id|name> reads one checklist. Manage the checklists themselves with plnk task-list.
• There is no standalone get for task, comment, or label.
  • use task list --card <cardId>
  • use comment list --card <cardId>
  • use label list --board <boardId>
  • or use card snapshot / board snapshot
• Snapshot commands are best when nested state is needed in one call:
  • plnk project snapshot <projectId> --output json
  • plnk board snapshot <boardId> --output json
  • plnk card snapshot <cardId> --output json
• Prefer narrow scopes for both correctness and performance.
• stdout is for data. stderr is for logs and diagnostics.

Command Patterns

Browse the hierarchy:

plnk project list --output json
plnk board list --project <projectId> --output json
plnk list list --board <boardId> --output json
plnk card list --list <listId> --output json
plnk card list --board <boardId> --due-before 2026-04-30 --output json

Find resources by name/title:

plnk project find --name "Platform" --output json
plnk board find --project <projectId> --name "Sprint" --output json
plnk list find --board <boardId> --name "Backlog" --output json
plnk card find --board <boardId> --title "auth" --output json
plnk card find --board <boardId> --due-before 2026-04-30 --output json
plnk card find --board <boardId> --due-after 2026-04-01 --due-before 2026-04-30 --output json

Mutate a card:

plnk card create --list <listId> --title "Fix auth" --output json
plnk card update <cardId> --description @spec.md --output json
plnk card update <cardId> --due-date 2026-04-30 --output json
plnk card update <cardId> --clear-due-date --output json
plnk card move <cardId> --to-list <listId> --position top --output json

Work with tasks and comments:

plnk task list --card <cardId> --output json
plnk task create --card <cardId> --title "Write tests" --output json
plnk task-list list --card <cardId> --output json
plnk task create --card <cardId> --title "Regression pass" --task-list QA --output json
plnk comment create --card <cardId> --text "Starting work" --output json

When Unsure

If command syntax, flags, or resource behavior are uncertain, inspect machine-readable help instead of guessing:

plnk --help --output json
plnk card --help --output json
plnk card create --help --output json

Then read the relevant references.

References

Primary references:

• references/commands.md
• references/api-quirks.md

Resource docs:

• ../../docs/cli/projects.md
• ../../docs/cli/boards.md
• ../../docs/cli/lists.md
• ../../docs/cli/cards.md
• ../../docs/cli/task-lists.md
• ../../docs/cli/tasks.md
• ../../docs/cli/comments.md
• ../../docs/cli/labels.md
• ../../docs/cli/custom-fields.md
• ../../docs/cli/attachments.md
• ../../docs/cli/memberships.md
• ../../docs/cli/users.md
• ../../docs/cli/transport.md