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.

Prerequisites

Requires the plnk binary on PATH and configured credentials. Check both before doing real work:

plnk --version && plnk auth status

If either fails, stop and tell the user what is missing — do not fall back to raw curl against the Planka REST API. See README.md for binary installation and references/auth-and-transport.md for credential setup.

When to use this skill

Use this skill when the user wants to:

• inspect Planka projects, boards, lists, cards, 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
        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
• 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/plnk/config.toml (honors XDG_CONFIG_HOME; override with PLANKA_CONFIG)

Tokens are sent as the X-API-Key header. plnk auth status always exits 0; use plnk auth whoami when a script needs a non-zero exit on bad credentials.

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.
• 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.
• 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
• Card title is name in all JSON output (the --title flag is input-only), and card description is hidden from card get/card list — card create --description can even drop the body silently. Verify descriptions with card snapshot. See references/api-quirks.md.
• 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

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

Mutate a card:

plnk card create --list <listId> --title "Fix auth" --output json
plnk card update <cardId> --description @spec.md --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 comment create --card <cardId> --text "Starting work" --output json

Work with attachments (file/ID are POSITIONAL — there is no --file flag):

plnk attachment upload --card <cardId> /path/to/file --output json
plnk attachment list --card <cardId> --output json      # .size is null in list/upload output
plnk attachment download <attachmentId> --card <cardId> --out /tmp/check.bin
# verify an upload by round-trip: download and `cmp` against the source file

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

All references are vendored locally in references/ — read them from disk, never fetch them from the network.

Start with commands.md for syntax, api-quirks.md when a result looks wrong, and grammar.md when you need exit codes or output-shape guarantees.