A command-line interface for the Fizzy API. See the official API docs.
Arch Linux (AUR)
yay -S fizzy-climacOS (Homebrew)
brew install robzolkos/fizzy-cli/fizzy-cliDebian/Ubuntu
# Download the .deb for your architecture (amd64 or arm64) curl -LO https://github.com/robzolkos/fizzy-cli/releases/latest/download/fizzy-cli_VERSION_amd64.deb sudo dpkg -i fizzy-cli_VERSION_amd64.debFedora/RHEL
# Download the .rpm for your architecture (x86_64 or aarch64) curl -LO https://github.com/robzolkos/fizzy-cli/releases/latest/download/fizzy-cli-VERSION-1.x86_64.rpm sudo rpm -i fizzy-cli-VERSION-1.x86_64.rpmWindows
Download fizzy-windows-amd64.exe from GitHub Releases, rename it to fizzy.exe, and add it to your PATH.
With Go
go install github.com/robzolkos/fizzy-cli/cmd/fizzy@latestFrom binary
Download the latest release for your platform from GitHub Releases and add it to your PATH.
From source
git clone https://github.com/robzolkos/fizzy-cli.git cd fizzy-cli go build -o fizzy ./cmd/fizzy ./fizzy --helpThe CLI looks for configuration in multiple locations:
Global config is stored in one of these locations:
~/.config/fizzy/config.yaml(preferred)~/.fizzy/config.yaml
token: fizzy_abc123... account: 897362094 api_url: https://app.fizzy.do board: 123456You can also create a .fizzy.yaml file in your project directory. The CLI walks up the directory tree to find it, so you can run commands from any subdirectory.
# .fizzy.yaml - project-specific settings account: 123456789 api_url: https://self-hosted.example.com board: 123456Local config values merge with global config:
- Values in local config override global config
- Empty values in local config do not override global values
- This allows you to keep your token in global config while overriding account per project
Example: Global config has your token, local config specifies which account to use for this project:
# ~/.config/fizzy/config.yaml (global) token: fizzy_abc123... # /path/to/project/.fizzy.yaml (local) account: 123456789Configuration priority (highest to lowest):
- Command-line flags (
--token,--account,--api-url) - Environment variables (
FIZZY_TOKEN,FIZZY_ACCOUNT,FIZZY_API_URL,FIZZY_BOARD) - Local project config (
.fizzy.yamlin current or parent directories) - Global config (
~/.config/fizzy/config.yamlor~/.fizzy/config.yaml) - Defaults
-
Get your API token from My Profile → Personal Access Tokens (see instructions)
-
Run the interactive setup wizard:
fizzy setupThe wizard will guide you through configuring your token, selecting your account, and optionally setting a default board.
That's it! Try fizzy board list to verify everything is working.
fizzy <resource> <action> [options] fizzy version| Option | Environment Variable | Description |
|---|---|---|
--token | FIZZY_TOKEN | API access token |
--account | FIZZY_ACCOUNT | Account slug (from fizzy identity show) |
--api-url | FIZZY_API_URL | API base URL (default: https://app.fizzy.do) |
--verbose | Show request/response details |
# List all boards fizzy board list # Show a board fizzy board show BOARD_ID # Create a board fizzy board create --name "Engineering" # Update a board fizzy board update BOARD_ID --name "New Name" # Delete a board fizzy board delete BOARD_ID# List cards (with optional filters) fizzy card list fizzy card list --board BOARD_ID fizzy card list --column COLUMN_ID fizzy card list --column maybe fizzy card list --column done fizzy card list --tag TAG_ID fizzy card list --indexed-by not_now fizzy card list --assignee USER_ID # Tip: if you set a default `board` in config (or `FIZZY_BOARD`), `fizzy card list` automatically filters to that board unless you pass `--board`. # Show a card fizzy card show 42 # Create a card fizzy card create --board BOARD_ID --title "Fix login bug" fizzy card create --board BOARD_ID --title "New feature" --description "Details here" fizzy card create --board BOARD_ID --title "Card" --tag-ids "TAG_ID1,TAG_ID2" fizzy card create --board BOARD_ID --title "Card" --image /path/to/header.png # Create with custom timestamp (for data imports) fizzy card create --board BOARD_ID --title "Old card" --created-at "2020-01-15T10:30:00Z" # Update a card fizzy card update 42 --title "Updated title" fizzy card update 42 --image SIGNED_ID fizzy card update 42 --created-at "2019-01-01T00:00:00Z" # Delete a card fizzy card delete 42# Close/reopen fizzy card close 42 fizzy card reopen 42 # Move to "Not Now" fizzy card postpone 42 # Move into a column fizzy card column 42 --column COLUMN_ID # Move into UI lanes (pseudo columns) fizzy card column 42 --column not-now fizzy card column 42 --column maybe fizzy card column 42 --column done # Send back to triage fizzy card untriage 42 # Assign/unassign (toggles) fizzy card assign 42 --user USER_ID # Tag/untag (toggles, creates tag if needed) fizzy card tag 42 --tag "bug" # Watch/unwatch fizzy card watch 42 fizzy card unwatch 42 # Remove card header image fizzy card image-remove 42 # Mark/unmark card as golden fizzy card golden 42 fizzy card ungolden 42# List attachments on a card fizzy card attachments show 42 # Download all attachments from a card fizzy card attachments download 42 # Download a specific attachment by index (1-based) fizzy card attachments download 42 1 # Download with a custom filename fizzy card attachments download 42 1 -o my-file.pngfizzy column list --board BOARD_ID fizzy column show COLUMN_ID --board BOARD_ID fizzy column create --board BOARD_ID --name "In Progress" fizzy column update COLUMN_ID --board BOARD_ID --name "Done" fizzy column delete COLUMN_ID --board BOARD_IDfizzy column list also includes the UI's built-in lanes as pseudo columns in this order:
not-now(Not Now)maybe(Maybe?)- your real columns…
done(Done)
When filtering cards by --column maybe (triage) or a real column ID, the CLI filters client-side; use --all to fetch all pages before filtering.
fizzy comment list --card 42 fizzy comment show COMMENT_ID --card 42 fizzy comment create --card 42 --body "Looks good!" fizzy comment create --card 42 --body-file /path/to/comment.html # Create with custom timestamp (for data imports) fizzy comment create --card 42 --body "Old comment" --created-at "2020-01-15T10:30:00Z" fizzy comment update COMMENT_ID --card 42 --body "Updated comment" fizzy comment delete COMMENT_ID --card 42# Show a step fizzy step show STEP_ID --card 42 # Create a step fizzy step create --card 42 --content "Review PR" fizzy step create --card 42 --content "Already done" --completed # Update a step fizzy step update STEP_ID --card 42 --completed fizzy step update STEP_ID --card 42 --not-completed fizzy step update STEP_ID --card 42 --content "New content" # Delete a step fizzy step delete STEP_ID --card 42# List reactions on a comment fizzy reaction list --card 42 --comment COMMENT_ID # Add a reaction (emoji, max 16 chars) fizzy reaction create --card 42 --comment COMMENT_ID --content "👍" # Remove a reaction fizzy reaction delete REACTION_ID --card 42 --comment COMMENT_IDfizzy user list fizzy user show USER_IDfizzy tag listfizzy notification list fizzy notification read NOTIFICATION_ID fizzy notification unread NOTIFICATION_ID fizzy notification read-allUpload files for use in rich text fields (card descriptions, comment bodies) or as card header images.
# Upload a file fizzy upload file /path/to/image.png # Returns: { "signed_id": "...", "attachable_sgid": "..." }The upload returns two IDs for different purposes:
| ID | Use Case |
|---|---|
signed_id | Card header images (--image flag) |
attachable_sgid | Inline images in rich text (<action-text-attachment>) |
Header image:
SIGNED_ID=$(fizzy upload file header.png | jq -r '.data.signed_id') fizzy card create --board BOARD_ID --title "Card" --image "$SIGNED_ID"Inline image in description:
SGID=$(fizzy upload file image.png | jq -r '.data.attachable_sgid') cat > description.html << EOF <p>See image:</p> <action-text-attachment sgid="$SGID"></action-text-attachment> EOF fizzy card create --board BOARD_ID --title "Card" --description_file description.htmlNote: Each
attachable_sgidcan only be used once. Upload the file again if you need to attach it to multiple cards.
# Show your identity and all accessible accounts fizzy identity showInstall the Fizzy skill file for use with AI coding assistants like Claude Code or OpenCode.
fizzy skillThis interactive command lets you choose where to install the SKILL.md file:
| Location | Path |
|---|---|
| Claude Code (Global) | ~/.claude/skills/fizzy/SKILL.md |
| Claude Code (Project) | .claude/skills/fizzy/SKILL.md |
| OpenCode (Global) | ~/.config/opencode/skill/fizzy/SKILL.md |
| OpenCode (Project) | .opencode/skill/fizzy/SKILL.md |
| Other | Custom path of your choice |
The skill file enables AI assistants to understand and use Fizzy CLI commands effectively.
Command results output JSON. (--help and --version output plain text.)
{ "success": true, "data": { ... }, "meta": { "timestamp": "2025-12-10T10:00:00Z" } }When creating resources, the CLI automatically follows the Location header to fetch the complete resource data:
{ "success": true, "data": { "id": "abc123", "number": 42, "title": "New Card", "status": "published" }, "location": "https://app.fizzy.do/account/cards/42", "meta": { "timestamp": "2025-12-10T10:00:00Z" } }Errors return a non-zero exit code and structured error info:
{ "success": false, "error": { "code": "NOT_FOUND", "message": "Card not found", "status": 404 } }| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Invalid arguments |
| 3 | Authentication failure |
| 4 | Permission denied |
| 5 | Not found |
| 6 | Validation error |
| 7 | Network error |
List commands return paginated results. Use --page to fetch specific pages or --all to fetch everything:
fizzy card list --page 2 fizzy card list --allgo build -o bin/fizzy ./cmd/fizzyUnit tests (no API credentials required):
make test-unitE2E tests (requires live API credentials):
# Set required environment variables export FIZZY_TEST_TOKEN=your-api-token export FIZZY_TEST_ACCOUNT=your-account-slug # Build and run e2e tests make test-e2eRun a specific e2e test:
make test-run NAME=TestBoardCRUDMIT