# Fizzy

> |

- **Type:** Skill
- **Install:** `agentstack add skill-basecamp-fizzy-cli-fizzy`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [basecamp](https://agentstack.voostack.com/s/basecamp)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [basecamp](https://github.com/basecamp)
- **Source:** https://github.com/basecamp/fizzy-cli/tree/master/skills/fizzy
- **Website:** https://fizzy.do

## Install

```sh
agentstack add skill-basecamp-fizzy-cli-fizzy
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# /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.

```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 (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 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" ", "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:**
```json
{
  "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:

```bash
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:

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

---

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

```bash
# 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

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

---

## Command Reference

### Identity

```bash
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

```bash
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.

```bash
fizzy search QUERY
```

**Examples:**
```bash
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:

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

### Activities

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

### 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_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](https://github.com/basecamp)
- **Source:** [basecamp/fizzy-cli](https://github.com/basecamp/fizzy-cli)
- **License:** MIT
- **Homepage:** https://fizzy.do

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** yes
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-basecamp-fizzy-cli-fizzy
- Seller: https://agentstack.voostack.com/s/basecamp
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.