skills/planka/SKILL.md

---
name: planka
description: Manage Planka project boards using the pcli CLI. Use when the user wants to interact with Planka boards, cards, lists, tasks, labels, or comments.
---

# Planka Skill

Manage Planka project boards using the pcli CLI. Use when the user wants to interact with Planka boards, cards, lists, tasks, labels, or comments.

## Prerequisites

Ensure environment variables are set:
```bash
export PLANKA_URL="https://planka.example.com"
export PLANKA_API_KEY="your-api-key"
```

Ensure `pcli` is in PATH and `jq` is installed.

## Global Flags

All commands (apart from import/export) accept: `--format json|table`, `--url <url>`, `--api-key <key>`, `--log-level debug|info|warn|error`

## Commands

### Status Overview

```bash
pcli status
```

Returns summary of all boards, lists, and card counts (open/closed per list).

### Projects

```bash
pcli project list
pcli project get <project-id>
pcli project create --name "Name" --type private # type: private or shared
pcli project delete <project-id>

# Export/Import
pcli project export <project-id-or-name> [--board <name-or-id>] > backup.json
pcli project import --file backup.json
pcli project import < backup.json
```

Export outputs a portable JSON file (names, not IDs). Import creates all resources with fresh IDs.
Import fails if the project+board name combination already exists on the target.
Comments are exported with `(Original comment by <username>)` prefix for attribution.

**Note:** Export outputs its own envelope format (`{version, exportedAt, project}`) directly — not the standard `{data, error}` envelope. Import progress and errors go to stderr.

### Boards

```bash
pcli board list
pcli board get <board-id> # includes lists and cards
pcli board actions <board-id> [--limit N]
pcli board create --project <project-id> --name "Board Name" [--position N]
pcli board delete <board-id>
```

### Lists (Board Columns)

```bash
pcli list create --board <board-id> --name "Column Name" [--type active|closed] [--position N]
pcli list get <list-id>
pcli list update <list-id> [--name "..."] [--type active|closed] [--color "..."] [--position N] [--board <board-id>]
pcli list delete <list-id>
```

### Cards

```bash
# List (one of --board or --list required, mutually exclusive)
pcli card list --board <board-id> [--limit N]
pcli card list --list <list-id> [--limit N]

# CRUD
pcli card get <card-id>
pcli card create --list <list-id> --name "Name" [--description "..."] [--type project|story] [--position N] [--due-date "ISO8601"] [--due-completed]
pcli card update <card-id> [--name "..."] [--description "..."] [--type ...] [--position N] [--due-date "..."] [--due-completed]
pcli card delete <card-id>
pcli card duplicate <card-id> --name "Copy" [--position N]
pcli card move <card-id> --list <target-list-id> [--position N]

# Members
pcli card assign <card-id> --user <user-id>
pcli card unassign <card-id> --user <user-id>

# Labels
pcli card add-label <card-id> --label <label-id>
pcli card remove-label <card-id> --label <label-id>

# Actions
pcli card actions <card-id> [--limit N]
```

### Comments

```bash
pcli comment list --card <card-id> [--limit N]
pcli comment create --card <card-id> --text "..."
pcli comment update <comment-id> --text "..."
pcli comment delete <comment-id>
```

### Task Lists

```bash
pcli task-list create --card <card-id> --name "Checklist" [--position N] [--show-on-front] [--hide-completed]
pcli task-list get <task-list-id>
pcli task-list update <task-list-id> [--name "..."] [--position N] [--show-on-front] [--hide-completed]
pcli task-list delete <task-list-id>
```

### Tasks

```bash
pcli task create --task-list <task-list-id> --name "Item" [--position N] [--completed]
pcli task update <task-id> [--name "..."] [--position N] [--completed]
pcli task delete <task-id>
```

### Labels

```bash
pcli label create --board <board-id> --name "Bug" --color "berry-red" [--position N]
pcli label update <label-id> [--name "..."] [--color "..."] [--position N]
pcli label delete <label-id>
```

## Extracting IDs from Output

All responses use `{"data": ..., "error": null}`. Extract IDs with jq:

```bash
# Single object
pcli card create --list <id> --name "X" | jq -r '.data.id'

# Array
pcli card list --board <id> | jq -r '.data[].id'
```

## Common Workflows

### Create a complete Kanban board

```bash
# Create board
BOARD_ID=$(pcli board create --project <project-id> --name "Development Board" | jq -r '.data.id')

# Create columns
pcli list create --board $BOARD_ID --name "Backlog" --type "active" --position 0
TODO_ID=$(pcli list create --board $BOARD_ID --name "To Do" --type "active" --position 65536 | jq -r '.data.id')
PROGRESS_ID=$(pcli list create --board $BOARD_ID --name "In Progress" --type "active" --position 131072 | jq -r '.data.id')
DONE_ID=$(pcli list create --board $BOARD_ID --name "Done" --type "closed" --position 196608 | jq -r '.data.id')

# View the board
pcli board get $BOARD_ID --format table
```

### Create a card with a checklist

```bash
CARD_ID=$(pcli card create --list <list-id> --name "Task" | jq -r '.data.id')
TL_ID=$(pcli task-list create --card $CARD_ID --name "Steps" | jq -r '.data.id')
pcli task create --task-list $TL_ID --name "Step 1"
pcli task create --task-list $TL_ID --name "Step 2"
```

### Move all cards between lists

```bash
pcli card list --list <source-list-id> | jq -r '.data[].id' | while read id; do
 pcli card move $id --list <target-list-id>
done
```

### Export and import a project

```bash
# Export entire project
pcli project export "My Project" > project-backup.json

# Export single board
pcli project export "My Project" --board "Sprint Board" > board-backup.json

# Import to another instance (or same instance if project+board combo doesn't exist)
pcli project import --file project-backup.json
```