Skip to content

quickdesignio/quickdesign-cli

BranchesTags

Repository files navigation

@quickdesign/cli

npm node license

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

There are two ways to install. Pick whichever matches how you use Claude Code today.

Option A — npm (CLI binary + skill bundle, classic)

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

This installs the quickdesign binary AND copies the Claude Code skill into ~/.claude/skills/quickdesign/. Best for standalone CLI users + scripted/CI use.

Option B — Claude Code plugin marketplace

# Inside Claude Code:
/plugin marketplace add ottasilver/quickdesign-cli
/plugin install quickdesign@quickdesign

# Still need the binary on PATH for actual generation:
npm install -g @quickdesign/cli

The plugin distributes the skill (SKILL.md + references/ + pipelines/ + models/) under ~/.claude/plugins/quickdesign/. New skill versions reach you whenever you run /plugin marketplace update — no manual quickdesign init --skill-only --force required. The quickdesign binary itself still ships via npm; the plugin keeps distribution lean by not bundling node binaries.

If you already used Option A, you can keep it — the plugin install lives alongside ~/.claude/skills/quickdesign/ without conflict. For a clean switch: rm -rf ~/.claude/skills/quickdesign after the plugin is installed.

Requires Node.js ≥ 18.17 either way.

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

Variable Purpose
QUICKDESIGN_BASE_URL Override API base URL (default https://app.quickdesign.io)
QUICKDESIGN_TOKEN Override the stored token (takes precedence over auth.json)
QUICKDESIGN_SUPABASE_URL Override Supabase REST base (default: prod project). Used only by design subcommands.
QUICKDESIGN_SUPABASE_ANON_KEY Supabase anon key. Required for design subcommands (PostgREST-direct; RLS scopes to user).

Commands (v0.3)

init — bootstrap

Command Notes
init [--force] [--skill-only] [--no-skill] [--no-auth] [--no-doctor] [--skill-dir <path>] One-shot setup: ffmpeg doctor + bundled Claude Code skill + browser login

auth

Command Notes
login Browser OAuth + parallel terminal-paste fallback (CI flags: --token, --token-stdin, --timeout <ms>)
logout Delete the stored token
whoami Show the active user, token expiry, live ping
`auth config show get

spy — Spy Brands

Command Notes
brands [--search] [--limit] List / search brands
brand <brandId> Fetch one brand
brand-ads <brandId> [--status] [--sort] [--limit] List a brand's ads
best-ads [--limit] [--category-id] [--status] Top ads cross-brand
search <query> Convenience alias for brand search
for-you Personalized feed (auth required)
trending Trending feed

image

Command Notes
generate --prompt … [--model] [--wait] [-o path] Async start + optional poll + optional save
status <requestId> One-shot status check
wait <requestId> [--timeout] [-o path] Resume polling on a job started earlier and optionally download
result <requestId> [-o path] Fetch finished job result
history [--limit] List past image jobs
models Discover available image models

video — Sora 2 / Kling / Seedance 2.0 / UGC

Command Notes
generate --provider <sora2|kling|seedance|ugc> --prompt … [--image | --reference-image…] [--audio] [--duration] [--aspect-ratio] [--resolution] [--wait] [-o path] Start + optional poll + optional save. Seedance 2.0 r2v is activated by --reference-image (1+). UGC requires both --image and --audio.
status <provider> <jobId> One-shot status check
wait <provider> <jobId> [--timeout] [-o path] Resume polling on a job started earlier (default timeout 30 min) and optionally download
history <provider> [--limit] [--status] List jobs for a provider
upscale --video <url> --provider <topaz|bytedance> [--factor] [--wait] [-o path] Kick off a Topaz/ByteDance video upscale
upscale-status <jobId> One-shot status check
upscale-wait <jobId> [--timeout] [-o path] Resume polling on an upscale job
upscale-history [--limit] List upscale jobs
subtitle <video> [--style default|tiktok|minimal|karaoke|reels-pop] [--language] [--font-name] [--font-size] [--position] [--wait] [-o path] Burn karaoke-style auto-subtitles into a video (ElevenLabs ASR + libass; ~$0.03/min). Default preset: Montserrat 65px bold, 5 words/line, bottom-positioned, yellow highlight. Local files are auto-uploaded to R2.
subtitle-status <jobId> One-shot status check
subtitle-history [--limit] List subtitle jobs

brand

Command Notes
scrape <url> Sync scrape — returns colors, fonts, logo, description
dna <url> [--output json|events] Full Brand DNA via Claude (SSE). Default prints the final JSON; --output events emits NDJSON of every frame (agents)

ad-creator — Smart Ad Creator

Command Notes
concepts [--human] List available concept slugs
analyze <product-url> Extract product name, images, features, audience
generate --product-url --concept <slug> [--brand-kit] [--wait] [-o path] Single-concept async job
advantage-plus --product-url [--brand-kit] [--wait] [-o dir] Fan out 16 concepts. With -o <dir>, every completed concept is saved to <dir>/<concept>.jpg
status <requestId> One-shot status check
wait <requestId> [--timeout] [-o path] Resume polling on a single ad job
batch-status <batchId> One-shot batch status
batch-wait <batchId> [--timeout] [-o dir] Resume polling on an advantage+ batch + download every completed concept

design

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

Command Notes
list [--limit] [--offset] [--category] [--assets-only] [--archived] Your designs (most recent first)
get <id> Full row
delete <id> Soft-delete (sets isArchived = true)
download <id> -o <path> Save the design's image or video to disk

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

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

26 tags

Packages

 
 
 

Contributors

Languages