Fizzy CLI by jeremy · Pull Request #2358 · basecamp/fizzy

jeremy · 2026-01-13T18:12:28Z

Introduces fizzy, an agent-first CLI for Fizzy.

Fizzy CLI

Foundation: Entry point, config management, API client, OAuth auth flow
Queries: boards, cards, columns, people, tags, search, notifications, show
Actions: card create, close, reopen, triage, postpone, comment, assign, tag, watch, gild, step
Ergonomics: Name resolution, --in alias, multi-origin credential storage, pagination
Distribution: Install script, bash/zsh completions, README

Design Highlights

Agent-first: JSON envelopes with breadcrumbs, predictable patterns
Human-friendly: Markdown output in TTY, rich help text
Dependencies: Bash 4+, curl, jq
Builds on Minimal modern OAuth 2.1 stack #2296 for seamless auth

Test plan

All 256 bats tests pass (bats test/*.bats)
Smoke tested against http://fizzy.localhost:3006
OAuth flow works (browser and --no-browser modes)
Name resolution works across paginated endpoints
Card create chains follow-up actions (triage, tag, assign)

Agent-first CLI for Fizzy API interaction: - OAuth 2.1 with RFC 8414 discovery, DCR, and PKCE - 7-layer config hierarchy (system/user/repo/local/env/flags) - HTTP client with ETag caching and exponential backoff - JSON/Markdown output with auto-detection - 72 passing bats tests

Three improvements: 1. _wait_for_callback: Avoid SIGPIPE killing nc before HTTP response sent. The `nc | head -1` pipe causes head to close stdin after reading one line, sending SIGPIPE to nc before it finishes writing the response. Now captures nc output to temp file before reading with head. 2. _exchange_code: Only include client_secret for confidential clients. Public clients (registered via DCR) have no secret, and sending an empty client_secret= parameter can cause some OAuth servers to reject the request. 3. _register_client: Request scope in DCR to ensure CLI gets proper permissions.

The symlink was pointing to $INSTALL_DIR/fizzy but the binary is at $INSTALL_DIR/bin/fizzy after extraction.

- Tag API returns .title not .name - fix resolve_tag_id matching - Strip leading # from tag input (users type #bug or bug) - Use api_get_all for boards/users/tags to fetch all pages - Use grep -iF in _suggest_similar to avoid regex errors on special characters like [ ] * Adds contract tests for tag resolution and regex handling.

The API only accepts title/description on POST /cards. Flags like --column, --tag, and --assign were being silently ignored. Now chains follow-up API calls after card creation: - POST /cards/{n}/triage for --column - POST /cards/{n}/taggings for --tag - POST /cards/{n}/assignments for --assign Also strips leading # from tag names in fizzy tag --with.

Multi-origin setups (dev + prod) were sharing a global account_slug, causing mismatches when switching between instances. Now stores account_slug alongside access_token in per-origin credentials file, with fallback to global config for compatibility.

- boards, tags, people, notifications: add --page N pagination - search: add board name resolution via resolve_board_id - Consistent validation (positive integer required) - Breadcrumbs show next page command Adds pagination tests for all query commands.

Changed from standalone commands (fizzy edit-comment, fizzy delete-comment) to subcommands of comment (fizzy comment edit, fizzy comment delete). Usage: fizzy comment "text" --on <num> # Create comment (unchanged) fizzy comment edit <id> --on <num> "new text" # Update comment fizzy comment delete <id> --on <num> # Delete comment API: PATCH/DELETE /cards/:num/comments/:id Smoke test: fizzy comment edit --help; fizzy comment delete --help

fizzy delete <number> [numbers...] Permanently deletes cards. Shows warning in help that action cannot be undone. API: DELETE /cards/:number (returns 204 No Content) Smoke test: fizzy delete --help

fizzy delete-image <number> removes the header image from a card. Uses DELETE /cards/:number/image (returns 204), then fetches the card to show updated state.

Card update: wrap params in {card: {...}} as Rails expects params[:card] Comment edit: Rails returns 204 No Content on PATCH, so fetch the updated comment after to get its current state for display.

Steps: - Add --completed flag to step create - Add step show/update/delete subcommands - Fix body wrapper to {step: {...}} as Rails expects Reactions: - Add fizzy reactions --card <num> --comment <id> to list reactions - Add fizzy react delete <id> --card <num> --comment <id> - Update fizzy react to manage reactions (add + delete) All commands follow existing subcommand patterns (like comment edit/delete). Shell completions updated for new subcommands.

Identity & Users: - fizzy identity: show current user and accounts - fizzy user show/update/delete: manage users - User avatar upload via multipart form Card Images: - --image flag on card create and card update - Multipart upload with retry/backoff for 429/5xx - Use --form-string for non-file fields (prevents @-prefix hazard) Auth & Config: - FIZZY_URL convenience var (extracts base URL + account slug) - Allow re-login without logout - Improved token and scope handling Reliability: - api_multipart_request helper with retry logic - Regression test for --form-string usage 387 tests passing, smoke tested against live server.

Adds Jbuilder views for index, show, and create actions.

Internal endpoints (Tier 3) - functional but intentionally undocumented.

- Fix card create/update params (remove status, tag_ids) - Fix card move request shape (top-level board_id) - Fix board update request (top-level user_ids) - Fix comment update response (204 No Content) - Fix column reordering paths (shallow routes) - Add 429 to error codes table - Add endpoint-specific error table - Add API docs maintenance micro-skill - Align webhook actions with PERMITTED_ACTIONS

Documents API↔CLI coverage and intentional omissions (pins, involvement).

- fizzy webhooks: list webhooks - fizzy webhook create/show/update/delete - Align available actions with Webhook::PERMITTED_ACTIONS - Add assert_json_contains test helper - Add 17 webhook tests including action list lock tests

- fizzy account show/update/entropy/join-code/export - Export accepts HTTP 202 for async operations

- fizzy --version / -V / version: show installed version - fizzy self-update: update CLI from GitHub - fizzy self-update --check: check without installing - Add VERSION file for semver tracking - Add 9 tests for version and self-update

- fizzy board publish: publish board publicly with shareable URL - fizzy board unpublish: remove public access - fizzy board entropy: set auto-postpone period - Use publish response URL correctly

- fizzy user role: change user role (owner/admin/member)

- fizzy card publish: publish draft card - fizzy card move --to: move card to different board

- Add webhooks, account to help topics - Update command listings for new subcommands

- Fix unbound variable EXIT_API_ERROR (was EXIT_API) - Guard against self-update in git checkouts (suggest git pull) - Guard against non-writable FIZZY_ROOT (suggest brew upgrade) - Add tests for git checkout detection

Version tracking changes: - Remove VERSION file (no manual version bumping) - Install script fetches latest commit SHA from GitHub API - Write commit SHA to .commit file during install - Display version as "fizzy main (abc1234)" format - self-update compares commits instead of version strings Uninstall command: - fizzy uninstall shows what will be removed - fizzy uninstall --force removes installation and symlinks - Guards for git checkout and Homebrew installs - Removes symlink from common bin directories

Install script improvements: - Support FIZZY_REPO, FIZZY_REF, FIZZY_COMMIT env vars for forks/CI - Try branch then tag when downloading (supports both refs/heads and refs/tags) - Gracefully handle GitHub API rate limits (commit SHA is best-effort) - Add 5s timeout to API calls to avoid hanging Self-update improvements: - --force now works even when GitHub API is unavailable - Better error messages suggesting --force when rate-limited - Re-try commit SHA fetch after download in _perform_update - Fall back to branch name in .commit if SHA unavailable - Use FIZZY_BRANCH in status messages instead of hardcoded "main"

Copilot

Pull request overview

Introduces a new fizzy Bash-based CLI (agent-first, JSON envelope by default when non-TTY) and extends several Rails controllers with JSON responses to support the CLI’s API usage patterns (including webhooks and assorted “tier 3” endpoints).

Changes:

Add a full Bash CLI implementation (cli/bin/fizzy, core libs, commands, installer, completions) plus an extensive bats test suite.
Add/extend JSON responses across multiple Rails controllers (e.g., board publication, involvements, exports, roles) and add Jbuilder views for webhooks JSON.
Add/extend Rails tests to cover JSON response behavior for selected endpoints.

Reviewed changes

Copilot reviewed 58 out of 60 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
test/controllers/cards/pins_controller_test.rb	Adds additional JSON-mode tests for pin/unpin behavior (currently duplicates existing tests).
test/controllers/boards/publications_controller_test.rb	Adds JSON publish/unpublish tests including returned key/url.
test/controllers/boards/involvements_controller_test.rb	Adds JSON update test expecting `204 No Content`.
cli/test/webhooks.bats	Adds bats coverage for webhook command help and validation.
cli/test/users.bats	Adds bats coverage for identity/user help + auth/config validation paths.
cli/test/test_helper.bash	Introduces common bats helpers (fixtures, JSON assertions, temp HOME/project).
cli/test/self_update.bats	Adds bats coverage for version/self-update/uninstall help and guard rails.
cli/test/run.sh	Adds a simple bats runner script for the CLI test suite.
cli/test/queries.bats	Adds bats coverage for tags/people/notifications help + pagination validation.
cli/test/names.bats	Adds contract + unit-ish tests for name resolution and caching helpers.
cli/test/core.bats	Adds bats coverage for core CLI behavior, flags, and `FIZZY_URL` parsing.
cli/test/config.bats	Adds bats coverage for layered config behavior and config command UX.
cli/test/cards.bats	Adds bats coverage for cards/show/search/people/tags/comments/notifications help + validation.
cli/test/boards.bats	Adds bats coverage for boards/board/columns/column help + validation.
cli/test/auth.bats	Adds bats coverage for auth status/logout/refresh, PKCE helpers, env token precedence.
cli/lib/names.sh	Implements board/user/column/tag name→ID resolution with caching + suggestions.
cli/lib/core.sh	Provides core output (JSON envelope/markdown), global flags, exit codes, utilities.
cli/lib/config.sh	Implements layered config + multi-origin credential/client/accounts storage.
cli/lib/commands/tags.sh	Implements `fizzy tags` query command with pagination/all-pages support.
cli/lib/commands/show.sh	Implements `fizzy show` dispatcher (board/card) with markdown rendering.
cli/lib/commands/self_update.sh	Implements `self-update` and `uninstall` flows (currently has runtime issues).
cli/lib/commands/search.sh	Implements `fizzy search` with board filtering and term encoding.
cli/lib/commands/people.sh	Implements `fizzy people` query with pagination/all-pages support.
cli/lib/commands/notifications.sh	Implements notifications list + read/unread actions.
cli/lib/commands/help.sh	Implements top-level help + quick start output; documents command taxonomy.
cli/lib/commands/config.sh	Implements `fizzy config` list/get/set/unset/path UX and rendering.
cli/lib/commands/comments.sh	Implements `comments` and `reactions` query commands + help/renderers.
cli/lib/commands/cards.sh	Implements `cards` query command and `show_card` rendering.
cli/install.sh	Adds curl-pipe installer for distributing the CLI.
cli/completions/fizzy.bash	Adds bash completion definitions (currently missing several commands).
cli/completions/_fizzy	Adds zsh completion definitions.
cli/bin/fizzy	Adds CLI entrypoint: loads libs/commands and dispatches subcommands.
cli/README.md	Documents install, output contract, commands, auth/config, name resolution, testing.
cli/PARITY.md	Documents API↔CLI parity/omissions (currently has a few mismatches with CLI surface).
app/views/webhooks/show.json.jbuilder	Adds JSON shape for webhook show.
app/views/webhooks/index.json.jbuilder	Adds JSON shape for webhook index.
app/views/webhooks/create.json.jbuilder	Adds JSON shape for webhook create.
app/controllers/webhooks_controller.rb	Adds JSON responses for create/update/destroy to support CLI automation.
app/controllers/users/roles_controller.rb	Adds JSON `204` response for role updates.
app/controllers/oauth/authorizations_controller.rb	Dynamically widens CSP `form-action` for valid redirect URIs during auth.
app/controllers/columns/right_positions_controller.rb	Adds JSON `204` response for column reorder.
app/controllers/columns/left_positions_controller.rb	Adds JSON `204` response for column reorder.
app/controllers/cards/publishes_controller.rb	Adds JSON `204` response for card publish.
app/controllers/boards/publications_controller.rb	Adds JSON responses for publish/unpublish (key/url + `204`).
app/controllers/boards/involvements_controller.rb	Adds JSON `204` response for involvement update.
app/controllers/boards/entropies_controller.rb	Adds JSON `204` response for entropy update.
app/controllers/account/settings_controller.rb	Adds JSON account summary response + JSON `204` for update.
app/controllers/account/join_codes_controller.rb	Adds JSON responses for join-code show/update/destroy.
app/controllers/account/exports_controller.rb	Adds JSON show + JSON create with `202 Accepted` and export summary.
app/controllers/account/entropies_controller.rb	Adds JSON `204` response for entropy update.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

adriantaut · 2026-02-26T08:03:17Z

Hello @jeremy , any chance this will be merged soon?

jeremy · 2026-03-04T19:56:29Z

We've adopted @robzolkos' Fizzy CLI officially! See https://github.com/basecamp/fizzy-cli

jeremy changed the base branch from main to oauth January 13, 2026 18:13

jeremy changed the title ~~Fizzy CLI and OAuth 2.1 support~~ Fizzy CLI Jan 13, 2026

jeremy force-pushed the cli branch 6 times, most recently from 1a49fb0 to 7770e22 Compare January 13, 2026 18:58

jeremy mentioned this pull request Jan 14, 2026

Fizzy CLI #2360

Closed

4 tasks

jeremy force-pushed the oauth branch from 2bbf396 to 0928831 Compare January 18, 2026 19:39

jeremy force-pushed the cli branch from 2dff42e to 7b3195f Compare January 22, 2026 07:55

jeremy mentioned this pull request Jan 23, 2026

Minimal MCP server for AI agent integration #2298

Closed

jeremy force-pushed the oauth branch from 0928831 to b3ba34c Compare February 19, 2026 22:05

jeremy added 17 commits February 19, 2026 14:06

Config command for settings management

68fa074

Query commands for boards, cards, and users

b033a0f

Card action commands

a84be17

Name resolution for fuzzy matching

761f20b

--in alias for --board flag

6ea9e09

README and tab completion

679a752

Multi-origin credential storage and install script

a934773

CSP validation for OAuth redirect_uri

1920161

Fix API response handling for RESTful patterns

5c23748

Pagination support for cards command

c33d8d6

Fix installer symlink path

1b3f417

The symlink was pointing to $INSTALL_DIR/fizzy but the binary is at $INSTALL_DIR/bin/fizzy after extraction.

jeremy added 23 commits February 19, 2026 14:06

Document env var auth path in help and status

4f52cdc

Add card delete command

2966db7

fizzy delete <number> [numbers...] Permanently deletes cards. Shows warning in help that action cannot be undone. API: DELETE /cards/:number (returns 204 No Content) Smoke test: fizzy delete --help

Add card image delete command

dac90a7

fizzy delete-image <number> removes the header image from a card. Uses DELETE /cards/:number/image (returns 204), then fetches the card to show updated state.

Fix API request/response handling

b950eb1

Card update: wrap params in {card: {...}} as Rails expects params[:card] Comment edit: Rails returns 204 No Content on PATCH, so fetch the updated comment after to get its current state for display.

Add JSON responders for webhooks controller

02b83d4

Adds Jbuilder views for index, show, and create actions.

Add JSON responders for pins, involvements, publications

8205c75

Internal endpoints (Tier 3) - functional but intentionally undocumented.

Add JSON responders for account, board, column, and role endpoints

22934c2

Add CLI parity matrix

3716604

Documents API↔CLI coverage and intentional omissions (pins, involvement).

Add webhook CLI commands

4118a0e

- fizzy webhooks: list webhooks - fizzy webhook create/show/update/delete - Align available actions with Webhook::PERMITTED_ACTIONS - Add assert_json_contains test helper - Add 17 webhook tests including action list lock tests

Add account CLI commands

7205b68

- fizzy account show/update/entropy/join-code/export - Export accepts HTTP 202 for async operations

Add self-update command and version tracking

a98e592

- fizzy --version / -V / version: show installed version - fizzy self-update: update CLI from GitHub - fizzy self-update --check: check without installing - Add VERSION file for semver tracking - Add 9 tests for version and self-update

Add board publish, unpublish, and entropy commands

8ea8338

- fizzy board publish: publish board publicly with shareable URL - fizzy board unpublish: remove public access - fizzy board entropy: set auto-postpone period - Use publish response URL correctly

Add user role command

b721e3e

- fizzy user role: change user role (owner/admin/member)

Add card publish and move commands

1fff982

- fizzy card publish: publish draft card - fizzy card move --to: move card to different board

Update help and API client for new commands

3764c39

- Add webhooks, account to help topics - Update command listings for new subcommands

Update CLI plan with complete command reference

a64cf2b

Fix self-update: EXIT_API_ERROR → EXIT_API, add safety guards

04b1ea6

- Fix unbound variable EXIT_API_ERROR (was EXIT_API) - Guard against self-update in git checkouts (suggest git pull) - Guard against non-writable FIZZY_ROOT (suggest brew upgrade) - Add tests for git checkout detection

jeremy force-pushed the cli branch from 7b3195f to 075b5b1 Compare February 19, 2026 22:07

Copilot AI review requested due to automatic review settings February 19, 2026 22:07

Copilot started reviewing on behalf of jeremy February 19, 2026 22:07 View session

Copilot AI reviewed Feb 19, 2026

View reviewed changes

jeremy closed this Mar 4, 2026

Navigation Menu

Uh oh!

Fizzy CLI - #2358

Fizzy CLI#2358
jeremy wants to merge 45 commits into
oauthfrom
cli

jeremy commented Jan 13, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

adriantaut commented Feb 26, 2026

Uh oh!

jeremy commented Mar 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

jeremy commented Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Fizzy CLI

Design Highlights

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

adriantaut commented Feb 26, 2026

Uh oh!

jeremy commented Mar 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jeremy commented Jan 13, 2026 •

edited

Loading