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 `` 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 
├── 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 
├── 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  --column 
├── Change status? → fizzy card close|reopen|postpone 
├── Assign? → fizzy card assign  --user 
├── Comment? → fizzy comment create --card  --body "text"
├── Add step? → fizzy step create --card  --content "text"
└── Move to board? → fizzy card move  --to 

Quick Reference

| Resource | List | Show | Create | Update | Delete | Other | |----------|------|------|--------|--------|--------|-------| | account | - | account show | - | account settings-update | - | account entropy, account export-create, account export-show EXPORT_ID, account join-code-show, account join-code-reset, account join-code-update | | identity | - | identity show | - | identity timezone-update --timezone NAME | - | - | | board | board list | board show ID | board create | board update ID | board delete ID | board accesses --board ID, board publish ID, board unpublish ID, board entropy ID, board closed, board postponed, board stream, board involvement ID, migrate board ID | | card | card list | card show NUMBER | card create | card update NUMBER | card delete NUMBER | card move NUMBER, card publish NUMBER, card mark-read NUMBER, card mark-unread NUMBER | | search | search QUERY | - | - | - | - | - | | activity | activity list | - | - | - | - | activity list --board ID, activity list --creator ID | | column | column list --board ID | column show ID --board ID | column create | column update ID | column delete ID | column move-left ID, column move-right ID | | comment | comment list --card NUMBER | comment show ID --card NUMBER | comment create | comment update ID | comment delete ID | comment attachments show --card NUMBER | | step | step list --card NUMBER | step show ID --card NUMBER | step create | step update ID | step delete ID | - | | reaction | reaction list | - | reaction create | - | reaction delete ID | - | | tag | tag list | - | - | - | - | - | | user | user list | user show ID | - | user update ID | - | user deactivate ID, user role ID, user avatar-remove ID, user export-create USER_ID, user export-show USER_ID EXPORT_ID, user email-change-request USER_ID --email user@example.com, user email-change-confirm USER_ID TOKEN, user push-subscription-create, user push-subscription-delete ID | | notification | notification list | - | - | - | - | notification tray, notification read-all, notification settings-show, notification settings-update | | pin | pin list | - | - | - | - | card pin NUMBER, card unpin NUMBER | | webhook | webhook list --board ID, webhook deliveries --board ID WEBHOOK_ID | webhook show ID --board ID | webhook create | webhook update ID | webhook delete ID | webhook reactivate ID |

---

Global Flags

All commands support these global flags unless noted otherwise:

| Flag | Description | |------|-------------| | --token TOKEN | API access token | | --profile NAME | Named profile (for multi-account users) | | --api-url URL | API base URL (default: https://app.fizzy.do) | | --jq EXPR | Built-in jq filter for machine-readable JSON output (no external jq required; implies --json, or filters raw data with --quiet/--agent; unsupported on completion, setup, top-level skill, and version with a jq-specific usage error; incompatible with --styled, --markdown, --ids-only, and --count) | | --json | JSON envelope output | | --quiet | Raw JSON data without envelope | | --styled | Human-readable styled output (tables, colors) | | --markdown | GFM markdown output (for agents) | | --agent | Agent mode (defaults to quiet; combinable with --json/--markdown) | | --ids-only | Print one ID per line | | --count | Print count of results | | --limit N | Client-side truncation of list results | | --verbose | Show request/response details |

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](#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 (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 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" ", "description": "Move to column"},
  {"action": "close", "cmd": "fizzy card close 42", "description": "Close card"},
  {"action": "assign", "cmd": "fizzy card assign 42 --user ", "description": "Assign user"}
]

Use breadcrumbs to discover available actions without memorizing the full CLI. Values like card numbers and board IDs are pre-filled; placeholders like `` need to be replaced.

Create/update responses include location:

{
  "ok": true,
  "data": { ... },
  "context": {
    "location": "/6102600/cards/579.json"
  }
}

---

ID Formats

IMPORTANT: Cards use TWO identifiers:

| Field | Format | Use For | |-------|--------|---------| | id | 03fe4rug9kt1mpgyy51lq8i5i | Internal ID (in JSON responses) | | number | 579 | CLI commands (card show, card update, etc.) |

All card CLI commands use the card NUMBER, not the ID.

Other resources (boards, columns, comments, steps, reactions, users) use their id field.

---

Card Statuses

Cards exist in different states. By default, fizzy card list returns open cards only (cards in triage or columns). To fetch cards in other states, use the --indexed-by or --column flags:

| Status | How to fetch | Description | |--------|--------------|-------------| | Open (default) | fizzy card list | Cards in triage ("Maybe?") or any column | | Closed/Done | fizzy card list --indexed-by closed | Completed cards | | Not Now | fizzy card list --indexed-by not_now | Postponed cards | | Golden | fizzy card list --indexed-by golden | Starred/important cards | | Stalled | fizzy card list --indexed-by stalled | Cards with no recent activity |

You can also use pseudo-columns:

fizzy card list --column done      # Same as --indexed-by closed
fizzy card list --column not-now   # Same as --indexed-by not_now
fizzy card list --column maybe     # Same as --indexed-by maybe

Fetching all cards on a board:

To get all cards regardless of status (for example, to build a complete board view), make separate queries:

# Open cards (triage + columns)
fizzy card list --board BOARD_ID --all

# Closed/Done cards
fizzy card list --board BOARD_ID --indexed-by closed --all

# Optionally, Not Now cards
fizzy card list --board BOARD_ID --indexed-by not_now --all

---

Built-in jq Filtering

Use --jq for filtering and extracting data. --jq implies --json (or filters raw data with --quiet / --agent) — no need to pass both. Never pipe to external jq — use --jq instead. --jq is for machine-readable JSON output and cannot be combined with --styled, --markdown, --ids-only, or --count.

Reducing Output

# Card summary (most useful)
fizzy card list --jq '[.data[] | {number, title, status, board: .board.name}]'

# First N items from the JSON envelope
fizzy card list --jq '.data[:5]'

# First N items from raw data only
fizzy card list --quiet --jq '.[0:5]'

# Just IDs
fizzy board list --jq '[.data[].id]'

# Specific fields from single item
fizzy card show 579 --jq '.data | {number, title, status, golden}'

# Card with description length (description is a string, not object)
fizzy card show 579 --jq '.data | {number, title, desc_length: (.description | length)}'

Filtering

# Cards with a specific status
fizzy card list --all --jq '[.data[] | select(.status == "published")]'

# Golden cards only
fizzy card list --indexed-by golden --jq '[.data[] | {number, title}]'

# Cards with non-empty descriptions
fizzy card list --jq '[.data[] | select(.description | length > 0) | {number, title}]'

# Cards with steps (must use card show, steps not in list)
fizzy card show 579 --jq '.data.steps'

Extracting Nested Data

# Comment text only (body.plain_text for comments)
fizzy comment list --card 579 --jq '[.data[].body.plain_text]'

# Card description (just .description for cards - it's a string)
fizzy card show 579 --jq '.data.description'

# Step completion status
fizzy card show 579 --jq '[.data.steps[] | {content, completed}]'

Activity Analysis

# Cards with steps count (requires card show for each)
fizzy card show 579 --jq '.data | {number, title, steps_count: (.steps | length)}'

# Comments count for a card
fizzy comment list --card 579 --jq '.data | length'

---

Command Reference

Identity

fizzy identity show                    # Show your identity and accessible accounts
fizzy identity timezone-update --timezone America/New_York  # Update your timezone for the current account

Account

fizzy account show                     # Show account settings (name, auto-postpone period)
fizzy account entropy --auto_postpone_period_in_days N  # Update account default auto-postpone period (admin only, N: 3, 7, 11, 30, 90, 365)

The auto_postpone_period_in_days is the account-level default. Cards are automatically moved to "Not Now" after this period of inactivity. Each board can override this with board entropy.

Search

Full-text search across cards. The query is sent as a single string to the dedicated search endpoint; if the query exactly matches a card ID, that card is returned directly.

fizzy search QUERY

Examples:

fizzy search "bug"                     # Search for "bug"
fizzy search "login error"             # Single-string FTS query
fizzy search 12345                     # Card-ID lookup shortcut

To filter cards by structured criteria (board, tag, assignee, status, sort, or AND-of-words term filtering), use fizzy card list with --search and the relevant filter flags:

fizzy card list --search "bug" --board BOARD_ID --indexed-by closed --sort newest

Activities

fizzy activity list [--board ID] [--creator ID] [--page N] [--all]

Boards

fizzy board list [--page N] [--all]
fizzy board show BOARD_ID
fizzy board create --name "Name" [--all_access true/false] [--auto_postpone_period_in_days N]
fizzy board update BOARD_ID [--name "Name"] [--all_access true/false] [--auto_postpone_period_in_days N]
fizzy board publish BOARD_ID
fizzy board unpublish BOARD_ID
fizzy board delete BOARD_ID
fizzy board entropy BOARD_ID --auto_postpone_period_in_days N  # N: 3, 7, 11, 30, 90, 365
fizzy board accesses --board ID [--page N]             # Show board access settings and users
fizzy board closed --board ID [--page N] [--all]       # List closed cards
fizzy board postponed --board ID [--page N] [--all]    # List postponed cards
fizzy board stream --board ID [--page N] [--all]       # List stream cards
fizzy board involvement BOARD_ID --involvement LEVEL   # Update your involvement

board show includes public_url only when the board is published. board entropy updates the auto-postpone period for a specific board (overrides account

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: basecamp
• Source: basecamp/fizzy-cli
• License: MIT
• Homepage: https://fizzy.do

Install and usage instructions live in the source repository linked above.