fizzy

/fizzy - Fizzy 工作流命令

完整覆盖 CLI 功能：看板、卡片、列、评论、步骤、反应、标签、用户、通知、置顶项、webhook、账户设置、搜索和看板迁移。

Agent 不变量

必须遵守以下规则：

1. 卡片使用 NUMBER，而不是 ID — fizzy card show 42 使用卡片编号。其他资源使用其 id 字段。
2. 使用内置的 --jq 进行筛选，以减少令牌输出 — fizzy card list --jq '[.data[] | {number, title}]'。切勿通过管道使用外部 jq — 请改用 --jq。--jq 会隐含启用 --json，无需同时传入两者。
3. 检查响应中的面包屑导航，查看带有预填值的可用后续操作。
4. 在列出卡片前，通过 .fizzy.yaml 或 --board 标志检查看板上下文。
5. 遇到设置、配置或身份验证问题时，先使用 fizzy doctor，不要猜测 — 它是主要的只读健康检查工具，并会提供修复提示。
6. 富文本字段接受 Markdown 或 HTML — 对于简单的追加到末尾的内联附件，使用可重复指定的 --attach PATH；需要精确控制位置时，则手动嵌入 <action-text-attachment> 标签。
7. 卡片描述是字符串，但评论正文是嵌套对象 — 分别使用 .description 和 .body.plain_text。
8. 向新注册用户显示欢迎消息 — 当 signup complete --name 返回 is_new_user: true 时，必须立即向用户醒目地显示 welcome_message 字段。这是 CEO 发给用户的一次性私人留言 — 如果跳过，用户将永远看不到它。

决策树

查找内容

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)

修改内容

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>

快速参考

资源	列表	显示	创建	更新	删除	其他
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 [email protected]、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

---

全局标志

除非另有说明，所有命令均支持以下全局标志：

标志	说明
--token TOKEN	API 访问令牌
--profile NAME	命名配置文件（适用于使用多个账户的用户）
--api-url URL	API 基础 URL（默认值：https://app.fizzy.do）
--jq EXPR	内置 jq 筛选器，用于输出机器可读的 JSON（无需外部 jq；隐含 --json，或使用 --quiet/--agent 筛选原始数据；不支持 completion、setup、顶层 skill，以及带有 jq 专用用法错误的 version；与 --styled、--markdown、--ids-only 和 --count 不兼容）
--json	输出 JSON 封装格式
--quiet	输出不带封装的原始 JSON 数据
--styled	输出便于阅读的样式化内容（表格、颜色）
--markdown	输出 GFM Markdown（供 Agent 使用）
--agent	Agent 模式（默认使用 quiet；可与 --json/--markdown 组合使用）
--ids-only	每行输出一个 ID
--count	输出结果数量
--limit N	在客户端截断列表结果
--verbose	显示请求/响应详情

输出格式默认自动检测：TTY 使用样式化格式，管道/非 TTY 使用 JSON。

分页

列表命令使用 --page 进行分页，使用 --limit 在客户端截断结果。

# 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

注意：--limit 和 --all 不能同时使用。

重要： --all 标志仅控制分页——它会获取当前筛选条件下的所有结果页，不会更改包含哪些卡片。默认情况下，card list 只返回未关闭的卡片。如何获取已关闭或已延期的卡片，请参阅卡片状态。

支持 --all 和 --page 的命令：

• board list
• board closed
• board postponed
• board stream
• card list
• comment list
• tag list
• user list
• notification list
• webhook list

---

配置

~/.config/fizzy/              # Global config (or ~/.fizzy/)
└── config.yaml               #   Token, account, API URL, default board

.fizzy.yaml                   # Per-repo config (committed to git)

每个仓库的配置： .fizzy.yaml

account: 123456789
board: 03foq1hqmyy91tuyz3ghugg6c

优先级（从高到低）：

1. CLI 标志（--token、--profile、--api-url、--board）
2. 环境变量（FIZZY_TOKEN、FIZZY_PROFILE、FIZZY_API_URL、FIZZY_BOARD）
3. 命名配置文件设置（来自 config.json 的账户、基础 URL、看板）
4. 本地项目配置（.fizzy.yaml）
5. 全局配置（~/.config/fizzy/config.yaml 或 ~/.fizzy/config.yaml）

检查上下文：

cat .fizzy.yaml 2>/dev/null || echo "No project configured"
fizzy config show
fizzy config explain

设置：

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

注册（新用户或生成令牌）

交互式：

fizzy signup                                    # Full interactive wizard

分步操作（适用于 Agent）：

# Step 1: Request magic link
fizzy signup start --email [email protected]
# 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

注意： 用户必须在步骤 1 和 2 之间检查电子邮件，获取 6 位数代码。 会话令牌会写入临时文件，并通过 stdin 传递，以避免在 shell 历史记录或 Agent 对话上下文中暴露。 如果有可用的系统凭据存储，则令牌会保存在其中；否则会回退到配置文件。配置文件和 API URL 会保存到 ~/.config/fizzy/（首选）或 ~/.fizzy/。

新用户的欢迎消息： 当 signup complete --name 成功执行（新用户）时，响应中会包含 is_new_user: true 和 welcome_message 字段。请参阅 Agent 不变量 #7——你必须显示此消息。

---

响应结构

所有响应都遵循以下结构：

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

摘要字段格式：

命令	摘要示例
board list	“5 boards”
board show ID	“Board: Engineering”
card list	“42 cards (page 1)” 或 “42 cards (all)”
card show 123	“Card #123: Fix login bug”
search "bug"	“7 results for "bug"”
notification list	“8 notifications (3 unread)”

带分页的列表响应：

{
  "ok": true,
  "data": [ ... ],
  "summary": "10 cards (page 1)",
  "context": {
    "pagination": {
      "has_next": true,
      "next_url": "https://..."
    }
  }
}

导航线索（后续操作提示）：

响应中包含一个 breadcrumbs 数组，用于建议接下来可以执行的操作。每个导航线索包含：

• action：简短的操作名称（例如，“comment”、“close”、“assign”）
• cmd：已插入实际值、可直接运行的命令
• description：易于理解的描述

fizzy card show 42 --jq '.breadcrumbs'

[
  {"action": "comment", "cmd": "fizzy comment create --card 42 --body \"text\"", "description": "Add comment"},
  {"action": "triage", "cmd": "fizzy card column 42 --column <column_id>", "description": "Move to column"},
  {"action": "close", "cmd": "fizzy card close 42", "description": "Close card"},
  {"action": "assign", "cmd": "fizzy card assign 42 --user <user_id>", "description": "Assign user"}
]

使用导航线索，无需记住完整的 CLI，即可了解可执行的操作。卡片编号和看板 ID 等值会预先填入；<column_id> 等占位符需要替换。

创建/更新响应包含位置：

{
  "ok": true,
  "data": { ... },
  "context": {
    "location": "/6102600/cards/579.json"
  }
}

---

ID 格式

重要： 卡片使用两种标识符：

字段	格式	用途
id	03fe4rug9kt1mpgyy51lq8i5i	内部 ID（位于 JSON 响应中）
number	579	CLI 命令（card show、card update 等）

所有卡片 CLI 命令都使用卡片编号，而不是 ID。

其他资源（看板、列、评论、步骤、回应、用户）使用其 id 字段。

---

卡片状态

卡片有不同的状态。默认情况下，fizzy card list 仅返回未关闭的卡片（分诊区或列中的卡片）。要获取其他状态的卡片，请使用 --indexed-by 或 --column 标志：

状态	获取方式	说明
未关闭（默认）	fizzy card list	分诊区（“Maybe?”）或任意列中的卡片
已关闭/已完成	fizzy card list --indexed-by closed	已完成的卡片
暂不处理	fizzy card list --indexed-by not_now	已推迟的卡片
精选	fizzy card list --indexed-by golden	已加星标/重要的卡片
停滞	fizzy card list --indexed-by stalled	近期没有活动的卡片

你也可以使用伪列：

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

获取看板上的所有卡片：

要获取所有状态的卡片（例如，构建完整的看板视图），请分别进行查询：

# 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

---

内置 jq 筛选

使用 --jq 筛选和提取数据。--jq 会隐含启用 --json（或使用 --quiet / --agent 筛选原始数据），无需同时传入这两个参数。切勿将输出通过管道传给外部 jq；请改用 --jq。--jq 用于生成机器可读的 JSON 输出，不能与 --styled、--markdown、--ids-only 或 --count 一起使用。

精简输出

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

筛选

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

提取嵌套数据

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

活动分析

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

---

命令参考

身份

fizzy identity show                    # Show your identity and accessible accounts
fizzy identity timezone-update --timezone America/New_York  # Update your timezone for the current account

账户

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)

auto_postpone_period_in_days 是账户级默认值。卡片在此期限内无活动后，会自动移至“暂不处理”。每个看板都可以通过 board entropy 覆盖此设置。

搜索

对卡片进行全文搜索。查询内容会作为单个字符串发送到专用搜索端点；如果查询内容与某个卡片 ID 完全匹配，则直接返回该卡片。

fizzy search QUERY

示例：

fizzy search "bug"                     # Search for "bug"
fizzy search "login error"             # Single-string FTS query
fizzy search 12345                     # Card-ID lookup shortcut

要按结构化条件筛选卡片（看板、标签、负责人、状态、排序或按词语组合进行 AND 筛选），请使用 fizzy card list 和 --search 及相关筛选标志：

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

活动

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

看板

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 仅在看板已发布时包含 public_url。 board entropy 会更新特定看板的自动推迟期限（覆盖账户默认值）。需要看板管理员权限。

看板迁移

在账户之间迁移看板（例如，从个人账户迁移到团队账户）。

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

迁移内容：

• 同名看板
• 所有列（保留顺序和颜色）
• 所有卡片的标题、描述、时间戳和标签
• 卡片状态（已关闭、精选、列位置）
• 可选：标题图片、内嵌附件、评论和步骤

无法迁移的内容：

• 卡片创建者（将变为执行迁移的用户）
• 卡片编号（目标账户中会分配新的连续编号）
• 评论作者（将变为执行迁移的用户）
• 用户分配（团队必须手动重新分配）

**要求：**你必须拥有源账户和目标账户的 API 访问权限。使用 fizzy identity show 验证。

# 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

卡片

列表与查看

fizzy card list [flags]
  --board ID                           # Filter by board
  --column ID                          # Filter by column ID or pseudo: not-now, maybe, done
  --assignee ID                        # Filter by assignee user ID
  --tag ID                             # Filter by tag ID
  --indexed-by LANE                    # Filter: all, closed, maybe, 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)

创建与更新

fizzy card create --board ID --title "Title" [flags]
  --description "TEXT"                # Card description (markdown or HTML)
  --description_file PATH              # Read description from file (markdown or HTML)
  --attach PATH                        # Upload and append inline attachment at end (repeatable)
  --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 "TEXT"
  --description_file PATH
  --attach PATH
  --image SIGNED_ID
  --created-at TIMESTAMP

fizzy card delete CARD_NUMBER

状态变更

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

**注意：**处于活动状态的卡片，其 status 字段始终为 “published”。请使用：

• closed: true/false 检查卡片是否已关闭
• --indexed-by not_now 查找已推迟的卡片
• --indexed-by closed 查找已关闭的卡片

操作

fizzy card column CARD_NUMBER --column ID     # Move to column (use column ID or: maybe, not-now, 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 self-assign CARD_NUMBER            # Toggle current user's 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
fizzy card publish CARD_NUMBER               # Publish a card
fizzy card mark-read CARD_NUMBER             # Mark card as read
fizzy card mark-unread CARD_NUMBER           # Mark card as unread

附件

fizzy card attachments show CARD_NUMBER [--include-comments]           # List attachments
fizzy card attachments download CARD_NUMBER [INDEX] [--include-comments]  # Download (1-based index)
  -o, --output FILENAME                                    # Exact name (single) or prefix (multiple: test_1.png, test_2.png)

列

看板默认包含伪列：not-now、maybe、done

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
fizzy column move-left COLUMN_ID             # Move column one position left
fizzy column move-right COLUMN_ID            # Move column one position right

评论

fizzy comment list --card NUMBER [--page N] [--all]
fizzy comment show COMMENT_ID --card NUMBER
fizzy comment create --card NUMBER [--body "TEXT"] [--body_file PATH] [--attach PATH] [--created-at TIMESTAMP]
fizzy comment update COMMENT_ID --card NUMBER [--body "TEXT"] [--body_file PATH] [--attach PATH]
fizzy comment delete COMMENT_ID --card NUMBER

评论附件

fizzy comment attachments show --card NUMBER                  # List attachments in comments
fizzy comment attachments download --card NUMBER [INDEX]      # Download (1-based index)
  -o, --output FILENAME                                       # Exact name (single) or prefix (multiple: test_1.png, test_2.png)

步骤（待办事项）

card show 的响应中会返回步骤，也可以单独列出。

fizzy step list --card NUMBER
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

表情回应

可以直接对卡片添加表情回应，也可以对卡片上的评论添加表情回应。

# 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

标志	必需	说明
--card	是	卡片编号（始终必需）
--comment	否	评论 ID（对卡片添加回应时省略）
--content	是（创建时）	表情符号或文本，最多 16 个字符

标签

使用 card tag 时会自动创建标签。List 会显示所有现有标签。

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

用户

fizzy user list [--page N] [--all]
fizzy user show USER_ID
fizzy user update USER_ID --name "Name"       # Update user name (requires admin/owner)
fizzy user update USER_ID --avatar /path.jpg  # Update user avatar
fizzy user deactivate USER_ID                  # Deactivate user (requires admin/owner)
fizzy user role USER_ID --role ROLE            # Update user role (requires admin/owner)
fizzy user avatar-remove USER_ID               # Remove user avatar
fizzy user export-create USER_ID               # Create user data export
fizzy user export-show USER_ID EXPORT_ID       # Show user data export status
fizzy user email-change-request USER_ID --email [email protected]
fizzy user email-change-confirm USER_ID TOKEN
fizzy user push-subscription-create --user ID --endpoint URL --p256dh-key KEY --auth-key KEY
fizzy user push-subscription-delete SUB_ID --user ID

置顶项

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

通知

fizzy notification list [--page N] [--all]
fizzy notification tray                    # Unread notifications (up to 100)
fizzy notification tray --include-read     # Include read notifications
fizzy notification read NOTIFICATION_ID
fizzy notification read-all
fizzy notification unread NOTIFICATION_ID
fizzy notification settings-show              # Show notification settings
fizzy notification settings-update --bundle-email-frequency FREQ  # Update settings

Webhook

当看板上发生事件时，Webhook 会通知外部服务。需要账户管理员权限。

fizzy webhook list --board ID [--page N] [--all]
fizzy webhook deliveries --board ID WEBHOOK_ID [--page N] [--all]
fizzy webhook show WEBHOOK_ID --board ID
fizzy webhook create --board ID --name "Name" --url "https://..." [--actions card_published,card_closed,...]
fizzy webhook update WEBHOOK_ID --board ID [--name "Name"] [--actions card_closed,...]
fizzy webhook delete WEBHOOK_ID --board ID
fizzy webhook reactivate WEBHOOK_ID --board ID    # Reactivate a deactivated webhook

支持的操作： card_assigned、card_closed、card_postponed、card_auto_postponed、card_board_changed、card_published、card_reopened、card_sent_back_to_triage、card_triaged、card_unassigned、comment_created

注意： Webhook URL 创建后不可更改。使用 --actions 并以逗号分隔值。

Webhook 架构

字段	类型	描述
id	string	Webhook ID（用于 CLI 命令）
name	string	Webhook 名称
payload_url	string	目标 URL
active	boolean	Webhook 是否处于启用状态
signing_secret	string	用于验证负载的密钥
subscribed_actions	array	已订阅事件操作的列表
created_at	timestamp	ISO 8601
url	string	API URL
board	object	嵌套的看板对象

账户

fizzy account show                                     # Show account settings
fizzy account settings-update --name "Name"            # Update account name
fizzy account export-create                            # Create data export
fizzy account export-show EXPORT_ID                    # Check export status
fizzy account join-code-show                           # Show join code
fizzy account join-code-reset                          # Reset join code
fizzy account join-code-update --usage-limit N         # Update join code limit

文件上传

fizzy upload file PATH
# Returns: { "signed_id": "...", "attachable_sgid": "..." }

ID	用途
signed_id	卡片标题／背景图片（--image 标志）
attachable_sgid	手动以内联方式嵌入富文本，使用 <action-text-attachment>

简单的内联附件模式： 如果将附件追加到末尾即可，请优先在 card create、card update、comment create 和 comment update 中使用 --attach PATH。

---

常见工作流

创建带步骤的卡片

# Create the card
CARD=$(fizzy card create --board BOARD_ID --title "New Feature" \
  --description "<p>Feature description</p>" --jq '.data.number')

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

将代码关联到卡片

# Add a comment linking the commit
fizzy comment create --card 42 --body "<p>Commit $(git rev-parse --short HEAD): $(git log -1 --format=%s)</p>"

# Close the card when done
fizzy card close 42

创建带内联附件的卡片

简单模式：

fizzy card create --board BOARD_ID --title "Bug Report" --description "See the screenshot below" --attach screenshot.png

高级／手动放置模式：

# Upload image
SGID=$(fizzy upload file screenshot.png --jq '.data.attachable_sgid')

# Create description file with embedded image
cat > desc.html << EOF
<p>See the screenshot below:</p>
<action-text-attachment sgid="$SGID"></action-text-attachment>
EOF

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

创建带背景图片的卡片（仅在明确要求时）

# 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 '.data.signed_id')

# Create card with background
fizzy card create --board BOARD_ID --title "Card" --image "$SIGNED_ID"

在工作流中移动卡片

# Move to a column
fizzy card column 579 --column maybe

# Assign to yourself
fizzy card self-assign 579

# Or assign to another 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 another board
fizzy card move 579 --to TARGET_BOARD_ID

搜索和筛选卡片

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

# Filter cards by criteria (use card list, not search)
fizzy card list --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

对卡片作出回应

# 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
COMMENT=$(fizzy comment create --card 579 --body "<p>Looks good!</p>" --jq '.data.id')

# Add reaction to the comment
fizzy reaction create --card 579 --comment $COMMENT --content "👍"

---

资源架构

所有资源的完整字段参考。请在 jq 查询中使用这些确切的字段路径。

卡片架构

重要： card list 和 card show 返回的字段不同。steps 仅在 card show 中提供。

字段	类型	描述
number	integer	用于 CLI 命令
id	string	内部 ID（仅在响应中）
title	string	卡片标题
description	string	纯文本内容（不是对象）
description_html	string	带附件的 HTML 版本
status	string	活跃卡片通常为 "published"
closed	boolean	true = 卡片已关闭
golden	boolean	true = 已加星标／重要
image_url	string/null	标题／背景图片 URL
has_attachments	boolean	true = 卡片有文件附件
has_more_assignees	boolean	指派用户数量超过显示数量
created_at	timestamp	ISO 8601
last_active_at	timestamp	ISO 8601
url	string	网页 URL
comments_url	string	评论端点 URL
board	object	嵌套的看板对象（见下文）
creator	object	嵌套的用户对象（见下文）
assignees	array	用户对象数组
tags	array	标签对象数组
steps	array	仅在 card show 中提供，列表中不提供

看板架构

字段	类型	描述
id	string	看板 ID（用于 CLI 命令）
name	string	看板名称
all_access	boolean	所有用户均有访问权限
auto_postpone_period_in_days	integer	卡片自动延期前的不活跃天数
created_at	timestamp	ISO 8601
url	string	网页 URL
creator	object	嵌套的用户对象

账户设置架构（来自 account show）

字段	类型	描述
id	string	账户 ID
name	string	账户名称
cards_count	integer	账户中的卡片总数
auto_postpone_period_in_days	integer	账户级别的默认自动延期时长
created_at	timestamp	ISO 8601

用户架构

字段	类型	描述
id	string	用户 ID（用于 CLI 命令）
name	string	显示名称
email_address	string	电子邮件
role	string	"owner"、"admin" 或 "member"
active	boolean	账户是否处于活动状态
created_at	timestamp	ISO 8601
url	string	网页 URL

评论架构

字段	类型	描述
id	string	评论 ID（用于 CLI 命令）
body	object	包含 html 和 plain_text 的嵌套对象
body.html	string	HTML 内容
body.plain_text	string	纯文本内容
created_at	timestamp	ISO 8601
updated_at	timestamp	ISO 8601
url	string	网页 URL
reactions_url	string	表情回应端点 URL
creator	object	嵌套的用户
card	object	嵌套的 {id, url}

步骤架构

字段	类型	描述
id	string	步骤 ID（用于 CLI 命令）
content	string	步骤文本
completed	boolean	完成状态

列架构

字段	类型	描述
id	string	列 ID 或伪 ID（"not-now"、"maybe"、"done"）
name	string	显示名称
kind	string	"not_now"、"triage"、"closed" 或自定义值
pseudo	boolean	true = 内置列

标签架构

字段	类型	描述
id	string	标签 ID
title	string	标签名称
created_at	timestamp	ISO 8601
url	string	网页 URL

表情回应架构

字段	类型	描述
id	string	表情回应 ID（用于 CLI 命令）
content	string	表情符号
url	string	网页 URL
reacter	object	嵌套的用户

身份架构（来自 identity show）

字段	类型	描述
accounts	array	账户对象数组
accounts[].id	string	账户 ID
accounts[].name	string	账户名称
accounts[].slug	string	账户 slug（与 signup complete --account 配合使用，或作为配置文件名称）
accounts[].user	object	你在此账户中的用户信息

关键架构差异

资源	文本字段	HTML 字段
卡片	.description（string）	.description_html（string）
评论	.body.plain_text（嵌套）	.body.html（嵌套）

---

富文本格式

卡片描述和评论支持 Markdown 或 HTML。若要在末尾追加简单的内联附件，请使用 --attach PATH。

若要精确控制位置，请先上传，再手动嵌入 <action-text-attachment> 标签。要添加带间距的多个段落：

<p>First paragraph.</p>
<p><br></p>
<p>Second paragraph with spacing above.</p>

**注意：**每个 attachable_sgid 只能使用一次。需要多次使用时，请重新上传文件。

默认行为

• **卡片图片：**默认以内联方式插入（在描述中使用 attachable_sgid）。只有当用户明确提到“背景”或“页眉”时，才使用背景／页眉图片（通过 --image 使用 signed_id）。
• **评论图片：**始终以内联方式插入。评论不支持背景图片。

---

错误处理

错误响应格式：

{
  "ok": false,
  "error": "Not Found",
  "code": "not_found",
  "hint": "optional context"
}

退出代码：

代码	含义
0	成功
1	用法错误／参数无效
2	未找到
3	身份验证失败
4	权限被拒绝
5	请求过于频繁
6	网络错误
7	API／服务端错误
8	匹配结果不明确

身份验证错误（退出代码 3）：

fizzy doctor                             # Full health check with hints
fizzy auth status                        # Check auth
fizzy auth list                          # Check which profiles are configured
fizzy auth switch PROFILE                # Switch to correct profile
fizzy auth login TOKEN                   # Re-authenticate
fizzy auth login TOKEN --profile agent --account 1  # Save an aliased profile
fizzy setup                              # Full interactive setup

未找到错误（退出代码 2）： 请确认卡片编号或资源 ID 正确。卡片使用 NUMBER，而不是 ID。

权限被拒绝（退出代码 4）： 某些操作（更新用户、停用用户）需要管理员／所有者角色。

网络错误（退出代码 6）： 检查 API URL 配置：

fizzy doctor                             # Full connectivity + API URL diagnostics
fizzy config explain                     # Why this API URL won
fizzy auth status                        # Shows configured profile and API URL

了解更多

• API 文档：https://github.com/basecamp/fizzy/blob/main/docs/API.md
• CLI 仓库：https://github.com/basecamp/fizzy-cli