fizzy-cli
Fizzy CLI and Agent Skills
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/basecamp/fizzy-cli with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/basecamp/fizzy-cli'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/basecamp--fizzy-cli)HTML
<a href="/listings/basecamp--fizzy-cli"><img src="/api/listings/basecamp--fizzy-cli/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
curl -fsSL https://raw.githubusercontent.com/basecamp/fizzy-cli/master/scripts/install.sh | bash fizzy setup
That's it. The installer detects your platform and architecture, downloads the right binary, and verifies checksums. The setup wizard then walks you through configuring your token, selecting your account, and optionally setting a default board.
Recommended first checks:
fizzy doctor fizzy board list
Use `fizzy doctor` any time you want a full health check of your install, config, auth, API connectivity, board context, and agent setup.
<details> <summary>Other installation methods</summary>
**Omarchy/Arch Linux (AUR):**
yay -S fizzy-cli
**Homebrew (macOS and Linux):**
brew install --cask basecamp/tap/fizzy
Release candidates are not published to Homebrew; they are available from [Releases](https://github.com/basecamp/fizzy-cli/releases).
*Upgrading from Fizzy 3.x:* 3.x was the `fizzy-cli` formula in the `robzolkos/fizzy-cli` tap. `brew update` points that tap at this cask, but Homebrew never taps a third-party tap for you — not during migration, and not from a fully-qualified `brew install` — so run `brew tap` yourself first:
brew tap basecamp/tap brew unlink fizzy-cli brew install --cask basecamp/tap/fizzy brew uninstall --formula --force fizzy-cli brew untap robzolkos/fizzy-cli
`brew unlink` first is required: a cask will not overwrite a `bin/fizzy` symlink owned by the formula, so installing the cask while the formula is still linked skips the binary and the later uninstall leaves no `fizzy` on your PATH. Recover with `brew reinstall --cask fizzy`. Note also that `brew migrate fizzy-cli`, which Homebrew suggests, is a no-op for a formula-to-cask move.
**Scoop (Windows):**
scoop bucket add basecamp https://github.com/basecamp/homebrew-tap scoop install fizzy
**Go install:**
go install github.com/basecamp/fizzy-cli/cmd/fizzy@latest
**Debian/Ubuntu:**
curl -LO https://github.com/basecamp/fizzy-cli/releases/latest/download/fizzy-cli_VERSION_linux_amd64.deb sudo dpkg -i fizzy-cli_VERSION_linux_amd64.deb
**Fedora/RHEL:**
curl -LO https://github.com/basecamp/fizzy-cli/releases/latest/download/fizzy-cli_VERSION_linux_amd64.rpm sudo rpm -i fizzy-cli_VERSION_linux_amd64.rpm
**Windows:** download `fizzy_VERSION_windows_amd64.zip` from [Releases](https://github.com/basecamp/fizzy-cli/releases), extract, and add `fizzy.exe` to your PATH.
**GitHub Release:** download from [Releases](https://github.com/basecamp/fizzy-cli/releases).
</details>
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/plugin.json · Manifest · 12 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- {
- "name": "fizzy",
- "version": "0.1.0",
- "description": "Fizzy integration for Claude Code. Manage boards, cards, track work, and link code to projects.",
- "author": {
- "name": "37signals",
- "email": "support@37signals.com"
- },
- "homepage": "https://github.com/basecamp/fizzy-cli",
- "repository": "https://github.com/basecamp/fizzy-cli",
- "license": "MIT"
- }
README.md · README · 307 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # <img src="assets/fizzy-badge.png" height="28" alt="Fizzy"> Fizzy CLI
- ```
- ⠀⡀⠄⠀⣤⣤⡄⠠⢠⣤⣤⠀⠄⣠⣤⣤⠀⠠⣠⣤⣄⠠⠀⣤⣤⡄⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀
- ⠀⠀⠄⢸⣿⣿⡇⠠⢸⣿⣿⡇⠀⣿⣿⡿⡇⢈⣿⣿⣿⠀⢸⣿⣿⡇⢀⠈⡀⢈⠀⡈⢀⠈⡀⢈⠀⡈⢀⠈⡀⢈⠀⡈⢀⠈⡀⢈⠀⡈⢀⠈⡀⢈⠀⡈⢀⠈⡀⢈⠀⡈⢀⠈⠠⠈⢀⠈⡀⢈⠀⡈⢀⠈⡀⢈⠀⡈⠠⠀
- ⠀⢁⠠⢸⣿⡿⡇⠀⢸⣿⡿⡇⠀⣿⣿⢿⡃⠠⣿⣿⣾⠀⢸⣿⣽⡇⠀⠠⠀⠄⠠⠀⣦⣦⣦⣦⣦⣦⣦⣦⣦⠀⢰⣾⣷⡦⠀⠄⠠⠀⠄⠠⠀⠄⠠⠀⠄⠠⠀⠄⠠⠀⠄⠐⢀⠈⡀⠠⠀⠄⠠⠀⠄⠠⠀⠄⠠⠀⠐⠀
- ⠀⠠⠀⢸⣿⣿⡇⠈⢸⣿⣿⡇⠀⣿⣿⣿⠇⢈⣿⣷⣿⠀⢸⣿⣽⡇⠀⠂⠐⠀⠂⡀⣿⣿⡟⠛⠛⠛⠛⠛⠛⠀⠄⠉⠉⢁⠀⠂⠐⠀⠂⠐⠀⠂⠐⠀⠂⠐⠀⠂⠐⠀⠂⠁⠠⠀⠄⠐⠀⠂⠐⠀⠂⠐⠀⠂⠐⠈⡀⠁
- ⠀⠂⠈⢸⣿⣯⡇⠠⢸⣿⣯⡇⠀⣿⣿⣾⡇⠐⣿⣯⣿⠀⢸⣿⣽⡇⠀⡁⢈⠀⡁⠀⣿⣿⡇⠀⠄⠂⠀⠂⠐⢀⢸⣿⣿⡇⠀⡁⣿⣿⣿⣿⣿⣿⣿⣿⡃⢈⠀⣿⣿⣿⣿⣿⣿⣿⣿⠅⠈⢿⣿⣿⡀⢁⠈⡀⣽⣿⣿⠃
- ⠀⡈⠠⢸⣿⡿⡇⠀⢸⣿⡿⡇⠀⣿⣿⣽⡆⠨⣿⣟⣿⠀⢸⣯⣿⡇⠀⠄⠠⠀⠄⠂⣿⣿⢷⣶⣶⣶⣷⣾⡆⢀⢸⣿⣻⡇⠀⡀⠉⡈⠁⣁⣵⣿⣿⠋⠀⠠⠀⢉⠈⢁⢁⣵⣿⡿⠋⠀⠐⠘⣿⣿⣧⠀⠄⢠⣿⣿⠎⠀
- ⠀⠠⠀⢸⣿⣿⡇⠈⢸⣿⣿⡇⠀⣿⣿⣻⡅⠐⠿⣿⠟⠀⢸⣿⣽⡇⠀⠂⠐⠀⠂⡀⣿⣿⡟⠛⠛⠋⠛⠛⠃⠀⢸⣟⣿⡇⠀⠄⠂⠠⣰⣾⣿⠟⠁⢀⠈⠠⠈⢀⢠⣰⣿⡿⠟⠀⡀⢁⠈⡀⠸⣿⣾⡇⢀⣿⣿⡟⠀⠄
- ⠀⠂⠈⠸⣿⣯⡇⠠⢸⣿⣯⡇⠀⣿⣿⢿⡃⠠⠀⡢⠀⡁⠘⣿⣽⡇⠀⡁⢈⠀⢁⠀⣿⣿⡇⠀⠐⠀⠂⠐⠀⡁⢸⣿⣟⡇⢀⠐⣠⣶⣿⡟⠃⢀⠐⠀⡐⢀⠈⣠⣾⣿⡗⠋⠀⠄⠠⠀⠄⠀⠂⢹⣿⣷⣼⣿⡿⠀⠐⠀
- ⠀⡈⢀⠁⠉⡏⠀⠠⢸⣿⡿⡇⠀⣿⣿⣿⠇⠀⠂⢜⠀⡀⠂⠉⡏⠀⠄⠠⠀⠐⢀⠀⣿⣿⡇⠀⡁⢈⠀⡁⠄⠠⢸⣿⣽⡇⠀⡀⣿⣿⣻⣿⣿⣿⣿⣿⡇⠀⢐⣿⣿⣷⣿⣿⣿⣿⣿⡇⢀⠁⡈⠀⢹⣿⣻⣽⠁⢀⠁⠄
- ⠀⠠⠀⠐⠀⡇⠈⡀⢸⣿⣿⡇⠀⠙⢻⠊⠠⠈⡀⢕⠀⠠⠐⠀⡇⠐⠀⠂⢈⠠⠀⠄⢀⠀⡀⠄⠠⠀⠄⠠⠀⠂⢀⠀⡀⠠⠀⠄⢀⠀⡀⠀⡀⠀⡀⠀⡀⠐⢀⠀⡀⠀⡀⠀⡀⠀⡀⠀⠄⠠⣀⣈⣸⣿⣿⠃⠀⠄⠐⠀
- ⠀⠐⠈⢀⠁⡇⠠⠀⠸⢿⡯⠃⢀⠁⢸⠀⠂⠠⠀⠪⠀⠐⠀⠁⡇⢀⠁⡈⢀⠠⠐⠀⠄⠠⠀⠄⠂⠐⠀⠂⡀⢁⠠⠀⠄⠐⠀⠂⠠⠀⠄⠂⠀⠂⠀⠂⡀⢈⠀⠠⠀⠂⠀⠂⠀⠂⠀⠂⠐⠰⣿⣿⠿⠟⠁⡀⠂⡀⠁⠄
- ⠀⢁⠈⢀⠠⠐⠀⡈⠠⠀⡀⠄⠠⠐⠀⠂⠁⠐⠀⠂⡈⢀⠁⠐⡀⠄⠠⠀⠄⢀⠐⠀⠂⠐⠀⠂⡀⢁⠈⡀⠄⠠⠀⠐⢀⠈⡀⢁⠐⢀⠐⠀⡁⢈⠀⡁⠀⠄⠐⠀⠂⠁⡈⢀⠁⡈⢀⠁⡈⢀⠀⡀⠄⠂⠁⠀⠄⠠⠈⠀
- ```
- `fizzy` is a command-line interface for [Fizzy](https://fizzy.do). Manage boards, cards, comments, and more from your terminal or through AI agents.
- - Works standalone or with any AI agent (Claude, Codex, Copilot, Gemini)
- - JSON output with breadcrumbs for easy navigation
- - Token authentication via personal access tokens
- - Includes agent skill and Claude plugin setup
- ## Quick Start
- ```bash
- curl -fsSL https://raw.githubusercontent.com/basecamp/fizzy-cli/master/scripts/install.sh | bash
- fizzy setup
- ```
- That's it. The installer detects your platform and architecture, downloads the right binary, and verifies checksums. The setup wizard then walks you through configuring your token, selecting your account, and optionally setting a default board.
- Recommended first checks:
- ```bash
- fizzy doctor
- fizzy board list
- ```
- Use `fizzy doctor` any time you want a full health check of your install, config, auth, API connectivity, board context, and agent setup.
- <details>
- <summary>Other installation methods</summary>
- **Omarchy/Arch Linux (AUR):**
- ```bash
- yay -S fizzy-cli
- ```
- **Homebrew (macOS and Linux):**
- ```bash
- brew install --cask basecamp/tap/fizzy
- ```
- Release candidates are not published to Homebrew; they are available from [Releases](https://github.com/basecamp/fizzy-cli/releases).
- *Upgrading from Fizzy 3.x:* 3.x was the `fizzy-cli` formula in the `robzolkos/fizzy-cli` tap. `brew update` points that tap at this cask, but Homebrew never taps a third-party tap for you — not during migration, and not from a fully-qualified `brew install` — so run `brew tap` yourself first:
- ```bash
- brew tap basecamp/tap
- brew unlink fizzy-cli
- brew install --cask basecamp/tap/fizzy
- brew uninstall --formula --force fizzy-cli
- brew untap robzolkos/fizzy-cli
- ```
- `brew unlink` first is required: a cask will not overwrite a `bin/fizzy` symlink owned by the formula, so installing the cask while the formula is still linked skips the binary and the later uninstall leaves no `fizzy` on your PATH. Recover with `brew reinstall --cask fizzy`. Note also that `brew migrate fizzy-cli`, which Homebrew suggests, is a no-op for a formula-to-cask move.
- **Scoop (Windows):**
- ```bash
- scoop bucket add basecamp https://github.com/basecamp/homebrew-tap
- scoop install fizzy
- ```
- **Go install:**
- ```bash
- go install github.com/basecamp/fizzy-cli/cmd/fizzy@latest
- ```
- **Debian/Ubuntu:**
- ```bash
- curl -LO https://github.com/basecamp/fizzy-cli/releases/latest/download/fizzy-cli_VERSION_linux_amd64.deb
- sudo dpkg -i fizzy-cli_VERSION_linux_amd64.deb
- ```
- **Fedora/RHEL:**
- ```bash
- curl -LO https://github.com/basecamp/fizzy-cli/releases/latest/download/fizzy-cli_VERSION_linux_amd64.rpm
- sudo rpm -i fizzy-cli_VERSION_linux_amd64.rpm
- ```
- **Windows:** download `fizzy_VERSION_windows_amd64.zip` from [Releases](https://github.com/basecamp/fizzy-cli/releases), extract, and add `fizzy.exe` to your PATH.
- **GitHub Release:** download from [Releases](https://github.com/basecamp/fizzy-cli/releases).
- </details>
- ## Next Steps
- Start with a few common commands:
- ```bash
- fizzy board list
- fizzy card list
- fizzy card show 42
- fizzy search "authentication"
- fizzy comment create --card 42 --body "Looks good!"
- ```
- Then branch out as needed:
- ```bash
- fizzy board accesses --board ID # Show board access settings and users
- fizzy activity list --board ID # List recent board activity
- fizzy webhook deliveries --board ID WEBHOOK_ID
- fizzy user export-create USER_ID
- ```
- For the full command surface, run `fizzy commands --json` or read [`skills/fizzy/SKILL.md`](skills/fizzy/SKILL.md).
- ### Attachments
- Simple mode uses repeatable `--attach` and appends inline attachments to the end of card descriptions or comment bodies:
- ```bash
- fizzy card create --board ID --title "Bug report" --description "See attached" --attach screenshot.png
- fizzy comment create --card 42 --attach logs.txt
- fizzy comment create --card 42 --body_file comment.md --attach screenshot.png --attach trace.txt
- ```
- Advanced mode still works when exact placement matters:
- ```bash
- SGID=$(fizzy upload file screenshot.png --jq '.data.attachable_sgid')
- fizzy card create --board ID --title "Bug report" \
- --description "<p>See screenshot</p><action-text-attachment sgid=\"$SGID\"></action-text-attachment>"
- ```
- Use `signed_id` from `fizzy upload file` only for card header images via `--image`.
- ### Output Formats
- ```bash
- fizzy board list # JSON output
- fizzy board list --jq '.data[0].name' # Filter the JSON envelope (built-in, no external jq required)
- fizzy board list --quiet --jq '.[0].name' # Filter raw data without the envelope
- fizzy board list --jq '[.data[] | {id, name}]' # Extract specific fields
- ```
- `--jq` is for machine-readable JSON output. It implies `--json` and cannot be combined with `--styled`, `--markdown`, `--ids-only`, or `--count`.
- ### JSON Envelope
- Every command returns structured JSON:
- ```json
- {
- "ok": true,
- "data": [...],
- "summary": "5 boards",
- "breadcrumbs": [{"action": "show", "cmd": "fizzy board show <id>"}]
- }
- ```
- Breadcrumbs suggest next commands, making it easy for humans and agents to navigate.
- ## AI Agent Integration
- `fizzy` works with any AI agent that can run shell commands.
- **Claude Code:** `fizzy setup claude` — installs the Claude plugin from the marketplace and links the embedded Fizzy skill into Claude's skills directory.
- **Other agents:** Point your agent at [`skills/fizzy/SKILL.md`](skills/fizzy/SKILL.md) for Fizzy workflow coverage. `fizzy skill` launches the interactive installer by default, while `fizzy skill install` installs the embedded skill directly.
- **Agent discovery:** Every command supports `--help --agent` for structured help output. Use `fizzy commands --json` for the full command catalog.
- **Troubleshooting:** Run `fizzy doctor` for a read-only health check with remediation hints and next steps.
- ## Configuration
- ```
- ~/.config/fizzy/ # Global config
- ├── config.json # Named profiles (account, base URL, board)
- ├── config.yaml # Legacy/fallback settings
- └── credentials/ # Fallback token storage (when keyring unavailable)
- .fizzy.yaml # Per-repo (local config overrides global)
- ```
- Configuration priority (highest to lowest):
- 1. CLI flags (`--token`, `--profile`, `--api-url`, `--board`)
- 2. Environment variables (`FIZZY_TOKEN`, `FIZZY_PROFILE`, `FIZZY_API_URL`, `FIZZY_BOARD`)
- 3. Named profile settings (account, base URL, board from `config.json`)
- 4. Local project config (`.fizzy.yaml`)
- 5. Global config (`~/.config/fizzy/config.yaml` or `~/.fizzy/config.yaml`)
- `FIZZY_ACCOUNT` is accepted as a deprecated alias for `FIZZY_PROFILE`.
- A local `.fizzy.yaml` sets the account and the board. Its `api_url` and `token` decide
- where your credentials are sent, so they are ignored, with a warning, until you trust the
- file: read it, then run `fizzy config trust` in that directory. Trust covers those two
- settings as they are: if either changes, as a pull can change them, the file needs trusting
- again. `fizzy setup` trusts the local file it writes, and `fizzy config untrust` removes
- the trust.
- Profiles created by `fizzy setup` use the account slug as their name and continue to work without changes. A profile can also use a distinct name by storing its account in the profile's `extra` settings. This supports separate credentials for multiple users of the same account:
- ```bash
- fizzy auth login "$WALTER_TOKEN" --profile walter --account 1
- fizzy auth login "$AGENT_TOKEN" --profile walter-agent --account 1
- ```
- The commands store credentials under each profile name while routing both profiles to account `1`:
- ```json
- {
- "profiles": {
- "walter": {
- "base_url": "https://app.fizzy.do",
- "extra": { "account": "1" }
- },
- "walter-agent": {
- "base_url": "https://app.fizzy.do",
- "extra": { "account": "1" }
- }
- },
- "default_profile": "walter"
- }
- ```
- `FIZZY_NO_UPDATE_NOTIFIER=1` runs commands without update notifications.
- Inspect the effective config and precedence:
- ```bash
- fizzy config show
- fizzy config explain
- fizzy config explain --profile acme
- ```
- ## MCP server
- `fizzy mcp` runs an MCP (Model Context Protocol) server on stdin/stdout, serving Fizzy
- boards, columns, cards, comments, steps, tags, users, and your identity as tools
- backed by your signed-in account — the same credentials every other command uses. Register it with any MCP
- client as a stdio server:
- ```bash
- claude mcp add fizzy -- fizzy mcp # Claude Code
- fizzy mcp --writes # serve write actions too (pair with a Read+Write token)
- fizzy mcp --domains boards,cards # narrow the served tool surface
- ```
- Each domain is one gateway tool (`fizzy_identity`, `fizzy_boards`, `fizzy_columns`,
- `fizzy_cards`, `fizzy_comments`, `fizzy_steps`, `fizzy_tags`, `fizzy_users`); call an
- action named `describe` for any action's parameter schema. Read-only by default —
- `--writes` opts in. Listings with more pages come back as
- `{"data": ..., "next_page": N}` — pass the number back as the action's `page`
- parameter. Logs go to stderr — stdout carries the MCP wire protocol.
- ## Troubleshooting
- ```bash
- fizzy doctor # Full install/config/auth/API/agent health check
- fizzy doctor --profile acme # Check one saved profile explicitly
- fizzy doctor --all-profiles # Sweep every saved profile
- fizzy doctor --verbose # Include effective config details and timings
- fizzy doctor --json # Structured output for scripts and support
- ```
- Common follow-up commands:
- ```bash
- fizzy auth status
- fizzy config show
- fizzy config explain
- fizzy identity show
- fizzy board list
- fizzy setup
- fizzy setup claude
- fizzy skill install
- ```
- ## Development
- ```bash
- make build # Build binary
- make test-unit # Run unit tests (no API required)
- make e2e # Run owner-only CLI contract e2e suite
- make e2e-run NAME=TestBoardList
- ```
- E2E requirements:
- - `FIZZY_TEST_TOKEN`
- - `FIZZY_TEST_ACCOUNT`
- - optional: `FIZZY_TEST_API_URL`
- - optional: `FIZZY_TEST_BINARY`
- Useful local inspection modes:
- - `FIZZY_E2E_KEEP_FIXTURE=1 make e2e`
- - `FIZZY_E2E_TEARDOWN_DELAY=120 make e2e`
- ## License
- [MIT](LICENSE)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.