fizzy

| Resource | List | Show | Create | Update | Delete | Other |

|----------|------|------|--------|--------|--------|-------|

| board | board list | board show ID | board create | board update ID | board delete ID | migrate board ID |

| card | card list | card show NUMBER | card create | card update NUMBER | card delete NUMBER | card move NUMBER |

| search | search QUERY | - | - | - | - | - |

| column | column list --board ID | column show ID --board ID | column create | column update ID | column delete ID | - |

| comment | comment list --card NUMBER | comment show ID --card NUMBER | comment create | comment update ID | comment delete ID | - |

| step | - | 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 | - | - | - | - |

| notification | notification list | - | - | - | - | - |

| pin | pin list | - | - | - | - | card pin NUMBER, card unpin NUMBER |

---

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.

---

All responses follow this structure:

```json

{

"success": true,

"data": { ... }, // Single object or array

"summary": "4 boards", // Human-readable description

"breadcrumbs": [ ... ], // Contextual next actions (omitted when empty)

"meta": {

"timestamp": "2026-01-12T21:21:48Z"

}

}

```

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

{

"success": true,

"data": [ ... ],

"summary": "10 cards (page 1)",

"pagination": {

"has_next": true,

"next_url": "https://..."

},

"meta": { ... }

}

```

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

```bash

fizzy card show 42 | jq '.breadcrumbs'

```

```json

[

{"action": "comment", "cmd": "fizzy comment create --card 42 --body \"text\"", "description": "Add comment"},

{"action": "triage", "cmd": "fizzy card column 42 --column ", "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.

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": { ... }

}

```

---

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) |

---

All commands support:

| Flag | Description |

|------|-------------|

| --account SLUG | Account slug (for multi-account users) |

| --pretty | Pretty-print JSON output |

| --verbose | Show request/response details |

---

List commands use --page for pagination. There is NO --limit flag.

```bash

# Get first page (default)

fizzy card list --page 1

# Get specific number of results using jq

fizzy card list --page 1 | jq '.data[:5]'

# Fetch ALL pages at once

fizzy card list --all

```

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
• card list
• search
• comment list
• tag list
• user list
• notification list

---

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:

```bash

fizzy card list --column done --all # Same as --indexed-by closed

fizzy card list --column not-now --all # Same as --indexed-by not_now

fizzy card list --column maybe --all # Cards in triage (no column assigned)

```

Fetching all cards on a board:

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

```bash

# 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

```

---

Reducing Output

```bash

# Card summary (most useful)

fizzy card list | jq '[.data[] | {number, title, status, board: .board.name}]'

# First N items

fizzy card list | jq '.data[: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

```bash

# 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

```bash

# 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

```bash

# 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'

```

---

Identity

```bash

fizzy identity show # Show your identity and accessible accounts

```

Search

Quick text search across cards. Multiple words are treated as separate terms (AND).

```bash

fizzy search QUERY [flags]

--board ID # Filter by board

--assignee ID # Filter by assignee user ID

--tag ID # Filter by tag ID

--indexed-by LANE # Filter: all, closed, not_now, golden

--sort ORDER # Sort: newest, oldest, or latest (default)

--page N # Page number

--all # Fetch all pages

```

Examples:

```bash

fizzy search "bug" # Search for "bug"

fizzy search "login error" # Search for cards containing both "login" AND "error"

fizzy search "bug" --board BOARD_ID # Search within a specific board

fizzy search "bug" --indexed-by closed # Include closed cards

fizzy search "feature" --sort newest # Sort by newest first

```

Boards

```bash

fizzy board list [--page N] [--all]

fizzy board show BOARD_ID

fizzy board create --name "Name" [--all_access true/false] [--auto_postpone_period N]

fizzy board update BOARD_ID [--name "Name"] [--all_access true/false] [--auto_postpone_period N]

fizzy board delete BOARD_ID

```

Board Migration

Migrate boards between accounts (e.g., from personal to team account).

```bash

fizzy migrate board BOARD_ID --from SOURCE_SLUG --to TARGET_SLUG [flags]

--include-images # Migrate card header images and inline attachments

--include-comments # Migrate card comments

--include-steps # Migrate card steps (to-do items)

--dry-run # Preview migration without making changes

```

What gets migrated:

• Board with same name
• All columns (preserving order and colors)
• All cards with titles, descriptions, timestamps, and tags
• Card states (closed, golden, column placement)
• Optional: header images, inline attachments, comments, and steps

What cannot be migrated:

• Card creators (become the migrating user)
• Card numbers (new sequential numbers in target)
• Comment authors (become the migrating user)
• User assignments (team must reassign manually)

Requirements: You must have API access to both source and target accounts. Verify with fizzy identity show.

```bash

# Preview migration first

fizzy migrate board BOARD_ID --from personal --to team-account --dry-run

# Basic migration

fizzy migrate board BOARD_ID --from personal --to team-account

# Full migration with all content

fizzy migrate board BOARD_ID --from personal --to team-account \

--include-images --include-comments --include-steps

```

Cards

#### Listing & Viewing

```bash

fizzy card list [flags]

--board ID # Filter by board

--column ID # Filter by column ID or pseudo: not-yet, maybe, done

--assignee ID # Filter by assignee user ID

--tag ID # Filter by tag ID

--indexed-by LANE # Filter: all, closed, not_now, stalled, postponing_soon, golden

--search "terms" # Search by text (space-separated for multiple terms)

--sort ORDER # Sort: newest, oldest, or latest (default)

--creator ID # Filter by creator user ID

--closer ID # Filter by user who closed the card

--unassigned # Only show unassigned cards

--created PERIOD # Filter by creation: today, yesterday, thisweek, lastweek, thismonth, lastmonth

--closed PERIOD # Filter by closure: today, yesterday, thisweek, lastweek, thismonth, lastmonth

--page N # Page number

--all # Fetch all pages

fizzy card show CARD_NUMBER # Show card details (includes steps)

```

#### Creating & Updating

```bash

fizzy card create --board ID --title "Title" [flags]

--description "HTML" # Card description (HTML)

--description_file PATH # Read description from file

--image SIGNED_ID # Header image (use signed_id from upload)

--tag-ids "id1,id2" # Comma-separated tag IDs

--created-at TIMESTAMP # Custom created_at

fizzy card update CARD_NUMBER [flags]

--title "Title"

--description "HTML"

--description_file PATH

--image SIGNED_ID

--created-at TIMESTAMP

fizzy card delete CARD_NUMBER

```

#### Status Changes

```bash

fizzy card close CARD_NUMBER # Close card (sets closed: true)

fizzy card reopen CARD_NUMBER # Reopen closed card

fizzy card postpone CARD_NUMBER # Move to Not Now lane

fizzy card untriage CARD_NUMBER # Remove from column, back to triage

```

Note: Card status field stays "published" for active cards. Use:

• closed: true/false to check if closed
• --indexed-by not_now to find postponed cards
• --indexed-by closed to find closed cards

#### Actions

```bash

fizzy card column CARD_NUMBER --column ID # Move to column (use column ID or: maybe, not-yet, done)

fizzy card move CARD_NUMBER --to BOARD_ID # Move card to a different board

fizzy card assign CARD_NUMBER --user ID # Toggle user assignment

fizzy card tag CARD_NUMBER --tag "name" # Toggle tag (creates tag if needed)

fizzy card watch CARD_NUMBER # Subscribe to notifications

fizzy card unwatch CARD_NUMBER # Unsubscribe

fizzy card pin CARD_NUMBER # Pin card for quick access

fizzy card unpin CARD_NUMBER # Unpin card

fizzy card golden CARD_NUMBER # Mark as golden/starred

fizzy card ungolden CARD_NUMBER # Remove golden status

fizzy card image-remove CARD_NUMBER # Remove header image

```

#### Attachments

```bash

fizzy card attachments show CARD_NUMBER # List attachments

fizzy card attachments download CARD_NUMBER [INDEX] # Download (1-based index)

-o, --output FILENAME # Output filename (single file)

```

Columns

Boards have pseudo columns by default: not-yet, maybe, done

```bash

fizzy column list --board ID

fizzy column show COLUMN_ID --board ID

fizzy column create --board ID --name "Name" [--color HEX]

fizzy column update COLUMN_ID --board ID [--name "Name"] [--color HEX]

fizzy column delete COLUMN_ID --board ID

```

Comments

```bash

fizzy comment list --card NUMBER [--page N] [--all]

fizzy comment show COMMENT_ID --card NUMBER

fizzy comment create --card NUMBER --body "HTML" [--body_file PATH] [--created-at TIMESTAMP]

fizzy comment update COMMENT_ID --card NUMBER [--body "HTML"] [--body_file PATH]

fizzy comment delete COMMENT_ID --card NUMBER

```

Steps (To-Do Items)

Steps are returned in card show response. No separate list command.

```bash

fizzy step show STEP_ID --card NUMBER

fizzy step create --card NUMBER --content "Text" [--completed]

fizzy step update STEP_ID --card NUMBER [--content "Text"] [--completed] [--not_completed]

fizzy step delete STEP_ID --card NUMBER

```

Reactions

Reactions can be added to cards directly or to comments on cards.

```bash

# Card reactions (react directly to a card)

fizzy reaction list --card NUMBER

fizzy reaction create --card NUMBER --content "emoji"

fizzy reaction delete REACTION_ID --card NUMBER

# Comment reactions (react to a specific comment)

fizzy reaction list --card NUMBER --comment COMMENT_ID

fizzy reaction create --card NUMBER --comment COMMENT_ID --content "emoji"

fizzy reaction delete REACTION_ID --card NUMBER --comment COMMENT_ID

```

| Flag | Required | Description |

|------|----------|-------------|

| --card | Yes | Card number (always required) |

| --comment | No | Comment ID (omit for card reactions) |

| --content | Yes (create) | Emoji or text, max 16 characters |

Tags

Tags are created automatically when using card tag. List shows all existing tags.

```bash

fizzy tag list [--page N] [--all]

```

Users

```bash

fizzy user list [--page N] [--all]

fizzy user show USER_ID

```

Pins

```bash

fizzy pin list # List your pinned cards (up to 100)

```

Notifications

```bash

fizzy notification list [--page N] [--all]

fizzy notification read NOTIFICATION_ID

fizzy notification read-all

fizzy notification unread NOTIFICATION_ID

```

File Uploads

```bash

fizzy upload file PATH

# Returns: { "signed_id": "...", "attachable_sgid": "..." }

```

| ID | Use For |

|---|---|

| signed_id | Card header/background images (--image flag) |

| attachable_sgid | Inline images in rich text (descriptions, comments) |

---

Create Card with Steps

```bash

# Create the card

CARD=$(fizzy card create --board BOARD_ID --title "New Feature" \

--description "

Feature description

# Add steps

fizzy step create --card $CARD --content "Design the feature"

fizzy step create --card $CARD --content "Implement backend"

fizzy step create --card $CARD --content "Write tests"

```

Create Card with Inline Image

```bash

# Upload image

SGID=$(fizzy upload file screenshot.png | jq -r '.data.attachable_sgid')

# Create description file with embedded image

cat > desc.html << EOF

See the screenshot below:

EOF

# Create card

fizzy card create --board BOARD_ID --title "Bug Report" --description_file desc.html

```

Create Card with Background Image (only when explicitly requested)

```bash

# Validate file is an image

MIME=$(file --mime-type -b /path/to/image.png)

if [[ ! "$MIME" =~ ^image/ ]]; then

echo "Error: Not a valid image (detected: $MIME)"

exit 1

fi

# Upload and get signed_id

SIGNED_ID=$(fizzy upload file /path/to/header.png | jq -r '.data.signed_id')

# Create card with background

fizzy card create --board BOARD_ID --title "Card" --image "$SIGNED_ID"

```

Move Card Through Workflow

```bash

# Move to a column

fizzy card column 579 --column maybe

# Assign to user

fizzy card assign 579 --user USER_ID

# Mark as golden (important)

fizzy card golden 579

# When done, close it

fizzy card close 579

```

Move Card to Different Board

```bash

# Move card to another board

fizzy card move 579 --to TARGET_BOARD_ID

```

Search and Filter Cards

```bash

# Quick search

fizzy search "bug" | jq '[.data[] | {number, title}]'

# Search with filters

fizzy search "login" --board BOARD_ID --sort newest

# Find recently created cards

fizzy card list --created today --sort newest

# Find cards closed this week

fizzy card list --indexed-by closed --closed thisweek

# Find unassigned cards

fizzy card list --unassigned --board BOARD_ID

```

React to a Card

```bash

# Add reaction directly to a card

fizzy reaction create --card 579 --content "👍"

# List reactions on a card

fizzy reaction list --card 579 | jq '[.data[] | {id, content, reacter: .reacter.name}]'

```

Add Comment with Reaction

```bash

# Add comment

COMMENT=$(fizzy comment create --card 579 --body "

Looks good!

# Add reaction to the comment

fizzy reaction create --card 579 --comment $COMMENT --content "👍"

```

---

Card descriptions and comments support HTML. For multiple paragraphs with spacing:

```html

First paragraph.

Second paragraph with spacing above.

```

Note: Each attachable_sgid can only be used once. Upload the file again for multiple uses.

---

• Card images: Use inline (via attachable_sgid in description) by default. Only use background/header (signed_id with --image) when user explicitly says "background" or "header".
• Comment images: Always inline. Comments do not support background images.

---

1. Determine the action - What does the user want?
2. Check for account context - Use --account=SLUG if needed
3. Run the fizzy command using Bash
4. Parse JSON output with jq to reduce tokens
5. Report outcome clearly, including card numbers/entity IDs for reference