| name | fizzy-cli-extras |
| description | Thin wrapper around Basecamp's `fizzy` CLI (https://github.com/basecamp/fizzy-cli) for
surface area the existing `/fizzy` skill does NOT cover: cross-board search, file uploads,
and multi-account auth juggling (Vetted ↔ Congrats Fizzy contexts). For ALL other Fizzy
actions (cards, comments, columns, board/column IDs, user IDs, engineering board template,
column-move via POST /triage.json, comment HTML formatting, etc.) defer to `/fizzy`.
|
| triggers | ["fizzy search","fizzy upload","fizzy auth","fizzy identity","search fizzy cards","find fizzy card","upload to fizzy"] |
| invocable | true |
fizzy-cli-extras
Adjunct to /fizzy. Covers ONLY: search, upload, auth/identity.
For cards/comments/columns/boards/assignments → use /fizzy (still the authority).
For edge-function Fizzy calls → use supabase/functions/_shared/fizzyClient.ts (CLI can't run in Deno).
Hard rules
- Never run
fizzy auth login. Token resolves via the fizzy() shell function in ~/.zshrc which reads FIZZY_API_TOKEN from the current repo's .env.local. Two token stores = drift.
- Always guard CLI invocations with availability check — CI runners and teammates without the local install must still work:
if ! command -v fizzy >/dev/null 2>&1; then
echo "fizzy CLI not installed — use /fizzy raw-curl patterns instead"
exit 1
fi
- Never edit submodule
/fizzy skill to call this CLI. This skill is project-local on purpose. Cross-repo coupling stays via the existing submodule.
- Don't upgrade fizzy without re-running impact analysis — JSON shape changes can break dependent skills silently. v3.0.3 is the validated version as of this skill's authoring.
- Defer to
/fizzy for any action this skill's triggers don't explicitly cover. Do not re-implement card/comment/column commands here.
Token + account setup (one-time, outside the agent)
Install:
curl -fsSL https://raw.githubusercontent.com/basecamp/fizzy-cli/master/scripts/install.sh | bash
Add to ~/.zshrc (PATH first, function second):
export PATH="$HOME/.local/bin:$PATH"
fizzy() {
local dir="$PWD"
local token=""
while [ "$dir" != "/" ]; do
if [ -f "$dir/.env.local" ]; then
token=$(grep ^FIZZY_API_TOKEN "$dir/.env.local" 2>/dev/null | cut -d= -f2- | tr -d '"')
break
fi
dir=$(dirname "$dir")
done
if [ -n "$token" ]; then
FIZZY_TOKEN="$token" FIZZY_ACCOUNT=6102589 command fizzy "$@"
else
command fizzy "$@"
fi
}
Reload + verify:
source ~/.zshrc
cd ~/code/repos/vettedai-audition-supabase-version
fizzy board list
The function walks up from $PWD to find .env.local, so it works from any of the three Fizzy-enabled repos (vettedai-audition, congrats, backend-restructing). Account 6102589 is shared across all three (same Generous Circle org).
What this skill does NOT do
| Action | Use instead |
|---|
| Create/move/comment on cards | /fizzy |
| Assign Elvis (QA) or Oussama (backend) | /fizzy (user IDs live there) |
| Look up board/column IDs (Bugs, Vetted, Congrats, Product) | /fizzy |
| Engineering board column template | /fizzy |
| Edge-function Fizzy calls | supabase/functions/_shared/fizzyClient.ts |
| CI/GitHub Actions Fizzy calls | Raw curl (CLI not installed on runners) |
| Webhooks | Not in v3.0.3; use raw API or wait for upstream |
| Tags / notifications / pins / reactions | CLI supports these but we don't automate them — use /fizzy curl if needed |
Commands this skill covers
Search (the flagship — no equivalent in /fizzy)
fizzy search "<query>"
fizzy search "<query>" --board <id>
Use when: finding cards by content across boards without knowing the card number. Faster than scrolling Fizzy UI. Output is JSON; pipe to jq:
fizzy search "P0" | jq '.data[] | {number, title, board: .board.name}'
Upload (file attachments)
fizzy upload <file>
fizzy card update <card> --attach ...
Use when: posting screenshots, logs, or other binary artifacts to a card. The pure-REST flow for this was undocumented in /fizzy and would have required multipart upload handling.
Auth / identity (multi-account juggling)
fizzy auth status
fizzy identity
Use when: confirming which Fizzy account the CLI is hitting. Note: the fizzy() function in ~/.zshrc hardcodes FIZZY_ACCOUNT=6102589 (Generous Circle). If you ever need a different account, edit the function — don't run fizzy auth login.
Output format
CLI emits JSON by default. Every response wraps in {success, data}. Pipe to jq for parsing:
fizzy board list | jq '.data[] | {name, id}'
fizzy search "auth" | jq '.data | length'
Failure modes + fallbacks
| Symptom | Likely cause | Action |
|---|
command not found: fizzy | CLI not installed on this machine | Fall back to /fizzy raw-curl patterns; do not block on install |
Not authenticated from fizzy auth status | .env.local missing in this dir tree, or FIZZY_API_TOKEN blank | cd to a repo that has .env.local; verify grep ^FIZZY_API_TOKEN .env.local returns a value |
No account configured | Function didn't set FIZZY_ACCOUNT | Check ~/.zshrc function still hardcodes FIZZY_ACCOUNT=6102589 |
| CLI hangs on network | Flaky connection | Ctrl+C and retry; wrap unattended calls with timeout 30s fizzy ... |
| Output JSON shape changed unexpectedly | Newer CLI version installed | Check fizzy version; this skill validated against v3.0.3 |
When to expand this skill's scope
Phase 3 of the rollout plan may migrate ONE call site in /qa-handoff (the comment-post step) to fizzy comment create — gated behind the command -v fizzy guard above. That migration lives in the submodule /qa-handoff skill, NOT here. This skill's surface stays narrow until a Phase 4 decision gate re-runs impact analysis.
References
- CLI repo: https://github.com/basecamp/fizzy-cli
- Validated CLI version: v3.0.3
- Existing
/fizzy skill (authoritative for cards/comments/columns): submodules/skill-master/.agent/skills/fizzy/SKILL.md
- Raw API gotchas:
.claude/rules/fizzy-api-patterns.md (still authoritative for /fizzy and fizzyClient.ts)
- Edge fn client:
supabase/functions/_shared/fizzyClient.ts
