CLI for Fizzy (https://fizzy.do) - designed for AI agents like Claude Code
npm install @raw-works/fizzy-cliCLI 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.
No installation required - use bunx or npx:
``bashList your boards (with bunx - fastest!)
bunx @raw-works/fizzy-cli 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-cliNow 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-cliUse 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, spinnersQuick 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 accountsSwitch default account
fizzy auth switch another-accountUse 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 - Get column details
- fizzy columns create --board - Create column
- fizzy columns update - Update column
- fizzy columns delete - Delete column$3
-
fizzy steps list --card - List card steps
- fizzy steps get - Get step details
- fizzy steps create --card - Create step
- fizzy steps update - Update step
- fizzy steps delete - Delete step$3
-
fizzy comments list - List card comments
- fizzy comments get - Get comment details
- fizzy comments create - Create comment
- fizzy comments update - Update comment
- fizzy comments delete - Delete comment$3
-
fizzy reactions list --card - List reactions
- fizzy reactions create --card - Add reaction
- fizzy reactions delete - 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 readDocumentation
- 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 devBuild the project
bun run buildType checking
bun run typecheckRun 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.tomlProject 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 passThe 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 closedShow 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.
See CHANGELOG.md for version history and release notes.
ISC
Contributions are welcome! Please see CONTRIBUTING.md for details.
- Issues: GitHub Issues
- Fizzy API Documentation: fizzy-api/docs/API.md