WaveSpeed CLI · MCP

Every WaveSpeed model — from your terminal and agent

One open-source CLI to run any WaveSpeed AI model. Image, video, audio, 3D. Built for terminals and coding agents like Codex, Claude Code, Claude Cowork, and Cursor.

$npm install -g @wavespeed/cli

Install from npm MCP setup View on GitHub

Three commands and you're shipping

Install

Node 18+ required. One global install gives you the wavespeed binary everywhere.

$npm install -g @wavespeed/cli

Sign in

Opens the access-key page in your browser. We auto-detect a copied key and validate it live.

$wavespeed login

Run any model

Same shape for all models. Pass the model ID and inputs — get a CDN URL back, or pipe --json to your scripts.

$wavespeed run wavespeed-ai/z-image/turbo -p "a cat"

Built for humans and agents

Dynamic per-model help

Run wavespeed run <model> -h and the CLI fetches that model's input schema live and prints the exact flags it accepts — no guessing.

Aliases that ship with your repo

Define named shortcuts in wavespeed.json that bundle a model + default inputs. Teams pull the file, type wavespeed run hero, get on-brand output.

Agent-native by design

Every command supports --json on stdout and progress on stderr. Drop a SKILL.md so Codex, Claude Code, Claude Cowork, and Cursor know how to call it.

No magic, no daemon

The CLI never mutates your prompt and never opens a background process. It calls api.wavespeed.ai directly. Open source, MIT licensed.

What a real session looks like

From catalog browse to JSON output — three commands.

~/projects/marketing

# 1. browse the catalog
$ wavespeed models --type text-to-image --popular

# 2. inspect a model's inputs — schema fetched live
$ wavespeed run wavespeed-ai/z-image/turbo -h
  * prompt          string
    size            string   default: "1024*1024"
    strength        number   default: 0.6   range: 0..1
    output_format   string   default: "jpeg"   enum: jpeg | png | webp

# 3. run — JSON out so you can pipe it
$ wavespeed run wavespeed-ai/z-image/turbo \
    -p "a cyberpunk skyline at golden hour" --json
{
  "model": "wavespeed-ai/z-image/turbo",
  "outputs": ["https://example.com/output/skyline.jpeg"],
  "elapsed_ms": 4718
}

Plug into your coding agent in one step

No extra config. Coding agents like Codex, Claude Code, and Claude Cowork already know how to run shell commands — the SKILL.md tells them how to use the CLI.

$wavespeed skill install

Works with Codex, Claude Code, Claude Cowork, Cursor, and any agent that auto-loads .claude/skills/*.

Prefer MCP? Connect any MCP client

The WaveSpeed MCP server gives Claude Desktop, Claude Code, Cursor, Cline and any other MCP client the same live catalog: search models, read a model's real inputs, quote the price, then run it.

Signed in with wavespeed login? The MCP server uses the same login. Otherwise set WAVESPEED_API_KEY.

Claude Code

$claude mcp add wavespeed -- npx -y @wavespeed/mcp

Cursor

Install it in Cursor with one click.

Add to Cursor

Claude Desktop and other clients

Add this to the mcpServers section of your client's config.

{
  "mcpServers": {
    "wavespeed": {
      "command": "npx",
      "args": ["-y", "@wavespeed/mcp"],
      "env": { "WAVESPEED_API_KEY": "wsk_..." }
    }
  }
}

Seven tools

list_models

Search the live catalog by text or type

get_model_schema

A model's real inputs, required fields and defaults

run_model

Run any model; local @file inputs upload automatically

get_price

Quote the cost before you spend

get_balance

Check your credit balance

upload_file

Turn a local file into a hosted URL

get_prediction

Pick up a long-running generation by its id

GitHub npm

Open source. Ready today.

MIT licensed, scoped under @wavespeed on npm, hosted on GitHub. Issues and PRs welcome.

Install from npm Star on GitHub