fizzy

用途

fizzy 是 Fizzy 的命令行客户端，用于在终端或自动化流程中操作 Fizzy 的各项资源。它覆盖了完整的 CLI 能力：看板（boards）、卡片（cards）、列（columns）、评论（comments）、步骤（steps）、表情（reactions）、标签（tags）、用户（users）、通知（notifications）、置顶（pins）、Webhook、账户设置、搜索以及看板迁移。

主要能力

• 资源管理：account、identity、board、card、column、comment、step、reaction、tag、user、notification、pin、webhook 等均可通过命令行进行列表、查看、创建、更新、删除及部分专属操作（如卡片移动、发布、标记已读、列左右移动、Webhook 重新激活等）。
• 搜索：fizzy search QUERY 提供跨看板全文搜索，若查询精确匹配卡片 ID 则直接返回该卡片；也可用 fizzy card list --search 结合结构化筛选条件。
• 卡片状态筛选：默认 card list 只返回开放卡片，可通过 --indexed-by maybe|closed|not_now|golden|stalled 获取其他状态，或用伪列 --column done|not-now|maybe。
• 输出格式：支持 styled（默认 TTY 人类可读）、--json、--quiet（裸数据）、--markdown（GFM）、--agent、--ids-only、--count 等；非 TTY 或管道时自动切换为 JSON。
• 内置 jq：--jq EXPR 用于过滤与提取，隐含 --json，无需外部 jq，且不可与 --styled、--markdown、--ids-only、--count 同时使用。
• 分页：列表命令支持 --page、--limit 与 --all（--limit 与 --all 不能同时使用）；--all 仅控制分页，不改变筛选范围。
• 响应结构：统一返回 ok、data、summary、breadcrumbs（上下文下一步操作建议）、context（位置与分页信息）、meta 等字段；创建/更新响应包含 location。
• 面包屑：响应中的 breadcrumbs 提供可直接运行的命令与说明，值（如卡片编号、看板 ID）已预填，占位符需自行替换。

使用方式

全局标志包括 --token、--profile、--api-url（默认 https://app.fizzy.do）、--jq、--json、--quiet、--styled、--markdown、--agent、--ids-only、--count、--limit、--verbose。

配置优先级从高到低为：CLI 标志、环境变量（FIZZY_TOKEN、FIZZY_PROFILE、FIZZY_API_URL、FIZZY_BOARD）、命名配置文件、本地项目配置 .fizzy.yaml、全局配置（~/.config/fizzy/config.yaml 或 ~/.fizzy/config.yaml）。

设置与认证：

fizzy setup                              # 交互式向导
fizzy doctor                             # 安装/配置/认证/API/agent 健康检查
fizzy auth login TOKEN                   # 为当前配置保存 token
fizzy auth login TOKEN --profile agent --account 1
fizzy auth status
fizzy auth list
fizzy auth switch PROFILE
fizzy auth logout
fizzy auth logout --all
fizzy identity show

注册流程分为交互式与非交互式（面向智能体）两种。非交互式步骤为：fizzy signup start --email user@example.com 获取 pending_authentication_token；用户查收邮件中的 6 位验证码后执行 fizzy signup verify --code ABC123 --pending-token eyJ... 获得 session_token；将 session token 写入临时文件（如 /tmp/fizzy-session，并 chmod 600）；新用户执行 fizzy signup complete --name "Full Name" < /tmp/fizzy-session，已有用户执行 fizzy signup complete --account SLUG < /tmp/fizzy-session；随后清理临时文件。token 会优先保存到系统凭据存储，回退到配置文件。

关键约定

• 卡片使用 NUMBER 而非 ID：fizzy card show 42 中的 42 是卡片编号；其他资源使用其 id 字段。
• 卡片描述是字符串（.description），而评论正文是嵌套对象（.body.plain_text）。
• 富文本字段接受 markdown 或 HTML：可用可重复的 --attach PATH 追加内联附件，或在需要精确位置时手动嵌入 <action-text-attachment> 标签。
• 新用户注册成功（is_new_user: true）时响应会包含 welcome_message 字段，需立即向用户展示——这是来自 CEO 的一次性个人留言。
• 遇到设置、配置或认证问题优先运行 fizzy doctor，它是主要的只读健康检查并提供修复提示。
• 列表卡片前应先确认看板上下文（.fizzy.yaml 或 --board 标志）。

适用场景

适合需要通过脚本、流水线或智能体自动化操作 Fizzy 的场景，例如批量查询与筛选卡片、跨看板搜索、按状态或负责人聚合任务、创建与移动卡片、管理评论与步骤、查看通知与活动、维护 Webhook 等。多账户用户可通过命名配置文件区分身份。

限制

• 价格、收费与平台支持等信息原文中暂未提供。
• --jq 不支持在 completion、setup、顶层 skill 及 version 命令上使用（会给出 jq 相关用法错误），且不能与 --styled、--markdown、--ids-only、--count 组合。
• --limit 与 --all 不能同时使用。
• --all 仅影响分页，不改变卡片筛选范围；获取全部状态的卡片需要分多次查询（如开放卡片、已关闭卡片、Not Now 卡片）。
• 获取卡片步骤需使用 card show，列表接口不返回步骤。