WaveSpeed CLI

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

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

# Download the installer, then run it. It downloads the executable for your platform,
# verifies its checksum, and installs it to ~/.local/bin.
curl --fail-with-body -sSL -o install.sh https://raw.githubusercontent.com/WaveSpeedAI/wavespeed-cli/main/install.sh
bash install.sh

# Upgrade to the latest version.
wavespeed upgrade
 
# Only check whether a newer version exists.
wavespeed upgrade --check

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

# 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

# Clear the locally stored API key.
wavespeed logout

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

# 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" -i size=1024*1024
 
# Run the model and print a JSON response.
wavespeed run wavespeed-ai/z-image/turbo -p "a product photo" -i size=1024*1024 --json
 
# Run the model and download generated outputs locally.
wavespeed run wavespeed-ai/z-image/turbo -p "a product photo" -i size=1024*1024 --json --download

# 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

# 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

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

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

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

# Run z-image turbo with explicit size, 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 \
  --json \
  --download

# 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 in one command and return JSON.
wavespeed upload ./a.png ./b.png --json

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

# 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

# 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 cost with prompt shorthand.
wavespeed price wavespeed-ai/z-image/turbo -p "a product photo" -i size=1024*1024
 
# Estimate cost with explicit input syntax and JSON output.
wavespeed price wavespeed-ai/z-image/turbo -i prompt="a product photo" -i size=1024*1024 --json

# 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

# 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
 
# Show predictions created in a time range (ISO 8601 or YYYY-MM-DD).
wavespeed history --since 2026-10-01 --until 2026-10-08
 
# Return history as JSON.
wavespeed history --json

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

# List recent charges and refunds.
wavespeed billings
 
# Only refunds, or only charges.
wavespeed billings --type refund
wavespeed billings --type deduct
 
# Charges for one model or one API key (use the uuid), in a time range.
wavespeed billings --model <model_uuid> --key <api_key_uuid> --since 2026-10-01 --until 2026-10-08
 
# Page through the records, or return them as JSON.
wavespeed billings --page 2 --limit 50
wavespeed billings --json
 
# Spend, request counts and a per-model breakdown (the last 7 days by default).
wavespeed usage
wavespeed usage --since 2026-10-01 --until 2026-10-08 --model <model_uuid> --json

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

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

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

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

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

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

# 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

# List supported agents and which ones are on this machine.
wavespeed setup
 
# Preview the change without writing anything.
wavespeed setup opencode --dry-run
 
# Configure an agent, then verify it with a live streamed request.
wavespeed setup opencode
 
# Use a different model.
wavespeed setup opencode --model <model_id>
 
# Restore the agent's previous settings.
wavespeed setup opencode --undo

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

.claude/skills/wavespeed/SKILL.md

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

# 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

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",
      "-i",
      "size=1024*1024",
      "--json",
      "--download",
    ]
  : [
      "run",
      "wavespeed-ai/z-image/turbo",
      "-p",
      "a clean product photo",
      "-i",
      "size=1024*1024",
      "--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);

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",
        "-i",
        "size=1024*1024",
        "--json",
        "--download",
    ],
    capture_output=True,
    text=True,
    check=True,
)
 
data = json.loads(result.stdout)
print(data["outputs"])
print(data["saved"])