| 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:
{"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:
with open('/tmp/kanban-zone-desc.txt', 'w') as f:
f.write("""Your multi-line
description here""")
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)
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.
python3 scripts/kanban_zone_api.py --pretty cards get --id 65
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.
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.
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 |
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 |
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 |
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 <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.
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 <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.
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:
<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:
- Write the description content to a temp file (e.g.,
/tmp/kanban-zone-desc.txt) using the Write tool.
- Run the command with
--description-file /tmp/kanban-zone-desc.txt.
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
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": {
"<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
- 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.
- If the cache file exists and contains a matching entry (case-insensitive for names), use the cached value directly — do not call the API.
- 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 for complete endpoint documentation, data models, and response schemas.
