@raw-works/fizzy-cli

CLI for Fizzy - designed for AI agents like Claude Code

Manage your Fizzy boards, cards, and workflows from the terminal or through AI agents. Fully agent-friendly with non-interactive authentication, JSON output, and comprehensive API coverage.

🚀 Quick Start

No installation required - use bunx or npx:

``bash


List your boards (with bunx - fastest!)

bunx @raw-works/fizzy-cli boards list

Create a card (with npx)

npx @raw-works/fizzy-cli cards create --board --title "Ship it!"

Or install globally

npm install -g @raw-works/fizzy-cli
fizzy boards list
`

⚡️ Installation

Choose your preferred method:

$3

`bash


Bun's npx equivalent - much faster:

bunx @raw-works/fizzy-cli

Example: create a card

bunx @raw-works/fizzy-cli cards create --board abc123 --title "New card"
`

$3

`bash


Run any command without installing:

npx @raw-works/fizzy-cli

Example: list boards

npx @raw-works/fizzy-cli boards list
`

$3

`bash


Install once, use everywhere:

npm install -g @raw-works/fizzy-cli

Now just use 'fizzy':

fizzy boards list
fizzy cards create --board abc123 --title "New card"
`

$3

`bash


Add to your project:

npm install @raw-works/fizzy-cli

Use via package.json scripts or npx:

npx fizzy boards list
`

💡 Why This CLI?

- ✅ 100% API Coverage - All 55 Fizzy endpoints supported
- ✅ Zero Config - Works with npx, no setup needed
- ✅ Type Safe - Built with TypeScript, validated with Zod
- ✅ Battle Tested - 293 tests, dogfooded daily
- ✅ Rich Features - File uploads, search, filters, retries, confirmations
- ✅ Great DX - Markdown support, templates, auto-complete ready
- ✅ Multi-Account - Switch between Fizzy accounts seamlessly
- ✅ Scriptable - JSON output for automation

🎯 Features

$3

- Boards: Create, list, update, delete boards
- Cards: Full lifecycle management - create, update, move, close, reopen, postpone, triage
- Columns: Organize your board workflows
- Steps: Checklists and todos for cards
- Comments: Discuss and collaborate
- Reactions: React with emojis
- Tags: Organize and filter
- Users: Manage team members
- Notifications: Stay updated

$3

- 📁 File Uploads: Card images, user avatars
- 🔍 Search & Filter: Advanced filtering, sorting, date ranges
- 📝 Rich Text: Markdown support with templates (bug, feature, task)
- ✅ Validation: Client-side validation for better error messages
- 🔄 Retries: Automatic retry with exponential backoff
- ⚠️ Confirmations: Prevent accidents with delete confirmations
- 📄 Pagination: Handle large datasets efficiently
- 🎨 Beautiful Output: Tables, colors, spinners

Quick Start

$3

The easiest way to authenticate is using a Personal Access Token (PAT):

`bash
fizzy auth login
`

This will guide you through:
1. Visit https://app.fizzy.do/my/access_tokens
2. Create a token with "Read + Write" permission
3. Paste the token when prompted

Your token is stored securely in ~/.fizzy-cli/tokens.json.

Alternatively, use magic link authentication:

`bash
fizzy auth login --magic-link your@email.com
`

$3

`bash
fizzy boards list
`

$3

`bash
fizzy cards create --board --title "My first CLI card" --description "Created from fizzy-cli!"
`

$3

`bash
fizzy --help
fizzy boards --help
fizzy cards --help
`

Configuration

$3

- FIZZY_BASE_URL: Override the default Fizzy API URL (default: https://app.fizzy.do)

$3

Tokens are stored in ~/.fizzy-cli/tokens.json with the following structure:

`json
{
"accounts": [
{
"account_slug": "your-account",
"account_name": "Your Account",
"access_token": "your_token_here",
"user": {
"id": "user_id",
"name": "Your Name",
"email_address": "your@email.com",
"role": "owner"
}
}
],
"defaultAccount": "your-account"
}
`

$3

fizzy-cli supports multiple accounts. You can:

`bash


List all accounts

fizzy auth accounts

Switch default account

fizzy auth switch another-account

Use specific account for a command

fizzy boards list --account another-account
`

Command Overview

All commands support --json for JSON output and --account for multi-account usage.

$3

- fizzy auth login - Authenticate with PAT or magic link
- fizzy auth logout - Remove stored credentials
- fizzy auth status - Show authentication status
- fizzy auth accounts - List all authenticated accounts
- fizzy auth switch - Switch default account

$3

- fizzy boards list - List all boards
- fizzy boards get - Get board details
- fizzy boards create - Create a new board
- fizzy boards update - Update board properties
- fizzy boards delete - Delete a board

$3

- fizzy cards list - List cards with filters
- fizzy cards get - Get card details
- fizzy cards create - Create a new card
- fizzy cards update - Update card properties
- fizzy cards delete - Delete a card
- fizzy cards close - Close a card
- fizzy cards reopen - Reopen a closed card
- fizzy cards move - Move card to column
- fizzy cards postpone - Postpone card (Not Now)
- fizzy cards triage - Send card to triage
- fizzy cards tag - Add/remove tags
- fizzy cards assign - Assign/unassign users
- fizzy cards watch - Watch a card
- fizzy cards unwatch - Unwatch a card

$3

- fizzy columns list --board - List board columns
- fizzy columns get --board - Get column details
- fizzy columns create --board --name - Create column
- fizzy columns update --board - Update column
- fizzy columns delete --board - Delete column

$3

- fizzy steps list --card - List card steps
- fizzy steps get --card - Get step details
- fizzy steps create --card --content - Create step
- fizzy steps update --card - Update step
- fizzy steps delete --card - Delete step

$3

- fizzy comments list - List card comments
- fizzy comments get - Get comment details
- fizzy comments create --body - Create comment
- fizzy comments update --body - Update comment
- fizzy comments delete - Delete comment

$3

- fizzy reactions list --card --comment - List reactions
- fizzy reactions create --card --comment --content - Add reaction
- fizzy reactions delete --card --comment - Remove reaction

$3

- fizzy tags list - List all tags

$3

- fizzy users list - List all users
- fizzy users get - Get user details
- fizzy users me - Get current user profile
- fizzy users update - Update user details
- fizzy users deactivate - Deactivate a user

$3

- fizzy notifications list - List notifications
- fizzy notifications read - Mark as read
- fizzy notifications unread - Mark as unread
- fizzy notifications mark-all-read - Mark all as read

Documentation

- Complete Command Reference - Detailed documentation for every command
- Usage Examples - Real-world examples and workflows
- Troubleshooting Guide - Common issues and solutions
- Contributing Guide - How to contribute to fizzy-cli

Development

$3

`bash


Run in development mode

bun run dev

Build the project

bun run build

Type checking

bun run typecheck

Run tests

bun test
`

$3

This project has comprehensive test coverage across multiple layers:

#### Unit Tests

Run the unit test suite:
`bash
bun test
`

Tests are located in src/commands/__tests__/ and cover individual commands and utilities.

#### Smoke Tests

Basic CLI functionality tests:
`bash
./scripts/smoke-test.sh
`

Verifies all commands are accessible and display help correctly.

#### E2E Tests

End-to-end integration tests:
`bash
bun test src/commands/__tests__/e2e.test.ts
`

Tests complete workflows and command interactions.

#### Dogfooding Tests (Optional)

Test against a real Fizzy instance:
`bash
export FIZZY_TOKEN="your_token"
export FIZZY_BASE_URL="https://app.fizzy.do"
./scripts/dogfood-test.sh
`

Security Note: Never commit credentials. Use environment variables or GitHub Secrets in CI/CD.

$3

All commits are scanned for leaked credentials using gitleaks:
`bash
gitleaks detect --no-git --verbose
`

Configuration: .gitleaks.toml

Project Structure

`
fizzy-cli/
├── src/
│ ├── index.ts # Main entry point
│ ├── cli.ts # CLI setup with Commander
│ ├── commands/ # Command implementations
│ │ ├── auth.ts # Authentication commands
│ │ ├── boards.ts # Board management
│ │ ├── cards.ts # Card management
│ │ ├── columns.ts # Column management
│ │ ├── steps.ts # Step/checklist management
│ │ ├── comments.ts # Comment management
│ │ ├── reactions.ts # Reaction management
│ │ ├── tags.ts # Tag listing
│ │ ├── users.ts # User management
│ │ └── notifications.ts # Notification management
│ ├── lib/
│ │ ├── api/ # API client and utilities
│ │ ├── auth/ # Authentication utilities
│ │ └── output/ # Output formatting utilities
│ ├── middleware/ # Command middleware (auth, validation)
│ ├── schemas/ # Zod schemas for API validation
│ └── types/ # TypeScript type definitions
├── docs/ # Documentation
├── scripts/ # Build and test scripts
├── package.json
└── tsconfig.json
`

Automated Updates

This CLI stays in sync with the upstream Fizzy repository through:

$3

A GitHub Actions workflow runs every night at 2 AM UTC to:
1. Check for updates in the fizzy-api submodule
2. Update to the latest commit from upstream
3. Run comprehensive tests:
- Type checking
- Unit tests
- CLI smoke tests
4. Create a pull request if updates are available and tests pass

The workflow can also be triggered manually via the Actions tab.

Examples

$3

`bash
fizzy cards create \
--board abc123 \
--title "Design mockup review" \
--description "Please review the new homepage design" \
--image ./mockup.png
`

$3

`bash


Show only closed cards

fizzy cards list --status closed

Show cards with specific tag

fizzy cards list --tag tag-id-here
`

$3

`bash


Tag cards in a loop


for card in 42 43 44; do
fizzy cards tag $card --add "urgent"
done
`

$3

`bash


Parse JSON with jq


fizzy boards list --json | jq '.[] | select(.name | contains("Design"))'
`

$3

`bash
fizzy cards watch 42
`

$3

`bash
fizzy users update --avatar ./profile.jpg
``

For more examples, see docs/EXAMPLES.md.

Changelog

See CHANGELOG.md for version history and release notes.

License

ISC

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

Support

- Issues: GitHub Issues
- Fizzy API Documentation: fizzy-api/docs/API.md