Fizzy CLI + Agent Skill

Fizzy CLI is a Go command-line client for Fizzy, designed for both people and coding agents. Its gh-inspired noun/verb commands provide readable tables, complete JSON output, built-in jq filtering, Go templates, automatic pagination, per-host authentication, and direct access to the Fizzy API.

An optional agent skill teaches compatible coding agents how to operate Fizzy safely and efficiently. The repository also includes a benchmark harness for measuring agent performance with and without the skill.

This independent project is not affiliated with, endorsed by, or sponsored by 37signals. 37signals maintains a separate official Fizzy CLI.

Install the latest release on Linux or macOS:

curl -fsSL https://raw.githubusercontent.com/holsee/fizzy-cli/master/install.sh | sh

Or install it from Windows PowerShell:

irm https://raw.githubusercontent.com/holsee/fizzy-cli/master/install.ps1 | iex

Then confirm the installation, authenticate with a Fizzy personal access token, and list your boards:

fizzy version
fizzy auth login --account YOUR_ACCOUNT
fizzy auth status
fizzy board list

fizzy auth login prompts for the token, verifies it against Fizzy, and stores the credentials for the selected host.

Precompiled releases support:

The installers verify the release checksum and do not require administrator privileges. By default, they install to ~/.local/bin on Linux and macOS and %LOCALAPPDATA%\Programs\fizzy\bin on Windows. If that directory is not on PATH, the installer prints the required change.

Set FIZZY_INSTALL_DIR to choose another directory. Set FIZZY_VERSION to a release tag, such as v0.1.0, to install a specific version.

To inspect an installer before running it:

curl -fsSLO https://raw.githubusercontent.com/holsee/fizzy-cli/master/install.sh
less install.sh
sh install.sh

irm https://raw.githubusercontent.com/holsee/fizzy-cli/master/install.ps1 -OutFile install.ps1
Get-Content ./install.ps1
./install.ps1

With Go 1.24 or later, install directly from source:

go install github.com/holsee/fizzy-cli/cmd/fizzy@latest

From a checkout:

go build -o fizzy ./cmd/fizzy

For local use, let the CLI prompt for a personal access token:

fizzy auth login --account YOUR_ACCOUNT
fizzy auth status

To read a token from a file or secret-manager command without placing it in shell history, use standard input:

fizzy auth login --account YOUR_ACCOUNT --with-token < token.txt

Keep token files out of source control and remove them when they are no longer needed.

For CI and agents, inject FIZZY_TOKEN, FIZZY_ACCOUNT, and optionally FIZZY_HOST. Environment tokens take precedence over stored credentials. Stored credentials use the OS user configuration directory, mode 0600 on POSIX systems, and the user profile's ACL on Windows.

Commands use a discoverable fizzy <resource> <action> structure:

# Find a board and its columns
fizzy board list
fizzy column list --board-name "Engineering"

# Find, create, and triage cards
fizzy card list --board-id 03f5v9zkft4hj9qq0lsn9ohcm --status maybe
fizzy card create --board-name "Engineering" --title "Ship the CLI"
fizzy card triage 42 --column-name "In Progress"

# Collaborate and clear notifications
fizzy comment create 42 --body "**Ready for review.**"
fizzy notification read-all

Run fizzy --help for the complete command tree or fizzy <resource> --help for resource-specific commands and examples. Generate Bash, Zsh, Fish, or PowerShell completion with fizzy completion SHELL; run fizzy completion --help for usage.

Use explicit selectors such as --board-id or --board-name, --user-id, --user-name, or --user-email, and --tag-id or --tag-title. IDs pass through unchanged; names, titles, and emails resolve by exact case-insensitive match. Compatibility aliases such as --board remain ID-only.

Repeat a selector flag to supply multiple literal values, including names containing commas. Columns also expose the pseudo-columns not-now/Not Now, maybe/Maybe?, and done/Done. Card listing maps these to the corresponding lane, while card triage dispatches them to postpone, untriage, or close.

Card descriptions and comment bodies accept Markdown by default and convert it to Fizzy's Action Text HTML. Headings, emphasis, links, lists, task lists, and fenced code blocks are mapped to the supported Action Text subset; tables degrade to preformatted text. Use --format html to pass Action Text HTML through unchanged or --format text to escape formatting characters. Markdown supplied with either explicit pass-through format produces a warning.

fizzy card create --board-name "Engineering" --title "Ship" --description $'## Plan\n\n- [ ] Verify release'
fizzy comment create 42 --body '<div><strong>Ready</strong></div>' --format html

For rich-text attachments, run fizzy upload FILE and insert the returned attachment_html into a description or comment. Markdown conversion preserves Action Text attachment tags; use --format html when exact pass-through is preferred. The similarly named signed_id is not the Action Text identifier.

Global flags include --host, --account, --json, --jq, and --template. Typed list commands fetch all pages automatically.

fizzy card list --json --jq '.[] | select(.golden) | {number, title}'
fizzy card view 42 --template '{{.number}}: {{.title}}{{"\n"}}'

Use fizzy api for endpoints that do not yet have typed commands. Account-relative paths omit the leading slash; global paths include it:

fizzy api cards --paginate
fizzy api cards/42 -X PUT -F 'card.title=New title'
fizzy api /my/identity

Typed commands cover the documented Fizzy API, including authentication, identity, account settings, boards, accesses and publications, columns, cards and lifecycle transitions, pins, steps, comments, reactions, tags, users, activities, notifications, exports, webhooks, and rich-text uploads. Raw API access provides forward compatibility when upstream adds endpoints.

The distributable fizzy agent skill contains a compact workflow guide and loads its full endpoint reference only when needed.

Install it with a GitHub CLI release that includes the preview gh skill commands:

gh skill install holsee/fizzy-cli fizzy
gh skill list

For example, install it for Codex at user scope so it is available across repositories:

gh skill install holsee/fizzy-cli fizzy --agent codex --scope user

You can also make skills/fizzy available manually by linking it to .agents/skills/fizzy in a repository or $HOME/.agents/skills/fizzy for personal use. Invoke the installed skill as $fizzy.

The separate fizzy-bench harness evaluates native Codex and Claude agents against ten containerized, state-graded Fizzy workflows, including a controlled skill-on/skill-off comparison. Benchmark maintainers can invoke $run-fizzy-benchmarks; its canonical instructions are in skills/run-fizzy-benchmarks.

Development requires Go 1.24 or later.

go fmt ./...
go test ./...
go vet ./...
go build ./cmd/fizzy

Releases use Go-compatible semantic version tags such as v0.1.0. A valid vMAJOR.MINOR.PATCH tag triggers the release workflow, which publishes checksum-protected archives for all supported platforms. A future v2 or later release must also add the matching /v2 suffix to the Go module and import paths.

Run fizzy version to display the CLI release and the Fizzy API revision used for compatibility testing. The API model is based on Fizzy's first-party docs/api documentation.

See the complete API test plan, its required run-report template, and the 2026-07-11 live API verification for the historical compatibility baseline and production findings.

Except for the logo, this project is dual-licensed under the MIT License or Apache License 2.0, at your option. Copyright (c) 2026 @holsee.

The project logo is a modified work inspired by the original Fizzy logo, copyright © 2025 37signals LLC, and is distributed separately under the terms and attribution in assets/LICENSE.md. This project is independent of and is not affiliated with, endorsed by, or sponsored by 37signals. No trademark permission is claimed or implied.