basecamp/fizzy-cli/fizzy

/fizzy - Fizzy Workflow Command

Full CLI coverage: boards, cards, columns, comments, steps, reactions, tags, users, notifications, pins, webhooks, account settings, search, and board migration.

Agent Invariants

MUST follow these rules:

1. Cards use NUMBER, not ID — fizzy card show 42 uses the card number. Other resources use their id field.
2. Use built-in `--jq` for filtering to reduce token output — fizzy card list --jq '[.data[] | {number, title}]'. Never pipe to external jq — use --jq instead. --jq implies --json, no need to pass both.
3. Check breadcrumbs in responses for available next actions with pre-filled values.
4. Check for board context via .fizzy.yaml or --board flag before listing cards.
5. Use `fizzy doctor` for setup/config/auth issues before guessing — it is the primary read-only health check and includes remediation hints.
6. Rich text fields accept markdown or HTML — use repeatable --attach PATH for simple end-appended inline attachments, or embed <action-text-attachment> tags manually when exact placement matters.
7. Card description is a string, but comment body is a nested object — .description vs .body.plain_text.
8. Display the welcome message for new signups — When signup complete --name returns is_new_user: true, you MUST immediately display the welcome_message field prominently to the user. This is a one-time personal note from the CEO — if you skip it, the user will never see it.

Decision Trees

Finding Content

Need to find something?
├── Know the board? → fizzy card list --board <id>
├── Full-text search? → fizzy search "query"
├── Filter by status? → fizzy card list --indexed-by maybe|closed|not_now|golden|stalled
├── Filter by person? → fizzy card list --assignee <id>
├── Filter by time? → fizzy card list --created today|thisweek|thismonth
└── Cross-board? → fizzy search "query" (searches all boards)

Modifying Content

Want to change something?
├── Move to column? → fizzy card column <number> --column <id>
├── Change status? → fizzy card close|reopen|postpone <number>
├── Assign? → fizzy card assign <number> --user <id>
├── Comment? → fizzy comment create --card <number> --body "text"
├── Add step? → fizzy step create --card <number> --content "text"
└── Move to board? → fizzy card move <number> --to <board_id>

Quick Reference

Global Flags

All commands support these global flags unless noted otherwise:

Output format defaults to auto-detection: styled for TTY, JSON for pipes/non-TTY.

Pagination

List commands use --page for pagination and --limit for client-side truncation.

# Get first page (default)
fizzy card list --page 1
 
# Limit to N results
fizzy card list --limit 5
 
# Fetch ALL pages at once
fizzy card list --all

Note: --limit and --all cannot be used together.

IMPORTANT: The --all flag controls pagination only - it fetches all pages of results for your current filter. It does NOT change which cards are included. By default, card list returns only open cards. See Card Statuses for how to fetch closed or postponed cards.

Commands supporting --all and --page:

• board list
• board closed
• board postponed
• board stream
• card list
• comment list
• tag list
• user list
• notification list
• webhook list

Configuration

~/.config/fizzy/              # Global config (or ~/.fizzy/)
└── config.yaml               #   Token, account, API URL, default board
 
.fizzy.yaml                   # Per-repo config (committed to git)

Per-repo config: .fizzy.yaml

account: 123456789
board: 03foq1hqmyy91tuyz3ghugg6c

Priority (highest to lowest):

1. CLI flags (--token, --profile, --api-url, --board)
2. Environment variables (FIZZY_TOKEN, FIZZY_PROFILE, FIZZY_API_URL, FIZZY_BOARD)
3. Named profile settings (account, base URL, board from config.json)
4. Local project config (.fizzy.yaml)
5. Global config (~/.config/fizzy/config.yaml or ~/.fizzy/config.yaml)

Check context:

cat .fizzy.yaml 2>/dev/null || echo "No project configured"
fizzy config show
fizzy config explain

Setup:

fizzy setup                              # Interactive wizard
fizzy doctor                             # Full install/config/auth/API/agent health check
fizzy auth login TOKEN                   # Save token for current profile
fizzy auth login TOKEN --profile agent --account 1  # Separate identity on account 1
fizzy auth status                        # Check auth status
fizzy auth list                          # List all authenticated profiles
fizzy auth switch PROFILE                # Switch active profile
fizzy auth logout                        # Log out current profile
fizzy auth logout --all                  # Log out all profiles
fizzy identity show                      # Show profiles

Signup (New User or Token Generation)

Interactive:

fizzy signup                                    # Full interactive wizard

Step-by-step (for agents):

# Step 1: Request magic link
fizzy signup start --email user@example.com
# Returns: {"pending_authentication_token": "eyJ..."}
 
# Step 2: User checks email for 6-digit code, then verify
fizzy signup verify --code ABC123 --pending-token eyJ...
# Returns: {"session_token": "eyJ...", "requires_signup_completion": true/false}
# For existing users (requires_signup_completion=false), also returns: "accounts": [{"name": "...", "slug": "..."}]
 
# Step 3: Write the session token to a temp file to keep it out of the agent session
echo "eyJ..." > /tmp/fizzy-session && chmod 600 /tmp/fizzy-session
 
# Step 4a: New user — complete signup (session token via stdin)
fizzy signup complete --name "Full Name" < /tmp/fizzy-session
# Returns: {"token": "fizzy_...", "account": "slug"}
 
# Step 4b: Existing user — generate token for an account
fizzy signup complete --account SLUG < /tmp/fizzy-session
# Returns: {"token": "fizzy_...", "account": "slug"}
 
# Step 5: Clean up the temp file
rm /tmp/fizzy-session

Note: The user must check their email for the 6-digit code between steps 1 and 2. The session token is written to a temp file and piped via stdin to avoid exposing it in shell history or the agent's conversation context. Token is saved to the system credential store when available, with a config file as fallback. Profile and API URL are saved to ~/.config/fizzy/ (preferred) or ~/.fizzy/.

Welcome message for new users: When signup complete --name succeeds (new user), the response includes is_new_user: true and a welcome_message field. See Agent Invariant #7 — you MUST display it.

Response Structure

All responses follow this structure:

{
  "ok": true,
  "data": { ... },           // Single object or array
  "summary": "4 boards",     // Human-readable description
  "breadcrumbs": [ ... ],    // Contextual next actions (omitted when empty)
  "context": { ... },        // Location, pagination, and other context (omitted when empty)
  "meta": {
  }
}

Summary field formats:

List responses with pagination:

{
  "ok": true,
  "data": [ ... ],
  "summary": "10 cards (page 1)",
  "context": {
    "pagination": {
      "has_next": true,
      "next_url": "https://..."
    }
  }
}

Breadcrumbs (contextual next actions):

Responses include a breadcrumbs array suggesting what you can do next. Each breadcrumb has:

• action: Short action name (e.g., "comment", "close", "assign")
• cmd: Ready-to-run command with actual values interpolated
• description: Human-readable description

fizzy card show 42 --jq '.breadcrumbs'