WaveSpeed CLI

One command, every WaveSpeed model. Image, video, audio, 3D — from your terminal.

🌐 wavespeed.ai • 💻 wavespeed.ai/cli • 📚 Models • 📖 Docs • 🐛 Issues

---

Features

• 🚀 Every WaveSpeed model — image, video, audio, 3D; the full live catalog, not a curated subset
• 🧬 Dynamic per-model help — wavespeed run <id> -h introspects the real input schema
• 🔗 Aliases — named shortcuts in wavespeed.json that bundle a model + default inputs
• 🤖 Agent-native — pipe-safe --json, drops a SKILL.md for Claude Code / Cursor / Codex
• ✨ Zero-friction auth — browser-launching, clipboard-aware login with live key validation

Install

# npm
npm install -g @wavespeed/cli

# or curl (script lives on GitHub; wraps `npm install -g` with a
# friendlier error path)
curl -fsSL https://raw.githubusercontent.com/WaveSpeedAI/wavespeed-cli/main/install.sh | bash

# macOS / Linux with Homebrew (standalone executable, no Node.js needed)
brew tap wavespeedai/tap
brew trust wavespeedai/tap   # recent Homebrew refuses formulae from an untrusted tap
brew install wavespeed

# no Node.js/npm? install.sh falls back to a standalone executable on macOS/Linux;
# on Windows (PowerShell):
irm https://raw.githubusercontent.com/WaveSpeedAI/wavespeed-cli/main/install.ps1 | iex

# sign in (opens the access-key page, paste to confirm)
wavespeed login

Quick start

# 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]'

Project config (wavespeed.json)

wavespeed init writes one. Drop it into git so the whole team shares the same defaults.

{
  "defaultModel": "bytedance/seedream-v5.0-pro",
  "outputDir": "wavespeed-output",
  "aliases": {
    "hero":   { "model": "bytedance/seedream-v5.0-pro",
                "input": { "aspect_ratio": "16:9", "resolution": "2k" } },
    "social": { "model": "bytedance/seedream-v5.0-pro",
                "input": { "aspect_ratio": "1:1",  "resolution": "1k" } },
    "vid":    { "model": "wavespeed-ai/minimax-h3/text-to-video",
                "input": { "resolution": "768p", "duration": 5 } }
  }
}

• 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=v flags override. wavespeed run hero -h shows the resolved schema. List them with wavespeed 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 rewrites your prompt or input values. The one way to hand it a local file is the explicit @ marker below — bare paths are passed through untouched, never uploaded.

Local files as inputs. -i image=@./cat.png (curl-style) uploads the file and submits its hosted URL — no separate wavespeed upload step. Only @-prefixed values upload; a missing @ file is an error. Identical bytes are content-hash cached for 24h, so repeated runs (and price --upload) reuse one upload and spare your quota.

Recommended starting models

For plain images and videos, the shortcuts pick the endpoint for you and use the same models as the WaveSpeed /chat page:

wavespeed generate image "a cyberpunk skyline at golden hour" --json
wavespeed edit image "replace the background with a sunlit kitchen" --image @./photo.jpg --json
wavespeed generate video "slow push-in on a lighthouse at dusk" --estimate --json   # price first, nothing submitted
wavespeed edit video "make it snow" --video @./clip.mp4 --json
wavespeed extend video "the camera keeps rising" --video @./clip.mp4 --json

	Default	Alternatives (-m)
Image	seedream-5-pro	gpt-image-2.5, nano-banana-2.1, nano-banana-pro, nano-banana-2, gpt-image-2
Video	seedance-2.5	seedance-2.5-turbo, kling-4.0, wan-3.0, wan-3.0-prime, minimax-h3 (cheap and fast, native stereo audio, 768p by default), Seedance 2.0 tiers

For everything else (audio, 3D, upscaling, a specific endpoint), find the model with wavespeed models <query> and call it with wavespeed run <model-id>.

Use from coding agents

The CLI needs no MCP server or daemon: agents already know how to run shell commands. If your agent supports MCP, the WaveSpeed MCP server offers the same actions as tools, and the skill covers both.

wavespeed skill install        # writes .claude/skills/wavespeed/SKILL.md and .agents/skills/wavespeed/SKILL.md

The skill teaches the agent the shortcuts for images and videos (generate, edit, extend, with the default models), and for everything else 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.

OpenCode loads the same file with no extra steps — .claude/skills/ is on its skill search path. For the MCP tools as well, add the plugin to your OpenCode config — "plugin": ["@wavespeed/opencode"] — and run opencode mcp auth wavespeed (WaveSpeedAI/wavespeed-opencode).

Codex reads .agents/skills/, which the same command writes. For a one-line install that also wires up the MCP server: codex plugin marketplace add WaveSpeedAI/codex-plugin-wavespeed-cli (WaveSpeedAI/codex-plugin-wavespeed-cli).

DeepSeek Harness (dsh): the same skill is packaged for dsh's .dsh/skills layout at WaveSpeedAI/wavespeed-dsh-skill.

Kimi Code CLI reads .claude/skills/ too, so wavespeed skill install is enough. For a one-line install that also wires up the MCP server, use the plugin: /plugins install https://github.com/WaveSpeedAI/wavespeed-kimi-plugin (WaveSpeedAI/wavespeed-kimi-plugin).

Commands

# 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
wavespeed upgrade [--check] [--json]     Upgrade to the latest version (--check only reports)
wavespeed setup [agent]                  Point a coding agent (claude, codex, gemini, opencode, openclaw, hermes, kilo, cline, qwen, droid, crush, aider, continue, goose, miniagent, dsh) at the WaveSpeed LLM gateway (--dry-run, --undo, --model)

# generation
wavespeed run [model|alias] -p "…"       Run any model or alias (uses defaultModel if omitted)
wavespeed run <model|alias> --sync       Attempt sync wait; timed-out tasks remain queryable
wavespeed run <model|alias> -h           Dynamic schema-based help (alias-aware)
wavespeed generate image|video "…"       /chat models; picks the endpoint from your inputs (--image/--first-frame/--ref-*)
wavespeed edit image|video "…"           Edit images (--image) or a video (--video)
wavespeed extend video "…" --video …     Continue a video
                                         Shortcuts adapt the request to the model (printed); add --estimate to price without running
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 (24h dedup cache)
wavespeed download <url...>              Save URLs to disk

# account & history
wavespeed balance                        Show your current credit balance
wavespeed usage [--since --until]        Spend + request counts, per-model (last 7d)
wavespeed billings [--type --since …]    Itemized charges and refunds
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

Pricing is an estimate. wavespeed price quotes the inputs you pass, and many models bill from an input — audio/video duration, frame count, text length. Pass the same inputs you would pass to wavespeed run: a quote made without them can be lower than the real charge. The amount actually charged for a run is authoritative.

Auth

	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.

Development

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 link

Stack: TypeScript, Commander, Inquirer, Chalk, Ora, the official wavespeed SDK.

License

MIT — see LICENSE.

---

WaveSpeed AI — AI image & video generation platform. Try it in the browser: Image generator · Video generator