fizzydo 0.2.0

Command-line client for the fizzy.do kanban API

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

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.

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.