Kanban Zone

Kanban Zone

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

⚠️ Delete operations do not work (Kanban Zone server-side bug)

Every delete command currently fails — cards delete, checklists delete, tasks delete, webhooks delete, and tokens revoke. Kanban Zone's API edge strips the body from DELETE requests, so Kanban Zone rejects them all with a "Body Parser failed" error and never deletes the record. This is a Kanban Zone server-side bug (confirmed 2026-05-16, reported to Kanban Zone) — not a problem with your request or this skill.

The skill detects this and exits non-zero with a KanbanZoneDeleteUnsupportedError that explains the situation in full. It does not report a false success.

Guidance for agents:

• Do not call a delete command expecting it to succeed.
• Do not retry a failed delete — no request shape works; retrying wastes API

quota.

• If a user asks you to delete a card, checklist, task, webhook, or token,

tell them it must be done in the Kanban Zone web UI, and explain why.

• cards move (e.g. to an Archive column) and cards update /

checklists update (rewriting titles/descriptions) still work and can neutralize an unwanted record without deleting it.

See README.md → "Deleting records is currently broken" 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:

# 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.

# 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 / --api-token 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.

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 --help to see subcommands for any group. Run python3 scripts/kanban_zone_api.py --help for full flag details.

boards

Manage boards and their metadata.

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.

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 — ⚠️ currently non-functional (Kanban Zone API bug) | | 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.

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.

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 — ⚠️ currently non-functional (Kanban Zone API bug) | | list | List all checklists (and their tasks) on a card |

tasks

Manage individual tasks within a checklist.

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 — ⚠️ currently non-functional (Kanban Zone API bug) | | move | Reorder a task within its checklist |

webhooks

Register and manage webhooks for board event notifications.

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 

| 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 — ⚠️ currently non-functional (Kanban Zone API bug) | | 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.

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.

python3 scripts/kanban_zone_api.py tokens list
python3 scripts/kanban_zone_api.py tokens assign --card 42 --token-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 — ⚠️ currently non-functional (Kanban Zone API bug) | | list | List all active tokens for the organization |

org

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

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 `, , /, , , , and instead of Markdown syntax (###, **, -, [text](url)`, etc.).

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

Field         | Value
--------------+------------
Priority      | High
Due date      | 2026-04-30
Owner         | sarah@co.com

Do not attempt to "illustrate tables of data with HTML tables" — always use `` 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.

# 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:

{
  "boards": {
    "": {
      "name": "Board Name",
      "columns": {
        "": { "name": "Column Name", "state": "In Progress" }

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [MaxGood-AI](https://github.com/MaxGood-AI)
- **Source:** [MaxGood-AI/kanban-zone-agent-skill](https://github.com/MaxGood-AI/kanban-zone-agent-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.