fizzy

/fizzy - Fizzy ワークフローコマンド

CLI で完全に操作できます。ボード、カード、列、コメント、ステップ、リアクション、タグ、ユーザー、通知、ピン留め、Webhook、アカウント設定、検索、ボードの移行に対応しています。

エージェントの不変条件

必ず次のルールに従ってください：

1. カードには ID ではなく NUMBER を使用します — 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	機械可読な JSON 出力に組み込みの jq フィルターを適用します（外部 jq は不要です。--json を暗黙的に指定します。または、--quiet／--agent を指定した場合は生データをフィルタリングします。completion、setup、トップレベルの skill、および jq 固有の使用方法エラーが発生する version では未サポートです。--styled、--markdown、--ids-only、--count とは併用できません）
--json	JSON エンベロープ形式で出力します
--quiet	エンベロープなしの生 JSON データを出力します
--styled	人が読みやすいスタイル付きの出力（テーブル、色）
--markdown	GFM Markdown 形式で出力します（エージェント向け）
--agent	エージェントモード（デフォルトは quiet。--json／--markdown と併用できます）
--ids-only	1 行につき 1 つの 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

手順ごと（エージェント向け）：

# 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桁のコードを確認する必要があります。 セッショントークンは一時ファイルに書き込まれ、シェルの履歴やエージェントの会話コンテキストに漏れないよう、標準入力経由で渡されます。 トークンは、利用可能な場合はシステムの認証情報ストアに保存され、利用できない場合は設定ファイルに保存されます。プロファイルと API URL は ~/.config/fizzy/（推奨）または ~/.fizzy/ に保存されます。

新規ユーザー向けウェルカムメッセージ： signup complete --name が成功すると（新規ユーザーの場合）、応答に is_new_user: true と welcome_message フィールドが含まれます。エージェント不変条件 #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"	""bug" の検索結果7件"
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 の形式

重要： カードには2種類の識別子があります。

フィールド	形式	用途
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'

---

コマンドリファレンス

ID

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)

ステップ（To-Do 項目）

ステップは 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	Web URL
comments_url	string	コメントエンドポイントの URL
board	object	ネストされたボード（下記参照）
creator	object	ネストされたユーザー（下記参照）
assignees	array	User オブジェクトの配列
tags	array	Tag オブジェクトの配列
steps	array	card show のみに含まれます。list には含まれません

ボードスキーマ

フィールド	型	説明
id	string	ボード ID（CLI コマンドで使用）
name	string	ボード名
all_access	boolean	すべてのユーザーがアクセスできます
auto_postpone_period_in_days	integer	カードが自動延期されるまでの非アクティブ日数
created_at	timestamp	ISO 8601
url	string	Web 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	Web 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	Web 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	Web URL

リアクションスキーマ

フィールド	型	説明
id	string	リアクション ID（CLI コマンドで使用）
content	string	絵文字
url	string	Web URL
reacter	object	ネストされたユーザー

アイデンティティスキーマ（identity showより）

フィールド	型	説明
accounts	array	Account オブジェクトの配列
accounts[].id	string	アカウント ID
accounts[].name	string	アカウント名
accounts[].slug	string	アカウントのスラッグ（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 が正しいことを確認してください。カードでは ID ではなく NUMBER を使用します。

アクセス拒否（終了コード 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