fizzy

# Fizzy CLI Skill ## Requirements (Install & Auth) ### Install via Homebrew (macOS) ```bash brew install robzolkos/fizzy-cli/fizzy-cli ``` ### Configure Credentials The CLI needs your API token and account. You can set these via environment variables or config files. **Environment variables (recommended for Clawdbot):** ```bash # Set these before running fizzy commands export FIZZY_TOKEN="your_token_here" export FIZZY_ACCOUNT="your_account_slug" # e.g., "0000001" export FIZZY_API_URL="https://fizzy.domain.net/" # self-hosted export FIZZY_BOARD="your_default_board_id" # optional ``` **Or use a config file** (`~/.config/fizzy/config.yaml`): ```yaml token: your_token_here account: your_account_slug api_url: https://fizzy.domain.net/ board: your_default_board_id ``` ### Get Your Token 1. Go to your Fizzy profile → Personal Access Tokens 2. Generate a new token with Read + Write permissions ## 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. --- ## Response Structure All responses follow this structure: ```json { "success": true, "data": { ... }, // Single object or array "meta": { "timestamp": "2026-01-12T21:21:48Z" } } ``` **List responses with pagination:** ```json { "success": true, "data": [ ... ], "pagination": { "has_next": true, "next_url": "https://..." }, "meta": { ... } } ``` **Error responses:** ```json { "success": false, "error": { "code": "NOT_FOUND", "message": "Not Found", "status": 404 }, "meta": { ... } } ``` **Create/update responses include location:** ```json { "success": true, "data": { ... }, "location": "/6102600/cards/579.json", "meta": { ... } } ``` --- ## Resource Schemas Complete field reference for all resources. Use these exact field paths in jq queries. ### Card Schema **IMPORTANT:** `card list` and `card show` return different fields. `steps` only in `card show`. | Field | Type | Description | | -------------------- | ----------- | -------------------------------------- | | `number` | integer | **Use this for CLI commands** | | `id` | string | Internal ID (in responses only) | | `title` | string | Card title | | `description` | string | Plain text content (**NOT an object**) | | `description_html` | string | HTML version with attachments | | `status` | string | Usually "published" for active cards | | `closed` | boolean | true = card is closed | | `golden` | boolean | true = starred/important | | `image_url` | string/null | Header/background image URL | | `has_more_assignees` | boolean | More assignees than shown | | `created_at` | timestamp | ISO 8601 | | `last_active_at` | timestamp | ISO 8601 | | `url` | string | Web URL | | `comments_url` | string | Comments endpoint URL | | `board` | object | Nested Board (see below) | | `creator` | object | Nested User (see below) | | `assignees` | array | Array of User objects | | `tags` | array | Array of Tag objects | | `steps` | array | **Only in `card show`**, not in list | ### Board Schema | Field | Type | Description | | ------------ | --------- | ------------------------------- | | `id` | string | Board ID (use for CLI commands) | | `name` | string | Board name | | `all_access` | boolean | All users have access | | `created_at` | timestamp | ISO 8601 | | `url` | string | Web URL | | `creator` | object | Nested User | ### User Schema | Field | Type | Description | | --------------- | --------- | ------------------------------ | | `id` | string | User ID (use for CLI commands) | | `name` | string | Display name | | `email_address` | string | Email | | `role` | string | "owner", "admin", or "member" | | `active` | boolean | Account is active | | `created_at` | timestamp | ISO 8601 | | `url` | string | Web URL | ### Comment Schema | Field | Type | Description | | ----------------- | --------- | ------------------------------------------ | | `id` | string | Comment ID (use for CLI commands) | | `body` | object | **Nested object with html and plain_text** | | `body.html` | string | HTML content | | `body.plain_text` | string | Plain text content | | `created_at` | timestamp | ISO 8601 | | `updated_at` | timestamp | ISO 8601 | | `url` | string | Web URL | | `reactions_url` | string | Reactions endpoint URL | | `creator` | object | Nested User | | `card` | object | Nested {id, url} | ### Step Schema | Field | Type | Description | | ----------- | ------- | ------------------------------ | | `id` | string | Step ID (use for CLI commands) | | `content` | string | Step text | | `completed` | boolean | Completion status | ### Column Schema | Field | Type | Description | | -------- | ------- | --------------------------------------------------- | | `id` | string | Column ID or pseudo ID ("not-now", "maybe", "done") | | `name` | string | Display name | | `kind` | string | "not_now", "triage", "closed", or custom | | `pseudo` | boolean | true = built-in column | ### Tag Schema | Field | Type | Description | | ------------ | --------- | ----------- | | `id` | string | Tag ID | | `title` | string | Tag name | | `created_at` | timestamp | ISO 8601 | | `url` | string | Web URL | ### Reaction Schema | Field | Type | Description | | --------- | ------ | ---------------------------------- | | `id` | string | Reaction ID (use for CLI commands) | | `content` | string | Emoji | | `url` | string | Web URL | | `reacter` | object | Nested User | ### Identity Schema (from `identity show`) | Field | Type | Description | | ----------------- | ------ | --------------------------------- | | `accounts` | array | Array of Account objects | | `accounts[].id` | string | Account ID | | `accounts[].name` | string | Account name | | `accounts[].slug` | string | Account slug (use with --account) | | `accounts[].user` | object | Your User in this account | ### Key Schema Differences | Resource | Text Field | HTML Field | | -------- | --------------------------- | ---------------------------- | | Card | `.description` (string) | `.description_html` (string) | | Comment | `.body.plain_text` (nested) | `.body.html` (nested) | --- ## Global Flags All commands support: | Flag | Description | | ---------------- | -------------------------------------- | | `--account SLUG` | Account slug (for multi-account users) | | `--pretty` | Pretty-print JSON output | | `--verbose` | Show request/response details |