Fizzy CLI

A Ruby command-line client for Fizzy project management.

Install

Requires Ruby >= 3.2.

gem install fizzy

AI Agent Skill

Fizzy CLI ships with a skill file that teaches AI coding assistants (Claude Code, Codex) how to use the CLI. Install it so agents can manage your Fizzy boards and cards autonomously.

fizzy skill install                          # Claude Code, user-level (default)
fizzy skill install --target codex           # OpenAI Codex / OpenCode
fizzy skill install --target all             # All supported agents
fizzy skill install --scope project          # Project-level instead of user-level
fizzy skill uninstall                        # Remove skill file

Authentication

Getting a Personal Access Token

1. Log in to app.fizzy.do
2. Open your profile settings (click your avatar)
3. Scroll to the Developer section
4. Click personal access tokens
5. Create a new token and copy it

Logging in

fizzy auth login --token YOUR_TOKEN

For self-hosted Fizzy instances, pass --url:

fizzy auth login --token YOUR_TOKEN --url https://fizzy.mycompany.com

The URL is stored per-account in ~/.config/fizzy-cli/tokens.yml. You can also set FIZZY_TOKEN as an environment variable with --account to skip the file.

fizzy auth status     # Show current auth
fizzy auth accounts   # List available accounts
fizzy auth switch SLUG  # Change default account

Project Configuration

Set project-level defaults so you don't need --account and --board on every command:

fizzy init

This creates a .fizzy.yml in the current directory:

account: acme
board: b1

For self-hosted instances, add a url key:

account: acme
board: b1
url: https://fizzy.mycompany.com

Resolution priority (highest wins):

1. CLI flag (--account / --board)
2. .fizzy.yml (nearest ancestor directory)
3. Global default_account from ~/.config/fizzy-cli/tokens.yml

Usage

All commands support --json for JSON output and --account SLUG to override the default account.

# Use a different account
fizzy cards list --board BOARD_ID --account my-other-team

Boards

fizzy boards list
fizzy boards get BOARD_ID
fizzy boards create "My Board"
fizzy boards update BOARD_ID --name "New Name"
fizzy boards delete BOARD_ID

Cards

Cards are addressed by number (not ID).

fizzy cards list
fizzy cards list --board BOARD_ID --status open
fizzy cards get 42
fizzy cards create "Card title" --board BOARD_ID
fizzy cards update 42 --title "New title"
fizzy cards delete 42

Card actions:

fizzy cards close 42
fizzy cards reopen 42
fizzy cards not-now 42
fizzy cards triage 42 --column COLUMN_ID
fizzy cards untriage 42
fizzy cards tag 42 "bug"
fizzy cards assign 42 USER_ID
fizzy cards watch 42
fizzy cards unwatch 42
fizzy cards golden 42
fizzy cards ungolden 42

Columns

Columns are scoped to a board.

fizzy columns list --board BOARD_ID
fizzy columns get COLUMN_ID --board BOARD_ID
fizzy columns create "To Do" --board BOARD_ID
fizzy columns update COLUMN_ID --board BOARD_ID --name "Done"
fizzy columns delete COLUMN_ID --board BOARD_ID

Steps

Steps are scoped to a card (no list endpoint; steps appear in cards get).

fizzy steps create "Write tests" --card 42
fizzy steps get STEP_ID --card 42
fizzy steps update STEP_ID --card 42 --completed
fizzy steps delete STEP_ID --card 42

Comments

fizzy comments list --card 42
fizzy comments get COMMENT_ID --card 42
fizzy comments create "Looks good" --card 42
fizzy comments update COMMENT_ID --card 42 --body "Updated"
fizzy comments delete COMMENT_ID --card 42

Reactions

Works on cards and comments.

fizzy reactions list --card 42
fizzy reactions list --card 42 --comment COMMENT_ID
fizzy reactions create "thumbsup" --card 42
fizzy reactions delete REACTION_ID --card 42

Tags, Users, Notifications, Pins

fizzy tags list
fizzy users list
fizzy users get USER_ID
fizzy notifications list
fizzy notifications read NOTIFICATION_ID
fizzy notifications mark-all-read
fizzy pins pin 42
fizzy pins unpin 42

Other

fizzy auth identity   # Show current user info
fizzy version    # Print version
fizzy help       # List all commands

Error Handling

begin
  # any fizzy command
rescue Fizzy::AuthError => e
  # 401 - invalid or expired token
rescue Fizzy::ForbiddenError => e
  # 403 - insufficient permissions
rescue Fizzy::NotFoundError => e
  # 404 - resource not found
rescue Fizzy::ValidationError => e
  # 422 - invalid input
rescue Fizzy::RateLimitError => e
  # 429 - too many requests, retry with backoff
rescue Fizzy::ServerError => e
  # 500+ - server error
rescue Fizzy::NetworkError => e
  # Timeout or connection failure
end

Configuration

Source	Purpose
.fizzy.yml	Per-project account, board, and URL defaults
~/.config/fizzy-cli/tokens.yml	Stored auth tokens, default account, and per-account URL
FIZZY_TOKEN env var	Token override (requires --account)
FIZZY_URL env var	Instance URL override (default: https://app.fizzy.do)

URL resolution priority (highest wins):

1. FIZZY_URL environment variable
2. url in .fizzy.yml
3. Per-account url from tokens.yml (set via fizzy auth login --url)
4. Default: https://app.fizzy.do

Development

bundle install
bundle exec rake        # runs tests + rubocop
bundle exec rake test   # tests only
bundle exec rubocop     # lint only

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/dpaluy/fizzy-cli.

License

The gem is available as open source under the terms of the MIT License.