fizzydo

Command-line client for the fizzy.do kanban API.

fizzydo is a thin, ergonomic CLI over the fizzy.do REST API for boards, columns, cards, comments, steps, tags, and pins. Resource-first command shape: fizzydo cards list, fizzydo boards create --name ..., fizzydo cards close 42.

Install

pip install fizzydo

Or with pipx / uv for an isolated install:

pipx install fizzydo
# or
uv tool install fizzydo

For development against a local checkout:

pip install -e ".[dev]"
pytest

Requires Python 3.11+.

Authentication

fizzydo authenticates with a personal access token from your fizzy.do profile (Profile → API → Personal access tokens → Generate new access token).

Set the token in FIZZYDO_API_KEY:

export FIZZYDO_API_KEY=your-token-here

If the env var is unset, fizzydo reads it from a .env file. Lookup order:

1. --env-file-path <path> (explicit override)
2. ./.env (current directory)
3. $HOME/.env

A .env looks like:

FIZZYDO_API_KEY=your-token-here
FIZZYDO_ACCOUNT=897362094         # optional, account slug
FIZZYDO_BASE_URL=https://app.fizzy.do  # optional

Quick start

fizzydo auth whoami                # list your accounts
fizzydo boards list                # see your boards
fizzydo cards list --mine          # cards assigned to you

# Create, comment on, and close a card
BOARD=$(fizzydo boards list --id | head -1)
fizzydo cards create --board "$BOARD" --title "Add dark mode" --description "We need dark mode."
fizzydo comments add 42 "Started looking into this."
fizzydo cards close 42

# Read a card with its description, checklist, and comments inline
fizzydo cards show 42

# Drop a card straight into a column instead of triage
DOING=$(fizzydo columns list --board "$BOARD" --id | sed -n '2p')
fizzydo cards create --board "$BOARD" --column "$DOING" \
  --title "Wire up dark mode toggle" --description @dark-mode.md

# Bulk-import a directory of markdown files as cards
fizzydo cards bulk-create --board "$BOARD" --column "$DOING" --from-dir ./tasks/

Output modes

• Default: human-friendly Rich tables. cards show <n> is the exception — it renders the card's title, metadata, the description body (HTML→markdown via Rich), the checklist with [x]/[ ] markers, and every comment, all inline.
• --json — emit raw JSON for piping into jq. For cards show, this returns {"card": {...}, "comments": [...]} so you can fetch both in one round trip.
• --id — emit only IDs (or card numbers), one per line, for scripting:

fizzydo cards list --mine --id | xargs -n1 fizzydo cards close

cards list --status all is a true union: it issues two requests (open feed + closed feed), dedupes by id, and re-sorts by last_active_at. Other status values still hit the API once.

Rich-text input

--description (cards) and the comment body argument accept several input forms:

• Inline plain text: --description "Quick note"
• A Markdown file: --description @notes.md
• An HTML file: --description @body.html
• Stdin (Markdown): --description -
• An editor: comments add 42 --editor

Commands

Resource	Subcommands
auth	whoami, status
boards	list, show, create, update, delete, publish, unpublish
columns	list, show, create, update, delete
cards	list, show, create, bulk-create, update, delete, close, reopen, not-now, triage, untriage, tag, assign, golden, ungolden, watch, unwatch
comments	list, show, add, update, delete
steps	list, add, done, undo, update, delete
tags	list
pins	list, add, remove
install	skill

Run fizzydo <resource> --help for full options on any subcommand.

A few ergonomics worth knowing:

• cards create --column COL triages the new card straight into a column, skipping the implicit triage step.
• cards bulk-create --from-dir ./tasks/ walks *.md files and creates one card per file. The H1 (# Title) becomes the title; the rest is the description. Combine with --column and --id for agent-driven flows.
• boards create --description ... is an alias for --public-description.
• steps done|undo|update|delete accept either a literal step ID or a 1-based index into the card's checklist (fizzydo steps done 42 1).

Exit codes

Code	Meaning
0	Success
1	Generic / network / config error
2	401 Unauthorized
3	403 Forbidden
4	404 Not Found
5	422 Unprocessable Entity (validation)
6	429 Too Many Requests
7	5xx Server Error

Using fizzydo from an agent

fizzydo is designed to be driven by coding agents (Claude Code, Codex CLI, etc.) for project task tracking. The recommended workflow — one board per project, three columns (TODO/DOING/DONE), cards moved through them as work progresses — is documented in FIZZYDO_AGENT_USE.md. Point your agent at that file at the start of a session.

Agent skill (agentskills.io)

An agentskills.io-compatible skill is bundled at skill/fizzydo/. Install it so your agent automatically knows how to drive fizzydo:

# Global (all projects):
fizzydo install skill global   # → ~/.claude/skills/fizzydo/

# Local (this project only):
fizzydo install skill local    # → .claude/skills/fizzydo/

Once installed, invoke with /fizzydo in Claude Code, or let the agent trigger it automatically when breaking down tasks. Compatible with Claude Code, Codex CLI, Gemini CLI, OpenHands, and other agentskills.io agents.

Not yet implemented

Webhooks, notifications, reactions, users admin, account settings, file/image uploads, and ETag-based caching are deferred to follow-up iterations. The fizzy.do API spec lives in Fizzy_API.md if you want to track what's still missing.

License

MIT — see LICENSE.