One command, every WaveSpeed model. Image, video, audio, 3D — from your terminal.
🌐 wavespeed.ai • 💻 wavespeed.ai/cli • 📚 Models • 📖 Docs • 🐛 Issues
- 🚀 Every WaveSpeed model — image, video, audio, 3D; the full live catalog, not a curated subset
- 🧬 Dynamic per-model help —
wavespeed run <id> -hintrospects the real input schema - 🔗 Aliases — named shortcuts in
wavespeed.jsonthat bundle a model + default inputs - 🤖 Agent-native — pipe-safe
--json, drops aSKILL.mdfor Claude Code / Cursor / Codex - ✨ Zero-friction auth — browser-launching, clipboard-aware login with live key validation
# npm
npm install -g @wavespeed/cli
# or curl
curl -fsSL https://wavespeed.ai/install | bash
# sign in (opens the access-key page, paste to confirm)
wavespeed login# 1. Browse the catalog
wavespeed models # browse the full live catalog, grouped by type
wavespeed models "z-image" # search
wavespeed models --type text-to-video # filter by modality
# 2. Inspect a model's inputs (dynamic — fetched live)
wavespeed run wavespeed-ai/z-image/turbo -h
# 3. Run it (URLs print to stdout; no files unless you ask).
# z-image/turbo returns in ~5s, a good default for trying the CLI.
wavespeed run wavespeed-ai/z-image/turbo \
-p "a cyberpunk skyline at golden hour"
# Save outputs locally
wavespeed run ... -p "..." --download # → ./wavespeed-output/
wavespeed run ... -p "..." --download "./hero.png" # exact path
wavespeed run ... -p "..." --download "./out/{index}.{ext}" # templated for batches
# Pipe-safe JSON
wavespeed run ... -p "..." --json | jq '.outputs[0]'wavespeed init writes one. Drop it into git so the whole team shares the same defaults.
defaultModel—wavespeed run -p "…"(no model arg) uses this. Can itself be an alias name.aliases— your own shortcuts.wavespeed run hero -p "…"expands to model + input. CLI-i k=vflags override.wavespeed run hero -hshows the resolved schema. List them withwavespeed aliases.
Resolution: positional with / is a model ID; otherwise looked up as an alias. Merge order on inputs: alias.input → --input-file → -i k=v → -p. The CLI never mutates the user's prompt or inputs — what you pass is what hits the API.
| Use case | Model |
|---|---|
| Text → image | google/nano-banana-2/text-to-image |
| Image edit | google/nano-banana-2/edit |
| Text → video | bytedance/seedance-2.0/text-to-video |
| Image → video | bytedance/seedance-2.0/image-to-video |
Browse alternatives with wavespeed models <query>.
No MCP server, no daemon. The CLI is the interface — agents already know how to run shell commands.
wavespeed skill install # writes .claude/skills/wavespeed/SKILL.mdThe skill teaches the agent the three-step pattern: models to find, run <id> -h to discover params, run <id> -p "…" --json to execute. Every command supports --json for clean piping.
# auth & config
wavespeed login Browser + paste-key wizard (clipboard-aware)
wavespeed logout Clear stored API key
wavespeed status Show masked key, base URL, useful links
wavespeed config [--default-model …] View / update CLI defaults
# generation
wavespeed run [model|alias] -p "…" Run any model or alias (uses defaultModel if omitted)
wavespeed run <model|alias> -h Dynamic schema-based help (alias-aware)
wavespeed schema <model> Pretty-print a model's input schema
wavespeed models [query] Browse the live catalog (cached 1h)
wavespeed aliases List aliases from wavespeed.json + user config
# files
wavespeed upload <file...> Upload local file(s) → CDN URLs
wavespeed download <url...> Save URLs to disk
# account & history
wavespeed balance Show your current credit balance
wavespeed price <model> -i k=v Estimate the cost of a run (no charge)
wavespeed top-up Open https://wavespeed.ai/top-up
wavespeed history [--limit --status …] List recent predictions (last 24h)
wavespeed show <id> Full details for a past prediction
wavespeed delete <id...> Remove predictions from your history
# misc
wavespeed open [target] Jump to dashboard / models / docs / … in browser
wavespeed init Create a wavespeed.json with defaults + alias stubs
wavespeed skill install Drop SKILL.md for coding agents
| Use when | |
|---|---|
wavespeed login |
Persistent, one machine, one user. Stored in ~/.config/wavespeed-nodejs/config.json. |
WAVESPEED_API_KEY=… wavespeed run … |
CI, scripts, one-off shells. Env var wins over stored config. |
Get a key at wavespeed.ai/accesskey.
git clone https://github.com/WaveSpeedAI/wavespeed-cli.git
cd cli
npm install
npm run dev -- run wavespeed-ai/z-image/turbo -p "a serene mountain lake"
npm run build && npm linkStack: TypeScript, Commander, Inquirer, Chalk, Ora, the official wavespeed SDK.
MIT — see LICENSE.
{ "defaultModel": "google/nano-banana-2/text-to-image", "outputDir": "wavespeed-output", "aliases": { "hero": { "model": "google/nano-banana-2/text-to-image", "input": { "aspect_ratio": "16:9", "resolution": "2k" } }, "social": { "model": "google/nano-banana-2/text-to-image", "input": { "aspect_ratio": "1:1", "resolution": "1k" } }, "vid": { "model": "bytedance/seedance-2.0/text-to-video", "input": { "resolution": "720p", "duration": 5 } } } }