@wavespeed/cli

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

# 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": "bytedance/seedance-2.5/text-to-video",
                "input": { "resolution": "720p", "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

Use case	Model
Text → image	bytedance/seedream-v5.0-pro
Image edit	bytedance/seedream-v5.0-pro/edit
Text → video	bytedance/seedance-2.5/text-to-video
Image → video	bytedance/seedance-2.5/image-to-video
Video edit	bytedance/seedance-2.5/video-edit
Video extend	bytedance/seedance-2.5/video-extend

Browse alternatives with wavespeed models <query>.

Use from coding agents

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.md

The 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.

OpenCode loads the same file with no extra steps — .claude/skills/ is on its skill search path.

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

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

# 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 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 from the model's pricing formula, and many models bill from an input — audio/video duration, frame count, text length. Those inputs are optional in the quote: ask for a price without them and the formula collapses to the model's base price, which is the floor of its range, not a typical run. wavespeed price wavespeed-ai/infinitetalk says $0.15; a 60s audio actually bills $1.80. The command names the inputs it was blind to (unpriced_inputs / at_base_price in --json) — supply them for a real quote. Whatever it says, 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.