Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/basecamp--fizzy-cli/badge.svg)](/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

i

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.

  1. {
  2. "name": "fizzy",
  3. "version": "0.1.0",
  4. "description": "Fizzy integration for Claude Code. Manage boards, cards, track work, and link code to projects.",
  5. "author": {
  6. "name": "37signals",
  7. "email": "support@37signals.com"
  8. },
  9. "homepage": "https://github.com/basecamp/fizzy-cli",
  10. "repository": "https://github.com/basecamp/fizzy-cli",
  11. "license": "MIT"
  12. }
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.

  1. # <img src="assets/fizzy-badge.png" height="28" alt="Fizzy"> Fizzy CLI
  2. ```
  3. ⠀⡀⠄⠀⣤⣤⡄⠠⢠⣤⣤⠀⠄⣠⣤⣤⠀⠠⣠⣤⣄⠠⠀⣤⣤⡄⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀⠠⠀
  4. ⠀⠀⠄⢸⣿⣿⡇⠠⢸⣿⣿⡇⠀⣿⣿⡿⡇⢈⣿⣿⣿⠀⢸⣿⣿⡇⢀⠈⡀⢈⠀⡈⢀⠈⡀⢈⠀⡈⢀⠈⡀⢈⠀⡈⢀⠈⡀⢈⠀⡈⢀⠈⡀⢈⠀⡈⢀⠈⡀⢈⠀⡈⢀⠈⠠⠈⢀⠈⡀⢈⠀⡈⢀⠈⡀⢈⠀⡈⠠⠀
  5. ⠀⢁⠠⢸⣿⡿⡇⠀⢸⣿⡿⡇⠀⣿⣿⢿⡃⠠⣿⣿⣾⠀⢸⣿⣽⡇⠀⠠⠀⠄⠠⠀⣦⣦⣦⣦⣦⣦⣦⣦⣦⠀⢰⣾⣷⡦⠀⠄⠠⠀⠄⠠⠀⠄⠠⠀⠄⠠⠀⠄⠠⠀⠄⠐⢀⠈⡀⠠⠀⠄⠠⠀⠄⠠⠀⠄⠠⠀⠐⠀
  6. ⠀⠠⠀⢸⣿⣿⡇⠈⢸⣿⣿⡇⠀⣿⣿⣿⠇⢈⣿⣷⣿⠀⢸⣿⣽⡇⠀⠂⠐⠀⠂⡀⣿⣿⡟⠛⠛⠛⠛⠛⠛⠀⠄⠉⠉⢁⠀⠂⠐⠀⠂⠐⠀⠂⠐⠀⠂⠐⠀⠂⠐⠀⠂⠁⠠⠀⠄⠐⠀⠂⠐⠀⠂⠐⠀⠂⠐⠈⡀⠁
  7. ⠀⠂⠈⢸⣿⣯⡇⠠⢸⣿⣯⡇⠀⣿⣿⣾⡇⠐⣿⣯⣿⠀⢸⣿⣽⡇⠀⡁⢈⠀⡁⠀⣿⣿⡇⠀⠄⠂⠀⠂⠐⢀⢸⣿⣿⡇⠀⡁⣿⣿⣿⣿⣿⣿⣿⣿⡃⢈⠀⣿⣿⣿⣿⣿⣿⣿⣿⠅⠈⢿⣿⣿⡀⢁⠈⡀⣽⣿⣿⠃
  8. ⠀⡈⠠⢸⣿⡿⡇⠀⢸⣿⡿⡇⠀⣿⣿⣽⡆⠨⣿⣟⣿⠀⢸⣯⣿⡇⠀⠄⠠⠀⠄⠂⣿⣿⢷⣶⣶⣶⣷⣾⡆⢀⢸⣿⣻⡇⠀⡀⠉⡈⠁⣁⣵⣿⣿⠋⠀⠠⠀⢉⠈⢁⢁⣵⣿⡿⠋⠀⠐⠘⣿⣿⣧⠀⠄⢠⣿⣿⠎⠀
  9. ⠀⠠⠀⢸⣿⣿⡇⠈⢸⣿⣿⡇⠀⣿⣿⣻⡅⠐⠿⣿⠟⠀⢸⣿⣽⡇⠀⠂⠐⠀⠂⡀⣿⣿⡟⠛⠛⠋⠛⠛⠃⠀⢸⣟⣿⡇⠀⠄⠂⠠⣰⣾⣿⠟⠁⢀⠈⠠⠈⢀⢠⣰⣿⡿⠟⠀⡀⢁⠈⡀⠸⣿⣾⡇⢀⣿⣿⡟⠀⠄
  10. ⠀⠂⠈⠸⣿⣯⡇⠠⢸⣿⣯⡇⠀⣿⣿⢿⡃⠠⠀⡢⠀⡁⠘⣿⣽⡇⠀⡁⢈⠀⢁⠀⣿⣿⡇⠀⠐⠀⠂⠐⠀⡁⢸⣿⣟⡇⢀⠐⣠⣶⣿⡟⠃⢀⠐⠀⡐⢀⠈⣠⣾⣿⡗⠋⠀⠄⠠⠀⠄⠀⠂⢹⣿⣷⣼⣿⡿⠀⠐⠀
  11. ⠀⡈⢀⠁⠉⡏⠀⠠⢸⣿⡿⡇⠀⣿⣿⣿⠇⠀⠂⢜⠀⡀⠂⠉⡏⠀⠄⠠⠀⠐⢀⠀⣿⣿⡇⠀⡁⢈⠀⡁⠄⠠⢸⣿⣽⡇⠀⡀⣿⣿⣻⣿⣿⣿⣿⣿⡇⠀⢐⣿⣿⣷⣿⣿⣿⣿⣿⡇⢀⠁⡈⠀⢹⣿⣻⣽⠁⢀⠁⠄
  12. ⠀⠠⠀⠐⠀⡇⠈⡀⢸⣿⣿⡇⠀⠙⢻⠊⠠⠈⡀⢕⠀⠠⠐⠀⡇⠐⠀⠂⢈⠠⠀⠄⢀⠀⡀⠄⠠⠀⠄⠠⠀⠂⢀⠀⡀⠠⠀⠄⢀⠀⡀⠀⡀⠀⡀⠀⡀⠐⢀⠀⡀⠀⡀⠀⡀⠀⡀⠀⠄⠠⣀⣈⣸⣿⣿⠃⠀⠄⠐⠀
  13. ⠀⠐⠈⢀⠁⡇⠠⠀⠸⢿⡯⠃⢀⠁⢸⠀⠂⠠⠀⠪⠀⠐⠀⠁⡇⢀⠁⡈⢀⠠⠐⠀⠄⠠⠀⠄⠂⠐⠀⠂⡀⢁⠠⠀⠄⠐⠀⠂⠠⠀⠄⠂⠀⠂⠀⠂⡀⢈⠀⠠⠀⠂⠀⠂⠀⠂⠀⠂⠐⠰⣿⣿⠿⠟⠁⡀⠂⡀⠁⠄
  14. ⠀⢁⠈⢀⠠⠐⠀⡈⠠⠀⡀⠄⠠⠐⠀⠂⠁⠐⠀⠂⡈⢀⠁⠐⡀⠄⠠⠀⠄⢀⠐⠀⠂⠐⠀⠂⡀⢁⠈⡀⠄⠠⠀⠐⢀⠈⡀⢁⠐⢀⠐⠀⡁⢈⠀⡁⠀⠄⠐⠀⠂⠁⡈⢀⠁⡈⢀⠁⡈⢀⠀⡀⠄⠂⠁⠀⠄⠠⠈⠀
  15. ```
  16. `fizzy` is a command-line interface for [Fizzy](https://fizzy.do). Manage boards, cards, comments, and more from your terminal or through AI agents.
  17. - Works standalone or with any AI agent (Claude, Codex, Copilot, Gemini)
  18. - JSON output with breadcrumbs for easy navigation
  19. - Token authentication via personal access tokens
  20. - Includes agent skill and Claude plugin setup
  21. ## Quick Start
  22. ```bash
  23. curl -fsSL https://raw.githubusercontent.com/basecamp/fizzy-cli/master/scripts/install.sh | bash
  24. fizzy setup
  25. ```
  26. 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.
  27. Recommended first checks:
  28. ```bash
  29. fizzy doctor
  30. fizzy board list
  31. ```
  32. Use `fizzy doctor` any time you want a full health check of your install, config, auth, API connectivity, board context, and agent setup.
  33. <details>
  34. <summary>Other installation methods</summary>
  35. **Omarchy/Arch Linux (AUR):**
  36. ```bash
  37. yay -S fizzy-cli
  38. ```
  39. **Homebrew (macOS and Linux):**
  40. ```bash
  41. brew install --cask basecamp/tap/fizzy
  42. ```
  43. Release candidates are not published to Homebrew; they are available from [Releases](https://github.com/basecamp/fizzy-cli/releases).
  44. *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:
  45. ```bash
  46. brew tap basecamp/tap
  47. brew unlink fizzy-cli
  48. brew install --cask basecamp/tap/fizzy
  49. brew uninstall --formula --force fizzy-cli
  50. brew untap robzolkos/fizzy-cli
  51. ```
  52. `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.
  53. **Scoop (Windows):**
  54. ```bash
  55. scoop bucket add basecamp https://github.com/basecamp/homebrew-tap
  56. scoop install fizzy
  57. ```
  58. **Go install:**
  59. ```bash
  60. go install github.com/basecamp/fizzy-cli/cmd/fizzy@latest
  61. ```
  62. **Debian/Ubuntu:**
  63. ```bash
  64. curl -LO https://github.com/basecamp/fizzy-cli/releases/latest/download/fizzy-cli_VERSION_linux_amd64.deb
  65. sudo dpkg -i fizzy-cli_VERSION_linux_amd64.deb
  66. ```
  67. **Fedora/RHEL:**
  68. ```bash
  69. curl -LO https://github.com/basecamp/fizzy-cli/releases/latest/download/fizzy-cli_VERSION_linux_amd64.rpm
  70. sudo rpm -i fizzy-cli_VERSION_linux_amd64.rpm
  71. ```
  72. **Windows:** download `fizzy_VERSION_windows_amd64.zip` from [Releases](https://github.com/basecamp/fizzy-cli/releases), extract, and add `fizzy.exe` to your PATH.
  73. **GitHub Release:** download from [Releases](https://github.com/basecamp/fizzy-cli/releases).
  74. </details>
  75. ## Next Steps
  76. Start with a few common commands:
  77. ```bash
  78. fizzy board list
  79. fizzy card list
  80. fizzy card show 42
  81. fizzy search "authentication"
  82. fizzy comment create --card 42 --body "Looks good!"
  83. ```
  84. Then branch out as needed:
  85. ```bash
  86. fizzy board accesses --board ID # Show board access settings and users
  87. fizzy activity list --board ID # List recent board activity
  88. fizzy webhook deliveries --board ID WEBHOOK_ID
  89. fizzy user export-create USER_ID
  90. ```
  91. For the full command surface, run `fizzy commands --json` or read [`skills/fizzy/SKILL.md`](skills/fizzy/SKILL.md).
  92. ### Attachments
  93. Simple mode uses repeatable `--attach` and appends inline attachments to the end of card descriptions or comment bodies:
  94. ```bash
  95. fizzy card create --board ID --title "Bug report" --description "See attached" --attach screenshot.png
  96. fizzy comment create --card 42 --attach logs.txt
  97. fizzy comment create --card 42 --body_file comment.md --attach screenshot.png --attach trace.txt
  98. ```
  99. Advanced mode still works when exact placement matters:
  100. ```bash
  101. SGID=$(fizzy upload file screenshot.png --jq '.data.attachable_sgid')
  102. fizzy card create --board ID --title "Bug report" \
  103. --description "<p>See screenshot</p><action-text-attachment sgid=\"$SGID\"></action-text-attachment>"
  104. ```
  105. Use `signed_id` from `fizzy upload file` only for card header images via `--image`.
  106. ### Output Formats
  107. ```bash
  108. fizzy board list # JSON output
  109. fizzy board list --jq '.data[0].name' # Filter the JSON envelope (built-in, no external jq required)
  110. fizzy board list --quiet --jq '.[0].name' # Filter raw data without the envelope
  111. fizzy board list --jq '[.data[] | {id, name}]' # Extract specific fields
  112. ```
  113. `--jq` is for machine-readable JSON output. It implies `--json` and cannot be combined with `--styled`, `--markdown`, `--ids-only`, or `--count`.
  114. ### JSON Envelope
  115. Every command returns structured JSON:
  116. ```json
  117. {
  118. "ok": true,
  119. "data": [...],
  120. "summary": "5 boards",
  121. "breadcrumbs": [{"action": "show", "cmd": "fizzy board show <id>"}]
  122. }
  123. ```
  124. Breadcrumbs suggest next commands, making it easy for humans and agents to navigate.
  125. ## AI Agent Integration
  126. `fizzy` works with any AI agent that can run shell commands.
  127. **Claude Code:** `fizzy setup claude` — installs the Claude plugin from the marketplace and links the embedded Fizzy skill into Claude's skills directory.
  128. **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.
  129. **Agent discovery:** Every command supports `--help --agent` for structured help output. Use `fizzy commands --json` for the full command catalog.
  130. **Troubleshooting:** Run `fizzy doctor` for a read-only health check with remediation hints and next steps.
  131. ## Configuration
  132. ```
  133. ~/.config/fizzy/ # Global config
  134. ├── config.json # Named profiles (account, base URL, board)
  135. ├── config.yaml # Legacy/fallback settings
  136. └── credentials/ # Fallback token storage (when keyring unavailable)
  137. .fizzy.yaml # Per-repo (local config overrides global)
  138. ```
  139. Configuration priority (highest to lowest):
  140. 1. CLI flags (`--token`, `--profile`, `--api-url`, `--board`)
  141. 2. Environment variables (`FIZZY_TOKEN`, `FIZZY_PROFILE`, `FIZZY_API_URL`, `FIZZY_BOARD`)
  142. 3. Named profile settings (account, base URL, board from `config.json`)
  143. 4. Local project config (`.fizzy.yaml`)
  144. 5. Global config (`~/.config/fizzy/config.yaml` or `~/.fizzy/config.yaml`)
  145. `FIZZY_ACCOUNT` is accepted as a deprecated alias for `FIZZY_PROFILE`.
  146. A local `.fizzy.yaml` sets the account and the board. Its `api_url` and `token` decide
  147. where your credentials are sent, so they are ignored, with a warning, until you trust the
  148. file: read it, then run `fizzy config trust` in that directory. Trust covers those two
  149. settings as they are: if either changes, as a pull can change them, the file needs trusting
  150. again. `fizzy setup` trusts the local file it writes, and `fizzy config untrust` removes
  151. the trust.
  152. 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:
  153. ```bash
  154. fizzy auth login "$WALTER_TOKEN" --profile walter --account 1
  155. fizzy auth login "$AGENT_TOKEN" --profile walter-agent --account 1
  156. ```
  157. The commands store credentials under each profile name while routing both profiles to account `1`:
  158. ```json
  159. {
  160. "profiles": {
  161. "walter": {
  162. "base_url": "https://app.fizzy.do",
  163. "extra": { "account": "1" }
  164. },
  165. "walter-agent": {
  166. "base_url": "https://app.fizzy.do",
  167. "extra": { "account": "1" }
  168. }
  169. },
  170. "default_profile": "walter"
  171. }
  172. ```
  173. `FIZZY_NO_UPDATE_NOTIFIER=1` runs commands without update notifications.
  174. Inspect the effective config and precedence:
  175. ```bash
  176. fizzy config show
  177. fizzy config explain
  178. fizzy config explain --profile acme
  179. ```
  180. ## MCP server
  181. `fizzy mcp` runs an MCP (Model Context Protocol) server on stdin/stdout, serving Fizzy
  182. boards, columns, cards, comments, steps, tags, users, and your identity as tools
  183. backed by your signed-in account — the same credentials every other command uses. Register it with any MCP
  184. client as a stdio server:
  185. ```bash
  186. claude mcp add fizzy -- fizzy mcp # Claude Code
  187. fizzy mcp --writes # serve write actions too (pair with a Read+Write token)
  188. fizzy mcp --domains boards,cards # narrow the served tool surface
  189. ```
  190. Each domain is one gateway tool (`fizzy_identity`, `fizzy_boards`, `fizzy_columns`,
  191. `fizzy_cards`, `fizzy_comments`, `fizzy_steps`, `fizzy_tags`, `fizzy_users`); call an
  192. action named `describe` for any action's parameter schema. Read-only by default —
  193. `--writes` opts in. Listings with more pages come back as
  194. `{"data": ..., "next_page": N}` — pass the number back as the action's `page`
  195. parameter. Logs go to stderr — stdout carries the MCP wire protocol.
  196. ## Troubleshooting
  197. ```bash
  198. fizzy doctor # Full install/config/auth/API/agent health check
  199. fizzy doctor --profile acme # Check one saved profile explicitly
  200. fizzy doctor --all-profiles # Sweep every saved profile
  201. fizzy doctor --verbose # Include effective config details and timings
  202. fizzy doctor --json # Structured output for scripts and support
  203. ```
  204. Common follow-up commands:
  205. ```bash
  206. fizzy auth status
  207. fizzy config show
  208. fizzy config explain
  209. fizzy identity show
  210. fizzy board list
  211. fizzy setup
  212. fizzy setup claude
  213. fizzy skill install
  214. ```
  215. ## Development
  216. ```bash
  217. make build # Build binary
  218. make test-unit # Run unit tests (no API required)
  219. make e2e # Run owner-only CLI contract e2e suite
  220. make e2e-run NAME=TestBoardList
  221. ```
  222. E2E requirements:
  223. - `FIZZY_TEST_TOKEN`
  224. - `FIZZY_TEST_ACCOUNT`
  225. - optional: `FIZZY_TEST_API_URL`
  226. - optional: `FIZZY_TEST_BINARY`
  227. Useful local inspection modes:
  228. - `FIZZY_E2E_KEEP_FIXTURE=1 make e2e`
  229. - `FIZZY_E2E_TEARDOWN_DELAY=120 make e2e`
  230. ## License
  231. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.