fizzydo 0.1.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

Output modes

• Default: human-friendly Rich tables.
• --json — emit raw JSON for piping into jq.
• --id — emit only IDs (or card numbers), one per line, for scripting:

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

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

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.