@quickdesign/cli

Command-line interface for QuickDesign — built so anyone (or any Claude Code agent) can drive the full QuickDesign stack from a terminal:

• Generate AI images (Nano Banana, GPT Image) and videos (Sora 2, Kling, Seedance 2.0 including reference-to-video, UGC) — start, poll, save to disk in one command.
• Smart Ad Creator — turn a product URL into a single concept ad, or fan out 16 concepts in parallel (Advantage+).
• Spy Brands — query the competitor ad library: per-brand ads, cross-brand winners, this-week trends.
• Brand DNA — scrape a website's colors / fonts / logo, or run the full Claude-streamed Brand DNA extraction (voice, audience, offer).
• Designs — list, fetch, download, or archive your saved creatives directly from PostgREST.
• Ship-ready — JSON to stdout, diagnostics to stderr, exit codes for pipelines, optional --human pretty-print.

Install

npm install -g @quickdesign/cli
quickdesign init        # one-time bootstrap: doctor + skill + login

Requires Node.js ≥ 18.17.

init does NOT run automatically after npm install. That would break CI/scripted installs and silently mutate ~/.claude/skills/ without consent. You run it once, on purpose, the first time you use the CLI on a machine. After that, every quickdesign … call just works.

quickdesign init does three things, each independently skippable:

1. Doctor — checks for ffmpeg / ffprobe (needed for multi-segment video pipelines). Warns + prints install hints if missing; never blocks.
2. Skill install — copies the bundled Claude Code skill into ~/.claude/skills/quickdesign/. Refuses to overwrite existing files unless --force.
3. Auth login — opens the browser handshake (or falls back to terminal paste; see Authentication).

quickdesign init                       # full bootstrap
quickdesign init --skill-only          # just install the skill
quickdesign init --no-skill            # skip skill, just doctor + login
quickdesign init --no-auth             # CI / scripted setups
quickdesign init --no-doctor           # skip ffmpeg check
quickdesign init --force               # overwrite existing skill files
quickdesign init --skill-dir ~/my/skills/quickdesign   # custom target

For one-shot use without a global install:

npx -y @quickdesign/cli init

Quickstart

# After `quickdesign init` you're already logged in. Verify:
quickdesign whoami

# --- Spy Brands ---------------------------------------------------------
quickdesign spy brands --search "Kizik" --human
quickdesign spy brand-ads <brand-id> --status active --sort most_impressions --limit 5

# --- Image: studio shot, save to disk -----------------------------------
quickdesign image generate \
  --prompt "studio photo of a silver bracelet on white background" \
  --model nano-banana-2 --wait -o ./bracelet.jpg

# --- Video: Seedance 2.0 r2v with two reference images ------------------
quickdesign video generate --provider seedance \
  --reference-image https://cdn.example.com/bracelet.jpg \
  --reference-image https://cdn.example.com/model.jpg \
  --prompt "@Image2 wearing @Image1, slow catwalk" \
  --aspect-ratio 9:16 --duration 5 --wait -o ./catwalk.mp4

# --- Smart Ad Creator: 16 concepts in parallel --------------------------
quickdesign ad-creator advantage-plus \
  --product-url https://kizik.com/products/bowen-black --wait -o ./ads
ls ./ads/   # one .jpg per completed concept

# --- Brand DNA (Claude-streamed) ----------------------------------------
quickdesign brand dna https://kizik.com

# --- Your designs -------------------------------------------------------
export QUICKDESIGN_SUPABASE_ANON_KEY="<your supabase anon key>"
quickdesign design list --limit 10
quickdesign design download <id> -o ./out.jpg

Authentication

quickdesign login opens the default browser, waits for the QuickDesign web app to hand back a token, and writes it to:

~/.config/quickdesign/auth.json  (0600)

The file holds the access token + refresh token, so subsequent commands transparently refresh expired sessions without re-prompting.

Manual paste fallback. Some environments (corporate VPN, container, remote SSH, browsers that block HTTPS→localhost) can't deliver the token over the loopback handshake. While quickdesign login is running, the browser tab also displays the access token in a copy box — paste it into the same terminal where login is waiting, press Enter, and it accepts the token directly. Whichever path finishes first wins; the other is cancelled cleanly.

For CI, skip the browser entirely:

QUICKDESIGN_TOKEN=<supabase-jwt> quickdesign spy brands
# or
quickdesign login --token <supabase-jwt>
# or
cat my-token.txt | quickdesign login --token-stdin

Logout / inspect config:

quickdesign logout
quickdesign auth config show
quickdesign auth config set baseUrl http://localhost:3001   # local dev

Environment variables

Commands (v0.3)

init — bootstrap

auth

spy — Spy Brands

image

video — Sora 2 / Kling / Seedance 2.0 / UGC

brand

ad-creator — Smart Ad Creator

design

PostgREST-direct (user JWT + RLS). Requires QUICKDESIGN_SUPABASE_ANON_KEY.

Long-running jobs

Video generations and Advantage+ batches commonly take 5–15 minutes. The CLI is polling-only (no inbound webhook into your laptop), so you have three options:

1. Block in the foreground. Pass --wait -o ./out.mp4 and the CLI polls + downloads in one step. --timeout <ms> controls the cap (default 15 min for video, 30 min for upscale and batches).

2. Fire-and-forget, resume later. Start the job, capture the request id, walk away, then resume:

# start (returns immediately)
JOB=$(quickdesign video generate --provider seedance \
  --image https://cdn/foo.jpg --prompt "..." | jq -r '.request_id')
echo $JOB > /tmp/myjob.id

# minutes later — same machine, another terminal, or even a cron tick
quickdesign video wait seedance "$JOB" --timeout 1800000 -o ./out.mp4

wait re-polls the BFF, downloads when ready, and prints the same JSON shape as --wait would have.

3. Background it. nohup quickdesign video generate ... --wait -o ./out.mp4 > job.log 2>&1 & then tail -f job.log.

For Advantage+ batches use ad-creator batch-wait <batchId> -o ./ads — same idea but downloads every completed concept to the directory.

The job state itself lives in the BFF (ugc_video_jobs / image_generation_jobs tables) so you can leave a job for hours and pick it up later. Result URLs (R2) don't expire.

Claude Code skill

The npm package bundles a complete Claude Code skill (SKILL.md + per-domain reference docs covering image / video / Spy Brands / Brand DNA / UGC pipelines). The recommended way to install it is quickdesign init (see Install) — it copies the bundle into ~/.claude/skills/quickdesign/ and Claude Code picks it up on the next session.

If you want to inspect or copy it manually instead, the bundled source lives at:

$(npm root -g)/@quickdesign/cli/skills/quickdesign/

Once installed, asking Claude Code things like "generate a UGC ad for this product page" or "analyze Kizik's recent ads" will route through the skill, which calls quickdesign … on your behalf.

Development

git clone https://github.com/ottasilver/quickdesign-cli
cd quickdesign-cli
npm install
npm run build
npm link                           # makes `quickdesign` available on PATH

# point at a local BFF
export QUICKDESIGN_BASE_URL=http://localhost:3001
export QUICKDESIGN_TOKEN="<your local supabase jwt>"

quickdesign whoami
quickdesign spy brands --search anything --limit 3 --human

Releasing

Publishes are automated via GitHub Actions (.github/workflows/publish.yml). A tag push to main triggers npm publish.

One-time repo setup (maintainers):

1. Create a granular access token on npm — scope @quickdesign, read+write, bypass-2FA.
2. Add it to the repo as a GitHub secret named NPM_TOKEN (Settings → Secrets and variables → Actions).

Cut a release:

# bump + tag + commit
npm version patch        # or: minor / major
git push --follow-tags   # CI takes over, runs build + publish

# dry-run via Actions UI:
gh workflow run publish.yml -f dry_run=true

The workflow also verifies the git tag matches package.json#version before publishing, so v0.1.2 tag + package.json: 0.1.1 will fail loudly rather than mis-tag the release.

Roadmap

• v0.1 ✅ — Auth (browser OAuth + token fallbacks), spy, image, Claude Code skill
• v0.2 ✅ — video (Sora 2 / Kling / Seedance 2.0 incl. r2v / UGC + upscale), brand (scraper + SSE DNA), ad-creator (single + advantage+), design (list / get / delete / download — PostgREST-direct)
• v0.3 ✅ — init bootstrap (doctor + bundled skill + login), video subtitle (auto-subtitle / karaoke), refresh-token handling, browser-OAuth Chrome PNA fix + parallel terminal-paste fallback
• v0.4 — local-file sources (--image ./foo.jpg) via auto-upload to R2
• v1.0 — plugins, opt-in telemetry, Homebrew tap

License

MIT