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 | 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. ```bash # 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` ```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:** ```bash cat .fizzy.yaml 2>/dev/null || echo "No project configured" fizzy config show fizzy config explain ``` **Setup:** ```bash 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: ```bash fizzy signup # Full interactive wizard ``` Step-by-step (for agents): ```bash # 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: ```json { "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:** | Command | Example Summary | |---------|-----------------| | `board list` | "5 boards" | | `board show ID` | "Board: Engineering" | | `card list` | "42 cards (page 1)" or "42 cards (all)" | | `card show 123` | "Card #123: Fix login bug" | | `search "bug"` | "7 results for \"bug\"" | | `notification list` | "8 notifications (3 unread)" | **List responses with pagination:** ```json { "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