---
name: kanban-zone
description: Interact with Kanban Zone kanban boards via the Kanban Zone API. Use when the user wants to manage kanban cards, boards, comments, checklists, tasks, webhooks, or board reports. Even if the user just says "check the board", "what's in progress", or mentions kanban cards, use this skill.
license: MIT
compatibility: Requires python3 and environment variables KANBAN_ZONE_API_KEY and KANBAN_ZONE_BOARD_ID. Wraps Kanban Zone Public API v1.4.
metadata:
  version: "3.2.0"
  openclaw:
    requires:
      env:
        - KANBAN_ZONE_API_KEY
        - KANBAN_ZONE_BOARD_ID
      bins:
        - python3
    primaryEnv: KANBAN_ZONE_API_KEY
    homepage: https://docs.kanbanzone.io
---

# Kanban Zone

Manage Kanban Zone kanban boards through the Kanban Zone Public API (v1.4).

## Delete operations work again (Kanban Zone fixed its API, 2026-06-11)

If you have prior context saying delete commands are broken, it is stale:
Kanban Zone fixed the server-side "Body Parser failed" defect that made every
DELETE fail between 2026-05-16 and 2026-06-11. All five delete commands
(`cards delete`, `checklists delete`, `tasks delete`, `webhooks delete`,
`tokens revoke`) work normally. A successful delete prints
`{"deleted": true, "id": ...}` and exits zero. The skill keeps a defensive
check: if the old failure envelope ever reappears, the delete **fails loudly**
(`KanbanZoneDeleteUnsupportedError`, exit non-zero) instead of reporting a
fake success — if you see that error, the defect has regressed; tell the user
and fall back to the Kanban Zone web UI.

## ⚠️ Monthly API usage limit (error code 2006)

Kanban Zone enforces a **monthly API-call quota** per organization (usage is
tracked per API key against the plan's limit). When the quota is exhausted,
**every** API call fails until the monthly quota resets or the plan's limit
is raised — and Kanban Zone returns the failure as **HTTP 200** with the
error only in the response body:

```json
{"code": 2006, "status": 429, "name": "TooManyRequests", "message": "API Usage limit reached"}
```

The skill detects this envelope and **exits non-zero** with a
`KanbanZoneUsageLimitError` that explains the situation in full. It does
**not** hand the envelope back as if it were data (before v3.2.0 this leaked
through and made a quota-exhausted card lookup report "card not found").

**Guidance for agents:**

- **Do not retry.** No request will succeed until the quota resets or the
  limit is raised, and retry loops burn through the fresh quota the moment
  it does.
- **Direct the user to check their API usage status** in the Kanban Zone web
  interface: the **Organization > Integrations** panel
  (`https://kanbanzone.io/settings/integrations`). Its "Available API Calls"
  meter shows current usage against the plan's monthly limit, per API key.
- Budget the remaining quota in normal operation: a cold-cache card-number
  lookup paginates `/cards` at one call per 100 cards, so keep the local
  cache warm and avoid polling loops.

See `README.md` → "Monthly API usage limit" for the full technical detail.

## ⚠️ Exec Safety Rule — Multi-line Commands

**Never pass multi-line shell commands or long `--description` strings inline to `exec`.** The exec preflight will block them as "complex interpreter invocation".

**Always write to a temp file first:**

```python
# Write description to temp file
with open('/tmp/kanban-zone-desc.txt', 'w') as f:
    f.write("""Your multi-line
description here""")

# Then run the CLI via a script file
script = '''import subprocess
result = subprocess.run(
    ["python3", "skills/kanban-zone/scripts/kanban_zone_api.py",
     "cards", "update", "--id", "123",
     "--description", open("/tmp/kanban-zone-desc.txt").read()],
    capture_output=True, text=True
)
print(result.stdout)
print(result.stderr)
'''
with open('/tmp/kanban-zone-run.py', 'w') as f:
    f.write(script)
# Then exec: python3 /tmp/kanban-zone-run.py
```

Or simply build the whole call as a Python script in `/tmp/` and exec that file directly.

## ⚠️ Reading Command Output — do not pipe through inline parsers

Every command prints a **single JSON value** to stdout and nothing else. On success it is the result object/array; on failure it is `{"error": true, "message": "..."}` **and the process exits non-zero**.

**Do not pipe the output through an inline `python3 -c "..."` (or `jq`, `grep`, etc.) to pluck a field.** Two things go wrong, and both waste a turn:

- The inline parser assumes the *success* shape. When the command fails, the output is the `{"error": ...}` object instead, so the parser raises `KeyError` on the field you expected — and that traceback **replaces** the genuinely helpful `message`, so you have to re-run the command bare just to see what actually went wrong.
- Inline `python3 -c` scripts are exactly the "complex interpreter invocation" the exec preflight blocks (see the Exec Safety Rule above).

**Instead:** run the command on its own with `--pretty` and read the JSON directly from the tool result. It is already structured — you do not need to post-process it.

```bash
# GOOD — run it bare, read the JSON yourself
python3 scripts/kanban_zone_api.py --pretty cards get --id 65

# BAD — parser crashes on the error shape and hides the real message
python3 scripts/kanban_zone_api.py cards get --id 65 | python3 -c "import sys,json; print(json.load(sys.stdin)['CardItem']['title'])"
```

If a result is genuinely too large to read inline (e.g. `cards search` across many boards) and you must extract fields with a script, **write the script to a `/tmp/*.py` file** (per the Exec Safety Rule) and have it **check `if data.get("error"): ...` first** before touching success-shape keys.

**Response shapes vary by command** — don't assume. `cards get` returns `{"_id", "CardItem", "meta"}` (the card is nested under `CardItem`); `cards list` / `cards search` return `{"count", "cards": [...]}` with each card wrapped in a `CardItem` envelope; `boards list` wraps each board in a `BoardItem` envelope. When unsure, run once with `--pretty` and look.

## Environment Setup

The CLI script reads two environment variables: `KANBAN_ZONE_API_KEY` and `KANBAN_ZONE_BOARD_ID`.

The script **automatically loads** these from a `.env` file if they are not already in the environment. It searches the current working directory **and the script's own location (symlinks resolved)**, plus **every ancestor directory of each**, up to the filesystem root — so a workspace-root `.env` is found no matter which directory you run the command from. No shell export, `cd`, or command substitution is needed — just run the Python command directly.

**You do not need to `cd` anywhere first.** If you see `--board or KANBAN_ZONE_BOARD_ID is required` or `KANBAN_ZONE_API_KEY is not set`, the `.env` is genuinely missing — do not retry from a different directory or re-run blindly. Either pass `--board <id>` / `--api-token <key>` explicitly, or tell the user the `.env` is not present in the workspace tree.

**Get your API key:** Settings > Organization Settings > Integrations > API Key
Direct: `https://kanbanzone.io/settings/integrations`

**Find column IDs:** Board Settings > API, or Organization Settings > Integrations > API

## Quick Start

All examples below assume a `.env` file with `KANBAN_ZONE_API_KEY` and `KANBAN_ZONE_BOARD_ID` exists in the workspace root.

```bash
python3 scripts/kanban_zone_api.py boards list
python3 scripts/kanban_zone_api.py boards get
python3 scripts/kanban_zone_api.py cards list --label "Bug"
python3 scripts/kanban_zone_api.py cards get --id 42
python3 scripts/kanban_zone_api.py cards create --title "New task" --column-id COL1
python3 scripts/kanban_zone_api.py cards move --id 42 --column-id COL2
python3 scripts/kanban_zone_api.py cards delete --id 42
python3 scripts/kanban_zone_api.py comments add --card 42 --text "Looks good!"
python3 scripts/kanban_zone_api.py checklists create --card 42 --title "QA" --task "T1"
python3 scripts/kanban_zone_api.py reports throughput --from-date 2026-01-01 --to-date 2026-04-01
```

## Resource Groups

Commands are organized into nine resource groups. Run `python3 scripts/kanban_zone_api.py <group> --help` to see subcommands for any group. Run `python3 scripts/kanban_zone_api.py <group> <subcommand> --help` for full flag details.

### boards

Manage boards and their metadata.

```bash
python3 scripts/kanban_zone_api.py boards list
python3 scripts/kanban_zone_api.py boards get --include-columns
python3 scripts/kanban_zone_api.py boards custom-fields
```

| Subcommand | Description |
|------------|-------------|
| `list` | List all boards with metrics (active/blocked/overdue counts) |
| `get` | Get a specific board's details; `--include-columns` adds column data and WIP limits |
| `columns` | List all columns for the active board |
| `labels` | List all labels defined on the active board |
| `members` | List all members of the active board |
| `custom-fields` | List custom field definitions for the active board |
| `templates` | List card templates available on the active board |

### cards

Create, read, update, move, delete, and search cards.

```bash
python3 scripts/kanban_zone_api.py cards list --label "Bug" --blocked
python3 scripts/kanban_zone_api.py cards create --title "New task" --column-id COL1 --owner dev@example.com
python3 scripts/kanban_zone_api.py cards move --id 42 --column-id COL2
```

| Subcommand | Description |
|------------|-------------|
| `list` | List cards on the active board with optional filters (label, owner, column, blocked, priority, query) |
| `get` | Get a single card by number or ObjectId |
| `create` | Create one card (supports watchers, custom fields, description file) |
| `create-bulk` | Create multiple cards from a JSON file |
| `update` | Update card fields (title, description, owner, watchers, custom fields, blocked status) |
| `move` | Move a card to a different column |
| `delete` | Delete a card |
| `history` | Get the activity history for a card |
| `metrics` | Get cycle time and lead time metrics for a card |
| `links-add` | Add a card-to-card or external URL link to a card |
| `links-remove` | Remove a card-to-card or external URL link from a card |
| `search` | Search cards across all boards by keyword and optional filters |
| `wip-check` | Check WIP limits across all columns, flagging over/under-limit columns |

### comments

Add and list comments on cards.

```bash
python3 scripts/kanban_zone_api.py comments add --card 42 --text "Review complete."
python3 scripts/kanban_zone_api.py comments list --card 42
```

| Subcommand | Description |
|------------|-------------|
| `add` | Add a comment to a card |
| `list` | List all comments on a card |

### checklists

Manage checklists and their inline tasks attached to cards.

```bash
python3 scripts/kanban_zone_api.py checklists create --card 42 --title "Release QA" --task "Run tests" --task "Update docs"
python3 scripts/kanban_zone_api.py checklists list --card 42
```

| Subcommand | Description |
|------------|-------------|
| `create` | Create a checklist on a card, optionally pre-populating it with tasks |
| `update` | Update a checklist's title or reorder its tasks |
| `delete` | Delete a checklist |
| `list` | List all checklists (and their tasks) on a card |

### tasks

Manage individual tasks within a checklist.

```bash
python3 scripts/kanban_zone_api.py tasks create --checklist CHECKLIST_ID --title "Write tests"
python3 scripts/kanban_zone_api.py tasks update --id TASK_ID --completed true
```

| Subcommand | Description |
|------------|-------------|
| `create` | Add a task to an existing checklist |
| `update` | Update a task (title, completed status, assignee) |
| `delete` | Delete a task |
| `move` | Reorder a task within its checklist |

### webhooks

Register and manage webhooks for board event notifications.

```bash
python3 scripts/kanban_zone_api.py webhooks list
python3 scripts/kanban_zone_api.py webhooks create --url https://hooks.example.com/kanban-zone-webhook --event CARD_MOVED
python3 scripts/kanban_zone_api.py webhooks verify-signature --payload-file /tmp/payload.json --signature <raw-hex-value-from-X-KanbanZone-Signature-header>
```

| Subcommand | Description |
|------------|-------------|
| `list` | List all registered webhooks for the active board |
| `get` | Get details of a specific webhook by ObjectId |
| `create` | Register a new webhook endpoint with selected event types |
| `update` | Update a webhook's URL or event subscription |
| `delete` | Delete a webhook registration |
| `test` | Send a test ping to a registered webhook |
| `verify-signature` | Verify an incoming webhook delivery's HMAC signature |

### reports

Pull board-level analytics reports for a date range.

```bash
python3 scripts/kanban_zone_api.py reports throughput --from-date 2026-01-01 --to-date 2026-04-01
python3 scripts/kanban_zone_api.py reports cycle-time --from-date 2026-01-01
python3 scripts/kanban_zone_api.py reports flow-efficiency
```

| Subcommand | Description |
|------------|-------------|
| `throughput` | Cards completed per time unit over the date range |
| `arrival-rate` | Cards arriving (created) per time unit over the date range |
| `cycle-time` | Statistical distribution of time from start to completion |
| `lead-time` | Statistical distribution of time from creation to completion |
| `flow` | Cumulative flow diagram data showing column occupancy over time |
| `flow-efficiency` | Ratio of active (value-add) time to total elapsed time |
| `allocation` | Breakdown of card effort by label, owner, or custom field |
| `abandoned-effort` | Cards that were started but deleted or reverted before completion |

### tokens

Manage card share tokens — named tokens defined in Organization Settings (Settings → Integrations → Card Tokens) that are assigned to cards to control card visibility and external sharing.

```bash
python3 scripts/kanban_zone_api.py tokens list
python3 scripts/kanban_zone_api.py tokens assign --card 42 --token-id <token-definition-id>
python3 scripts/kanban_zone_api.py tokens revoke --id TOKEN_ID
```

| Subcommand | Description |
|------------|-------------|
| `assign` | Create and assign a new API token with an optional label |
| `revoke` | Revoke a token by its ObjectId |
| `list` | List all active tokens for the organization |

### org

Read the caller's identity and the active board/org context.

```bash
python3 scripts/kanban_zone_api.py org me
python3 scripts/kanban_zone_api.py org context
```

| Subcommand | Description |
|------------|-------------|
| `me` | Return the authenticated user's profile and permissions |
| `context` | Return the resolved board/org context used by the current CLI invocation |

## Description Updates (IMPORTANT)

**Always use `--description-file` instead of `--description` for creating or updating card descriptions.** This avoids multi-line quoting issues in shell commands.

**Always format descriptions as HTML, never Markdown.** Kanban Zone renders card descriptions as HTML. Use tags like `<h3>`, `<p>`, `<ul>/<li>`, `<strong>`, `<em>`, `<a href="...">`, and `<br>` instead of Markdown syntax (`###`, `**`, `-`, `[text](url)`, etc.).

**⚠️ NEVER use HTML tables in descriptions.** Kanban Zone **silently strips** `<table>`, `<thead>`, `<tbody>`, `<tr>`, `<th>`, and `<td>` tags — the data disappears from the rendered card without warning. For **any** tabular data, use a `<pre>` block with fixed-width ASCII columns instead (this is the HTML equivalent of Markdown triple-backtick code blocks). Example:

```html
<pre>
Field         | Value
--------------+------------
Priority      | High
Due date      | 2026-04-30
Owner         | sarah@co.com
</pre>
```

Do not attempt to "illustrate tables of data with HTML tables" — always use `<pre>` with fixed-width characters.

Workflow:
1. Write the description content to a temp file (e.g., `/tmp/kanban-zone-desc.txt`) using the Write tool.
2. Run the command with `--description-file /tmp/kanban-zone-desc.txt`.

```bash
# CORRECT — use --description-file for all description changes
python3 scripts/kanban_zone_api.py cards update --id 42 --description-file /tmp/kanban-zone-desc.txt
python3 scripts/kanban_zone_api.py cards create --title "New task" --description-file /tmp/kanban-zone-desc.txt

# AVOID — inline --description with multi-line content
python3 scripts/kanban_zone_api.py cards update --id 42 --description "line 1\nline 2\n..."
```

The `--description-file` flag reads the entire file content as the description. It overrides `--description` if both are provided.

## Card ID Auto-Detection

`--id` accepts either a card number (digits only, e.g. `42`) or a 24-character hexadecimal ObjectId (e.g. `507f1f77bcf86cd799439011`). The skill auto-detects which form is supplied:

- **Digit string** → treated as a card number; resolved to an ObjectId via the bidirectional cache (or a `cards get` lookup if the cache is cold) before calling ObjectId-keyed endpoints.
- **24-hex string** → used directly as the ObjectId.

Sub-resource IDs (checklist ID, task ID, comment ID, token ID, webhook ID) are always 24-hex ObjectIds — there are no short numeric aliases for these resources.

## Cache (with bidirectional ID mapping)

To avoid unnecessary API calls when resolving board or column names to IDs, and card numbers to ObjectIds, maintain a local cache file in your memory directory.

### Cache file

Store `kanbanzone-cache.json` in your persistent memory directory with this structure:

```json
{
  "boards": {
    "<board-public-id>": {
      "name": "Board Name",
      "columns": {
        "<column-id>": { "name": "Column Name", "state": "In Progress" }
      },
      "cards": {
        "byNumber":   { "42": "507f1f77bcf86cd799439011" },
        "byObjectId": { "507f1f77bcf86cd799439011": 42 }
      }
    }
  },
  "updated": "2026-02-25T12:00:00Z"
}
```

The `byNumber` and `byObjectId` sub-objects form a bidirectional map between card numbers and their ObjectIds. They are populated opportunistically — every `cards list` or `cards get` response that returns card data should be used to update both maps, so the cache grows warmer with normal use without ever requiring a dedicated cache-fill step.

### Lookup flow

1. **Before** calling the API to resolve a board name to an ID, column name to an ID, or card number to an ObjectId, read `kanbanzone-cache.json` from your memory directory.
2. If the cache file exists and contains a matching entry (case-insensitive for names), use the cached value directly — **do not call the API**.
3. If the cache file is missing, or the name/number is not found, call the appropriate API command and then **update the cache file** with the returned data before proceeding.

### Auto-populate

Whenever you run `boards list`, `boards get --include-columns`, `cards list`, or `cards get` for any reason, always update `kanbanzone-cache.json` with the returned data. This keeps the cache fresh as a side effect of normal operations.

### Cache refresh

If the user says board, column, or card data is stale, or explicitly asks to refresh the cache, re-fetch from the API and overwrite `kanbanzone-cache.json`.

### Important notes

- The cache lives in **your agent memory directory**, not in the skill's directory. This keeps the skill stateless and portable.
- Column IDs change if a board is restructured — always honor a cache miss by falling back to the API.
- When writing the cache, set `"updated"` to the current ISO 8601 timestamp.

## Column States

| State | Meaning |
|-------|---------|
| `Backlog` | Pre-commitment items |
| `To Do` | Committed, ready to start |
| `Buffer` | Queue between stages |
| `In Progress` | Currently being worked on |
| `Done` | Completed |
| `Archive` | Historical items |
| `None` | No state assigned |

## Script Reference

All commands output JSON. Run `python3 scripts/kanban_zone_api.py --help` for full usage.

| Group | Subcommand | Description |
|-------|------------|-------------|
| `boards` | `list` | List all boards with metrics |
| `boards` | `get` | Get a specific board's details and columns |
| `boards` | `columns` | List all columns for the active board |
| `boards` | `labels` | List all labels on the active board |
| `boards` | `members` | List all members of the active board |
| `boards` | `custom-fields` | List custom field definitions for the active board |
| `boards` | `templates` | List card templates on the active board |
| `cards` | `list` | List cards with optional filters |
| `cards` | `get` | Get a single card by number or ObjectId |
| `cards` | `create` | Create one card |
| `cards` | `create-bulk` | Create multiple cards from a JSON file |
| `cards` | `update` | Update card fields |
| `cards` | `move` | Move a card to a column |
| `cards` | `delete` | Delete a card |
| `cards` | `history` | Get activity history for a card |
| `cards` | `metrics` | Get cycle/lead time metrics for a card |
| `cards` | `links-add` | Add a card-to-card or URL link |
| `cards` | `links-remove` | Remove a card-to-card or URL link |
| `cards` | `search` | Search cards across all boards |
| `cards` | `wip-check` | Check WIP limits across columns |
| `comments` | `add` | Add a comment to a card |
| `comments` | `list` | List all comments on a card |
| `checklists` | `create` | Create a checklist on a card |
| `checklists` | `update` | Update a checklist's title or tasks |
| `checklists` | `delete` | Delete a checklist |
| `checklists` | `list` | List all checklists on a card |
| `tasks` | `create` | Add a task to a checklist |
| `tasks` | `update` | Update a task (title, completed, assignee) |
| `tasks` | `delete` | Delete a task |
| `tasks` | `move` | Reorder a task within its checklist |
| `webhooks` | `list` | List all registered webhooks |
| `webhooks` | `get` | Get a specific webhook by ObjectId |
| `webhooks` | `create` | Register a new webhook endpoint |
| `webhooks` | `update` | Update a webhook's URL or event |
| `webhooks` | `delete` | Delete a webhook |
| `webhooks` | `test` | Send a test ping to a webhook |
| `webhooks` | `verify-signature` | Verify an incoming webhook delivery's HMAC signature |
| `reports` | `throughput` | Cards completed per time unit |
| `reports` | `arrival-rate` | Cards arriving per time unit |
| `reports` | `cycle-time` | Distribution of time from start to completion |
| `reports` | `lead-time` | Distribution of time from creation to completion |
| `reports` | `flow` | Cumulative flow diagram data |
| `reports` | `flow-efficiency` | Ratio of active time to total elapsed time |
| `reports` | `allocation` | Effort breakdown by label, owner, or custom field |
| `reports` | `abandoned-effort` | Cards started but abandoned before completion |
| `tokens` | `assign` | Create and assign a new API token |
| `tokens` | `revoke` | Revoke a token |
| `tokens` | `list` | List all active tokens |
| `org` | `me` | Return the authenticated user's profile |
| `org` | `context` | Return the resolved board/org context |

## Migration from v2

If you previously used flat commands (`create-card`, `update-card`, `move-card`, etc.), they still work as hidden aliases and will not appear in `--help` output — see `references/migration-from-v2.md` for the full mapping. New code should use the grouped commands documented above.

## API Reference

See [references/api-reference.md](./references/api-reference.md) for complete endpoint documentation, data models, and response schemas.