WaveSpeed CLI

Use WaveSpeed CLI to run WaveSpeedAI models from your terminal. The CLI gives image, video, audio, 3D, and other model workflows the same basic entry point:

# Run a WaveSpeedAI model and return machine-readable JSON.
wavespeed run <model_id> --json

It is useful when you want to generate assets manually, automate model calls from scripts or CI jobs, or let coding agents such as Codex, Claude Code, Cursor, and similar tools call WaveSpeedAI from the terminal.

Visit the WaveSpeed CLI page for the product overview and installation entry point.

Install

WaveSpeed CLI requires Node.js 18 or later.

# Install the CLI globally with npm.
npm install -g @wavespeed/cli
 
# Confirm the installed CLI version.
wavespeed --version

Use interactive login when you are working locally:

# Start the browser-based login flow.
wavespeed login
 
# Confirm the active account, API base URL, and local key location.
wavespeed status

Use non-interactive login for remote machines or automation:

# Store an API key on this machine without opening a browser.
wavespeed login --api-key <API_KEY> --no-browser
 
# Confirm the CLI is signed in before running jobs.
wavespeed status

To remove the stored API key from the machine:

# Clear the locally stored API key.
wavespeed logout

Keep API keys out of git, README files, frontend code, and shared logs. The CLI stores the key in local user configuration after login.

Recommended Workflow

Most CLI tasks follow this order:

models -> schema -> price -> run -> download or history

For example:

# Search for a model related to z-image.
wavespeed models z-image
 
# Inspect the inputs accepted by the selected model.
wavespeed schema wavespeed-ai/z-image/turbo
 
# Estimate the price before generating output.
wavespeed price wavespeed-ai/z-image/turbo -p "a product photo"
 
# Run the model and print a JSON response.
wavespeed run wavespeed-ai/z-image/turbo -p "a product photo" --json
 
# Run the model and download generated outputs locally.
wavespeed run wavespeed-ai/z-image/turbo -p "a product photo" --json --download

Search Models

Use models to browse the WaveSpeedAI model catalog. Start broad, then narrow by keyword, popularity, or model type.

# List models from the catalog.
wavespeed models
 
# Search models that match a keyword or model family.
wavespeed models z-image
 
# Search for video-related models.
wavespeed models video
 
# Search for LoRA-related models.
wavespeed models lora
 
# Show popular models across the catalog.
wavespeed models --popular
 
# Show popular models that match a keyword.
wavespeed models z-image --popular
 
# Filter to text-to-image models.
wavespeed models --type text-to-image
 
# Filter to image-to-video models.
wavespeed models --type image-to-video
 
# Filter to text-to-video models.
wavespeed models --type text-to-video
 
# Filter to image-to-image models.
wavespeed models --type image-to-image
 
# Use category as an alias for type.
wavespeed models --category text-to-image
 
# Refresh the local model cache from the live catalog.
wavespeed models --refresh
 
# Skip the local cache for this command.
wavespeed models --no-cache
 
# Return matching models as JSON for scripts and agents.
wavespeed models z-image --json

Use --json when another program needs to parse the model list. Use --refresh or --no-cache when you want to confirm the latest catalog data.

Inspect Model Inputs

Use schema before running an unfamiliar model:

# Show the required and optional inputs for a model.
wavespeed schema <model_id>
 
# Return the model schema as JSON.
wavespeed schema <model_id> --json
 
# Fetch a fresh schema instead of using the local cache.
wavespeed schema <model_id> --refresh

You can also inspect runnable flags for a model:

# Show model-specific run help and accepted flags.
wavespeed run <model_id> -h

For example:

# Inspect the z-image turbo input schema.
wavespeed schema wavespeed-ai/z-image/turbo

The schema shows required and optional inputs such as prompt, size, seed, output_format, image URLs, video settings, or other model-specific fields.

Run a Model

The simplest run uses a model ID and a prompt:

# Run a text-to-image prompt and return JSON.
wavespeed run wavespeed-ai/z-image/turbo -p "a cyberpunk skyline" --json

Pass model-specific inputs with -i:

# Run z-image turbo with explicit size, format, JSON output, and local download.
wavespeed run wavespeed-ai/z-image/turbo \
  -p "a clean product photo of a glass teapot" \
  -i size=1024*1024 \
  -i output_format=png \
  --json \
  --download

The multi-line examples use Bash line continuations (\). On Windows PowerShell, run the command on one line or replace each \ with a PowerShell backtick. In PowerShell, the backtick must be the last character on the line.

Common run options:

Option	Use
`-p, --prompt <text>`	Shortcut for `prompt=<text>`
`-i, --input key=value`	Pass one model input; repeat it for multiple inputs
`--input-file <path>`	Pass a full JSON input object from a file
`--json`	Emit one JSON object on stdout for scripts and agents
`--download`	Download generated outputs to the default output directory
`--download "./out/{index}.{ext}"`	Download with a path template
`--output-dir <dir>`	Set the download directory for this run
`--sync`	Use synchronous mode when the model supports it

For scripts and AI agents, prefer --json so the caller can parse the result reliably. Add --download when local files are needed.

Upload Files

Image-to-image, image editing, image-to-video, and similar models often require a hosted file URL. Upload local files first:

# Upload one local file and print the CDN URL.
wavespeed upload ./input.png
 
# Upload one local file and return JSON.
wavespeed upload ./input.png --json

Upload multiple files:

# Upload multiple files in one command and return JSON.
wavespeed upload ./a.png ./b.png --json

Then pass the returned CDN URL to a model input:

# Use an uploaded image URL as model input.
wavespeed run <model_id> -i image="<url>" -p "animate this image" --json

Download Results

Use download when you already have output URLs:

# Download one remote output URL to the default output directory.
wavespeed download <url>
 
# Download one remote output URL and return JSON.
wavespeed download <url> --json
 
# Download one remote output URL to a specific file path.
wavespeed download <url> -o ./output.png
 
# Download multiple output URLs into one directory.
wavespeed download <url1> <url2> --output-dir ./outputs

Price and Balance

Check your account balance:

# Show the current account balance.
wavespeed balance
 
# Return balance details as JSON.
wavespeed balance --json
 
# Show balance and open the top-up flow when needed.
wavespeed balance --top-up

Estimate the cost of a run before generating:

# Estimate cost with prompt shorthand.
wavespeed price wavespeed-ai/z-image/turbo -p "a product photo"
 
# Estimate cost with explicit input syntax and JSON output.
wavespeed price wavespeed-ai/z-image/turbo -i prompt="a product photo" --json

price calculates the estimated cost for the given inputs. It does not generate output and does not charge for a prediction.

Open or print the top-up page:

# Open the top-up page in a browser.
wavespeed top-up
 
# Print the top-up URL instead of opening a browser.
wavespeed top-up --print

History

List recent predictions:

# List recent predictions.
wavespeed history
 
# List the first 10 recent predictions.
wavespeed history --limit 10
 
# List page 2 with 20 predictions per page.
wavespeed history --page 2 --limit 20
 
# Show history for one model.
wavespeed history --model wavespeed-ai/z-image/turbo
 
# Show only completed predictions.
wavespeed history --status completed
 
# Return history as JSON.
wavespeed history --json

Show one prediction:

# Show full details for one prediction.
wavespeed show <prediction_id>
 
# Return prediction details as JSON.
wavespeed show <prediction_id> --json
 
# Show the prediction and download its outputs.
wavespeed show <prediction_id> --download

Delete predictions:

# Delete one prediction from history.
wavespeed delete <prediction_id>
 
# Delete multiple predictions without an interactive confirmation.
wavespeed delete <id1> <id2> -y
 
# Delete one prediction and return JSON.
wavespeed delete <prediction_id> --json

Project Configuration

Initialize a project configuration file:

# Create wavespeed.json with sensible defaults.
wavespeed init -y

This creates wavespeed.json:

{
  "$schema": "https://wavespeed.ai/schema/cli.json",
  "defaultModel": "google/nano-banana-2/text-to-image",
  "outputDir": "wavespeed-output",
  "aliases": {}
}

With defaultModel, you can omit the model ID:

# Run the configured default model.
wavespeed run -p "a product photo" --json --download

Use aliases to share repeatable model settings with a team:

{
  "defaultModel": "google/nano-banana-2/text-to-image",
  "outputDir": "wavespeed-output",
  "aliases": {
    "hero": {
      "model": "wavespeed-ai/z-image/turbo",
      "input": {
        "size": "1024*1024",
        "output_format": "png"
      }
    }
  }
}

Then run the alias:

# Run the hero alias with a custom prompt.
wavespeed run hero -p "a landing page hero image" --json --download

View available aliases:

# List aliases from project and user configuration.
wavespeed aliases
 
# Return aliases as JSON.
wavespeed aliases --json

Global Configuration

Use config for machine-level defaults:

# View current CLI configuration.
wavespeed config
 
# Set a custom WaveSpeedAI API base URL.
wavespeed config --base-url https://api.wavespeed.ai
 
# Set the default model used when run omits a model ID.
wavespeed config --default-model wavespeed-ai/z-image/turbo
 
# Set the default local output directory.
wavespeed config --output-dir wavespeed-output
 
# Reset CLI configuration to defaults.
wavespeed config --reset

Use wavespeed.json for project settings that can be shared with a repository. Keep login credentials and personal defaults in local user configuration.

Use with Coding Agents

WaveSpeed CLI is agent-ready. Codex, Claude Code, Cursor, and other coding agents can discover models, inspect schemas, estimate prices, run generations, and parse JSON output directly from the terminal.

Install the agent skill:

# Install the WaveSpeed skill file for compatible coding agents.
wavespeed skill install

This creates:

.claude/skills/wavespeed/SKILL.md

After the skill is installed, you can ask a coding agent for tasks such as:

Find a text-to-image model, generate a product photo, and download it locally.

The agent should follow the same CLI flow:

# Find popular text-to-image models.
wavespeed models --type text-to-image --popular
 
# Inspect the selected model inputs.
wavespeed schema <model_id>
 
# Estimate the cost for the intended prompt.
wavespeed price <model_id> -p "..."
 
# Run the model, return JSON, and download outputs.
wavespeed run <model_id> -p "..." --json --download

This keeps the integration simple: agents call the same CLI commands a developer would run, and JSON output gives them a stable result to read.

Script Automation

When calling the CLI from scripts, use wavespeed on macOS and Linux. On Windows, npm global binaries are usually exposed through .cmd shims, so call wavespeed.cmd directly or invoke it through cmd.exe.

Node.js

import { execFile } from "node:child_process";
import { promisify } from "node:util";
 
const execFileAsync = promisify(execFile);
const isWindows = process.platform === "win32";
 
const command = isWindows
  ? (process.env.ComSpec || "C:\\Windows\\System32\\cmd.exe")
  : "wavespeed";
 
const args = isWindows
  ? [
      "/d",
      "/s",
      "/c",
      "wavespeed.cmd",
      "run",
      "wavespeed-ai/z-image/turbo",
      "-p",
      "a clean product photo",
      "--json",
      "--download",
    ]
  : [
      "run",
      "wavespeed-ai/z-image/turbo",
      "-p",
      "a clean product photo",
      "--json",
      "--download",
    ];
 
// Run the CLI with JSON output so Node.js can parse the result.
const { stdout } = await execFileAsync(command, args);
const result = JSON.parse(stdout);
 
console.log(result.outputs);
console.log(result.saved);

Python

import json
import os
import subprocess
 
command = "wavespeed.cmd" if os.name == "nt" else "wavespeed"
 
# Run the CLI with JSON output so Python can parse the result.
result = subprocess.run(
    [
        command,
        "run",
        "wavespeed-ai/z-image/turbo",
        "-p",
        "a clean product photo",
        "--json",
        "--download",
    ],
    capture_output=True,
    text=True,
    check=True,
)
 
data = json.loads(result.stdout)
print(data["outputs"])
print(data["saved"])

Desktop App Python SDK