fizzyx

CLI tool for Fizzy board workflow, OSS/S3-compatible storage, and OpenAPI client generation.

Install

bun add -g @puffinstudio/fizzyx

Flow Commands

Manage a Fizzy board from a repository-local .fizzy.yaml.

Setup

fizzyx setup <board-id>
fizzyx auth login <token>
fizzyx auth status
fizzyx flow mine --fresh

flow doctor can still be run for an explicit health check, but new fizzyx flow ... commands auto-repair workflow columns and ids when needed.

Create A Card (Manual)

Use --draft to create a unique project-local draft file. This automatically creates .fizzyx/ when needed and avoids collisions between multiple agents.

draft=$(fizzyx flow template --draft)
$EDITOR "$draft"
fizzyx flow add Ellen "Implement feature" --desc "$draft"
rm "$draft"

You can also pipe or provide your own file:

fizzyx flow template
fizzyx flow add <user> "<title>" --desc <file|->

Work A Card

fizzyx flow mine --fresh
fizzyx flow next --fresh
fizzyx flow next --fresh --start
fizzyx flow show <card>
fizzyx flow start <card>
fizzyx flow complete-steps <card>
fizzyx flow done <card> "commit <sha>: <subject>"

flow done requires all steps to be complete and closes the card into Done.

Other Flow Commands

fizzyx flow sync
fizzyx flow status [--fresh]
fizzyx flow assign <card> <user|me> [user...]
fizzyx flow block <card> "<reason>"
fizzyx flow repair-markdown <card>
fizzyx flow standardize <card> (alias: std)
fizzyx flow standardize-all (alias: std-all)
fizzyx flow workflow
fizzyx flow skill
fizzyx flow skill init [--force]

• flow assign <card> me assigns the card to the authenticated Fizzy user.
• flow assign skips users who are already assigned.
• flow block moves the card to Not Now.
• flow workflow, flow skill, and flow template prefer project-local overrides under .agents/skills/fizzyx/.

Planner Dashboard

Start a local planner dashboard backed directly by the Fizzy API:

fizzyx planner start
fizzyx planner snapshot
fizzyx planner snapshot --auto-fix
fizzyx planner health
fizzyx planner repair-metadata
fizzyx planner repair-metadata --apply
fizzyx planner repair-metadata --apply --default-priority p2 --default-type chore

planner snapshot prints the same JSON used by the web dashboard. Project workflow uses BACKLOG → READY → IN PROGRESS → REVIEW → DONE, with DONE coming from closed cards and BLOCKED from Not Now/postponed cards.

planner repair-metadata is dry-run by default. It inserts/syncs deterministic frontmatter from existing tags and assignees. Missing priority/type are only filled when explicit defaults are passed.

Planner conventions use tags for filtering:

priority:p0 priority:p1 priority:p2
type:bug type:feature type:chore type:blocker
area:frontend area:api phase:integration

Cards can also include frontmatter for richer project details:

---
priority: P1
type: feature
owner: ellen
depends_on: [123]
api_status: not_connected
---

OSS Commands

Manage S3-compatible object storage (Alibaba Cloud OSS, AWS S3, MinIO, etc.).

Setup

# Interactive — prompts for keys, stores in OS keychain
fizzyx oss setup

# With explicit config (keys are prompted separately)
fizzyx oss setup --env dev --endpoint https://oss-cn-beijing.aliyuncs.com --region cn-beijing --local-dir ./public [--bucket my-bucket] [--remote-prefix assets]

# Configure keys for an existing environment
fizzyx oss setup --env dev

• --endpoint and --region are required
• --bucket is optional — omit if your endpoint already includes the bucket name (e.g. https://my-bucket.oss-cn-beijing.aliyuncs.com)
• --remote-prefix is optional — omit to upload to bucket root
• Credentials are stored in OS keychain via Bun.secrets, never in config files or shell history
• Without --env, keys are stored as default — all environments fall back to it

Sync

Upload local files to the remote bucket:

fizzyx oss sync [--env dev] [--full] [--no-urls] [--verify]

• --env: environment name (default: dev)
• --full: ignore cached manifest, force full re-upload
• --no-urls: suppress file URL output
• --verify: check remote existence before skipping (re-upload if deleted remotely)

Sync uses a two-stage check (mtime+size → SHA-256 hash) to skip unchanged files. The manifest is stored at .fizzyx/oss-manifest.json and can be committed for team sharing.

During sync, a live progress bar shows current file, progress, and status:

  ◐ dev [████░░░░░░░░░░░░] 25%  ↑ filename.jpg

List

List objects in the remote bucket in a tree view with file sizes:

fizzyx oss ls [--env dev] [--prefix assets/]

└── assets/
    └── Monkey_D._Luffy_Anime_Post_Timeskip_Infobox.webp  126.2 KB

• --prefix: filter objects by key prefix

Status

Show sync status (pending uploads, manifest info):

fizzyx oss status [--env dev]

List exact pending files without uploading:

fizzyx oss status --files

OpenAPI Commands

Generate a typed API client from an OpenAPI spec.

Generate

fizzyx openapi generate -i <url|path> -o <dir> -c wx

Options:

| Flag | Description | | -------------------------- | ------------------------------------------------------- | | -i, --input <url\|path> | OpenAPI spec URL or file path (JSON/YAML) | | -o, --output <dir\|file> | Output directory (or .ts path for custom api name) | | -c, --client <name> | Client target (wx) | | --api-name <name> | API filename (default: api.ts) | | --types-name <name> | Types filename (default: types.ts, false to inline) | | --runtime-name <name> | Runtime filename (default: wx-request.ts) | | --run <script\|cmd> | npm script or shell command after generation |

If --input/--output/--client are omitted, values from .fizzy.yaml openapi[0] are used.

Output is 3 files — runtime, types, and tree-shakeable endpoint functions:

src/api/
  ├── wx-request.ts   # runtime (configure, setToken, onError, request)
  ├── types.ts        # named interfaces / enums / aliases
  └── api.ts          # tree-shakeable export functions + param types

Generated Runtime API

import { configure, setToken, onError, initToken } from "./api";

// Setup at app startup
configure({ baseUrl: "https://api.example.com", storageKey: "myapp_token" });

// Or with custom logger + hooks
configure({
	baseUrl: "https://api.example.com",
	storageKey: "tb_token",
	logger: { error: myReporter, warn: () => {}, info: () => {}, debug: () => {} },
	hooks: [
		{ onError: (ctx) => wx.showToast({ title: ctx.message }) },
		{ onSuccess: (ctx) => reportAnalytics(ctx) },
	],
});

// Token auto-loads from storage. Explicit load if needed:
await initToken();

// Token persists to storage on set
setToken("jwt...");
setToken(null); // logout, clears storage

Logger vs Hooks:

• Logger controls output (console, file, sentry). Default: console.error/warn/info/debug with [fizzyx] prefix.
• RequestHook fires business callbacks at lifecycle points (onRequest, onSuccess, onError). Use for toast, analytics, loading state.

Generated Endpoint API

Each endpoint is a standalone export function with typed params:

import { listPets, createPet, ListPetsQueryParams } from "./api";

// GET with query params
const pets = await listPets({ query: { limit: 10, status: "available" } });

// POST with body
const pet = await createPet({ name: "Fluffy" });

// POST without requestBody (no data param generated)
const result = await someAction();

• No createApi() wrapper — tree-shakeable by default
• Each function exports its param types (ListPetsQueryParams, CreatePetPathParams)
• JSDoc comments from OpenAPI description/summary on endpoints and params

List Generators

fizzyx openapi list

Initialize OpenAPI config

fizzyx openapi init

Config (.fizzy.yaml)

openapi:
  - input: ./openapi.json
    output: ./src/api
    client: wx
    api_name: sdk.ts
    types_name: types.ts
    runtime_name: wx-request.ts
    run: check

Config File (.fizzy.yaml)

Minimal OSS-only config:

oss:
  dev:
    endpoint: https://oss-cn-beijing.aliyuncs.com
    region: cn-beijing
    bucket: my-bucket
  sync:
    local_dir: ./public
    remote_prefix: assets
    concurrency: 10

If your endpoint already contains the bucket in the hostname, bucket can be omitted:

oss:
  dev:
    endpoint: https://my-bucket.oss-cn-beijing.aliyuncs.com
    region: cn-beijing
  sync:
    local_dir: ./public

Credential Resolution

Credentials are resolved in this priority order:

1. OS keychain (Bun.secrets — set via fizzyx oss setup)
2. Environment variables: OSS_<ENV>_ACCESS_KEY_ID / OSS_<ENV>_SECRET_ACCESS_KEY
3. .fizzy.yaml access_key_id / secret_access_key fields (legacy, discouraged)

Credentials stored as default (without --env) are used as a fallback for all environments when no env-specific key is found. This means you only need to run fizzyx oss setup once — dev, prod, and any other env will reuse the same keys.