fizzy

Fizzy CLI Skill

Requirements (Install & Auth)

Install via Homebrew (macOS)

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

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

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:

{
  "success": true,
  "data": { ... },           // Single object or array
  "meta": {
    "timestamp": "2026-01-12T21:21:48Z"
  }
}

List responses with pagination:

{
  "success": true,
  "data": [ ... ],
  "pagination": {
    "has_next": true,
    "next_url": "https://..."
  },
  "meta": { ... }
}

Error responses:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Not Found",
    "status": 404
  },
  "meta": { ... }
}

Create/update responses include location:

{
  "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

---

Pagination

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

# 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

Commands supporting --all and --page:

• board list
• card list
• comment list
• tag list
• user list
• notification list

---

Common jq Patterns

Reducing Output

# 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

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

# Golden cards only
fizzy card list --

---

*Content truncated.*