kanban-zone

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:

# 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 <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 [e-mail]
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         | [e-mail]
</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.

# 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": {
    "<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 for complete endpoint documentation, data models, and response schemas.