@wavespeed/cli 0.4.24 → 0.4.25

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +22 -11
  2. package/package.json +1 -1
  3. package/skills/SKILL.md +64 -53
package/README.md CHANGED
@@ -42,6 +42,11 @@ npm install -g @wavespeed/cli
42
42
  # friendlier error path)
43
43
  curl -fsSL https://raw.githubusercontent.com/WaveSpeedAI/wavespeed-cli/main/install.sh | bash
44
44
 
45
+ # macOS / Linux with Homebrew (standalone executable, no Node.js needed)
46
+ brew tap wavespeedai/tap
47
+ brew trust wavespeedai/tap # recent Homebrew refuses formulae from an untrusted tap
48
+ brew install wavespeed
49
+
45
50
  # no Node.js/npm? install.sh falls back to a standalone executable on macOS/Linux;
46
51
  # on Windows (PowerShell):
47
52
  irm https://raw.githubusercontent.com/WaveSpeedAI/wavespeed-cli/main/install.ps1 | iex
@@ -103,26 +108,32 @@ Resolution: positional with `/` is a model ID; otherwise looked up as an alias.
103
108
 
104
109
  ## Recommended starting models
105
110
 
106
- | Use case | Model |
107
- |---|---|
108
- | Text → image | `bytedance/seedream-v5.0-pro` |
109
- | Image edit | `bytedance/seedream-v5.0-pro/edit` |
110
- | Text → video | `wavespeed-ai/minimax-h3/text-to-video` |
111
- | Image → video | `wavespeed-ai/minimax-h3/image-to-video` |
112
- | Video edit | `wavespeed-ai/minimax-h3/video-edit` |
113
- | Video extend | `wavespeed-ai/minimax-h3/video-extend` |
111
+ For plain images and videos, the shortcuts pick the endpoint for you and use the same models as the [WaveSpeed /chat](https://wavespeed.ai/chat) page:
112
+
113
+ ```bash
114
+ wavespeed generate image "a cyberpunk skyline at golden hour" --json
115
+ wavespeed edit image "replace the background with a sunlit kitchen" --image @./photo.jpg --json
116
+ wavespeed generate video "slow push-in on a lighthouse at dusk" --estimate --json # price first, nothing submitted
117
+ wavespeed edit video "make it snow" --video @./clip.mp4 --json
118
+ wavespeed extend video "the camera keeps rising" --video @./clip.mp4 --json
119
+ ```
120
+
121
+ | | Default | Alternatives (`-m`) |
122
+ |---|---|---|
123
+ | Image | `seedream-5-pro` | `gpt-image-2.5`, `nano-banana-2.1`, `nano-banana-pro`, `nano-banana-2`, `gpt-image-2` |
124
+ | 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 |
114
125
 
115
- MiniMax H3 is the open-weights default: cheap, fast, and native stereo audio — the best place to start. When you need the highest quality, switch to `bytedance/seedance-2.5/*` (text-to-video, image-to-video, video-edit, video-extend). Browse alternatives with `wavespeed models <query>`.
126
+ For everything else (audio, 3D, upscaling, a specific endpoint), find the model with `wavespeed models <query>` and call it with `wavespeed run <model-id>`.
116
127
 
117
128
  ## Use from coding agents
118
129
 
119
- No MCP server, no daemon. The CLI **is** the interface — agents already know how to run shell commands.
130
+ 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](https://github.com/WaveSpeedAI/mcp-server) offers the same actions as tools, and the skill covers both.
120
131
 
121
132
  ```bash
122
133
  wavespeed skill install # writes .claude/skills/wavespeed/SKILL.md and .agents/skills/wavespeed/SKILL.md
123
134
  ```
124
135
 
125
- 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.
136
+ 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.
126
137
 
127
138
  **OpenCode** loads the same file with no extra steps — `.claude/skills/` is on its skill search path.
128
139
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wavespeed/cli",
3
- "version": "0.4.24",
3
+ "version": "0.4.25",
4
4
  "description": "WaveSpeed CLI — one command to run any WaveSpeed AI model from your terminal.",
5
5
  "publishConfig": {
6
6
  "access": "public"
package/skills/SKILL.md CHANGED
@@ -1,86 +1,97 @@
1
1
  ---
2
2
  name: wavespeed
3
- description: Generate or edit AI media (image, video, audio, 3D) by calling the wavespeed CLI on the user's machine. Use whenever the user asks to create, edit, animate, upscale, or transform a visual asset, generate audio/TTS/music, or produce marketing creatives. Every model on the WaveSpeed platform is one `wavespeed run <id>` call.
3
+ description: Generate or edit AI media (image, video, audio, 3D) on WaveSpeed, through the WaveSpeed MCP tools when they are connected or the wavespeed CLI on the user's machine. Use whenever the user asks to create, edit, animate, extend, upscale, or transform an image or video, generate audio/TTS/music or 3D, or produce marketing creatives.
4
4
  ---
5
5
 
6
6
  # WaveSpeed
7
7
 
8
- You have access to the `wavespeed` CLI. Every generation flows through one generic verb, `wavespeed run`, and the model id is always explicit. For plain image and video work there are also shortcut commands (see the end).
8
+ WaveSpeed runs every model on its platform. There are two ways in, and they do the same things:
9
9
 
10
- ## The three-step pattern
10
+ - **MCP tools** (`generate_image`, `generate_video`, …): use them when the WaveSpeed MCP server is connected. The hosted server cannot read local files: pass public URLs, or use the CLI for files on disk.
11
+ - **The `wavespeed` CLI**: use it when it is installed, for local files (`@./path`), batches and scripts.
11
12
 
12
- ```bash
13
- # 1. FIND a model — search the live catalog
14
- wavespeed models "seedream"
15
- wavespeed models --type image-to-video --popular
13
+ For plain image and video work, use the shortcuts. For anything else (audio, 3D, upscaling, a specific endpoint, exact parameters), use the generic run.
16
14
 
17
- # 2. INSPECT its inputs — dynamic schema, per model
18
- wavespeed run bytedance/seedream-v5.0-pro -h
15
+ ## Images and videos: the shortcuts
19
16
 
20
- # 3. RUN it — always pass --json so you can read the result
21
- wavespeed run bytedance/seedream-v5.0-pro \
22
- -p "a cyberpunk skyline at golden hour" \
23
- -i aspect_ratio="16:9" -i resolution="2k" --json
24
- ```
17
+ | Task | CLI | MCP tool |
18
+ |---|---|---|
19
+ | Image from a prompt (optionally with reference pictures) | `wavespeed generate image "<prompt>" [--image @./ref.jpg]` | `generate_image` |
20
+ | Edit, restyle, combine images | `wavespeed edit image "<prompt>" --image @./photo.jpg` | `edit_image` |
21
+ | Video from a prompt, a first/last frame, or references | `wavespeed generate video "<prompt>" [--first-frame …] [--ref-image …]` | `generate_video` |
22
+ | Edit a video | `wavespeed edit video "<prompt>" --video @./clip.mp4` | `edit_video` |
23
+ | Continue a video | `wavespeed extend video "<prompt>" --video @./clip.mp4` | `extend_video` |
24
+
25
+ They use the same models as the WaveSpeed /chat page and pick the endpoint (text, image, reference, edit) from the inputs you give. In the prompt, refer to media as `@image 1`, `@video 1`, `@audio 1`, in the order given ("put the product in @image 1 into the kitchen in @image 2").
26
+
27
+ - **Price first for videos:** CLI `--estimate --json`, MCP `estimate_only: true`. It returns the endpoint, the exact request and the price, and submits nothing.
28
+ - **Models:** pass `-m` / `model` only when the user names one; a named model is never switched. Without it the default is used, or another model only when the default cannot take the inputs.
29
+ - **Options:** `--aspect-ratio`, `--resolution`, `--duration` (CLI) or the same fields (MCP). Set them only when the user asks; values are snapped to what the model supports, and every change is reported.
30
+ - CLI: add `--json` to read the result, `--download` to save files.
25
31
 
26
- `run --json` returns `{ id, model, prompt, outputs: [url, ...], saved: [path, ...], elapsed_ms, raw }`. Keep `id` — it is the handle for `wavespeed show <id>` if anything is interrupted. Use the URL when the user wants a link. Add `--download` if they need bytes on disk.
32
+ ### Default models
27
33
 
28
- ## Recommended defaults
34
+ | | Default | Alternatives (`-m` / `model`) |
35
+ |---|---|---|
36
+ | Image | `seedream-5-pro` (Seedream 5 Pro) | `gpt-image-2.5` (GPT Image 2.5, the model behind ChatGPT Images; strong at text and photorealism), `nano-banana-2.1`, `nano-banana-pro`, `nano-banana-2`, `gpt-image-2` |
37
+ | Video | `seedance-2.5` (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; defaults to 768p, its counterpart of 720p), older Seedance 2.0 tiers |
29
38
 
30
- | Use case | Model |
31
- |---|---|
32
- | Text → image | `bytedance/seedream-v5.0-pro` |
33
- | Image edit (instruction-driven) | `bytedance/seedream-v5.0-pro/edit` — requires `images: [url, ...]` |
34
- | Text → video | `wavespeed-ai/minimax-h3/text-to-video` |
35
- | Image → video | `wavespeed-ai/minimax-h3/image-to-video` — requires `image: url` |
36
- | Video edit (instruction-driven) | `wavespeed-ai/minimax-h3/video-edit` — requires `video: url` |
37
- | Video extend | `wavespeed-ai/minimax-h3/video-extend` — requires `video: url` |
39
+ Video resolution is 720p unless the user asks for another (MiniMax H3: 768p). Offer 480p for a cheaper draft.
38
40
 
39
- These are good starting points. MiniMax H3 is the open-weights default: cheap, fast, and native stereo audio — the best place to start. When you need the highest quality, switch to `bytedance/seedance-2.5/*` (text-to-video, image-to-video, video-edit, video-extend). Browse alternatives with `wavespeed models <query>`.
41
+ ## Everything else: the generic run
40
42
 
41
- ## Common recipes
43
+ Every model on the platform is one `wavespeed run <model-id>` (MCP: `run_model`). The model id is always explicit.
42
44
 
43
45
  ```bash
44
- # Edit an existing image — @path uploads the file and passes its URL (one step)
45
- wavespeed run bytedance/seedream-v5.0-pro/edit \
46
- -p "replace the background with a sunlit kitchen" \
47
- -i images='["@./input.jpg"]' --json
46
+ # 1. FIND a model in the live catalog (MCP: list_models)
47
+ wavespeed models "upscale"
48
+ wavespeed models --type text-to-audio --popular
48
49
 
49
- # Image-to-video — same @ marker for single-URL fields
50
- wavespeed run wavespeed-ai/minimax-h3/image-to-video \
51
- -p "subtle parallax, gentle wind" \
52
- -i image=@./hero.jpg -i duration=5 --json
50
+ # 2. INSPECT its inputs (MCP: get_model_schema)
51
+ wavespeed run <model-id> -h
53
52
 
54
- # Or upload separately when you need the URL itself
55
- URL=$(wavespeed upload ./hero.jpg --json | jq -r .url)
53
+ # 3. RUN it, with --json so you can read the result (MCP: run_model)
54
+ wavespeed run <model-id> -p "..." -i key=value --json
55
+ ```
56
+
57
+ `run --json` returns `{ id, model, prompt, outputs: [url, ...], saved: [path, ...], elapsed_ms, raw }`. Keep `id`: it is the handle for `wavespeed show <id>` (MCP: `get_prediction`) if anything is interrupted. Use the URL when the user wants a link; add `--download` when they need the file on disk.
58
+
59
+ ```bash
60
+ # Local files: @path uploads the file and passes its URL
61
+ wavespeed run <model-id> -i image=@./photo.jpg --json
62
+ wavespeed run <model-id> -i images='["@./a.jpg","@./b.jpg"]' --json
56
63
 
57
- # Save outputs locally with a template
58
- wavespeed run ... -p "..." --download "./out/{index}.{ext}"
64
+ # Or upload separately when you need the URL itself (MCP: upload_file / create_upload)
65
+ URL=$(wavespeed upload ./photo.jpg --json | jq -r .url)
66
+
67
+ # Save outputs with a template
68
+ wavespeed run <model-id> -p "..." --download "./out/{index}.{ext}"
59
69
  ```
60
70
 
71
+ The generic run never changes the user's prompt or inputs. The single exception is explicit: an `@path` value uploads that file and substitutes its hosted URL. Bare paths are never uploaded.
72
+
61
73
  ## Project config and aliases
62
74
 
63
75
  If `wavespeed.json` exists (created by `wavespeed init`):
64
76
 
65
- - **`defaultModel`** — lets `wavespeed run -p "…"` (no model arg) work.
66
- - **Aliases** — named shortcuts that bundle model + default inputs. Run `wavespeed aliases` to see what's defined. `wavespeed run <alias> -h` shows the resolved schema. CLI `-i k=v` overrides alias defaults.
67
-
68
- The CLI never modifies the user's prompt or inputs. The single exception is explicit: an `@path` value uploads that file and substitutes its hosted URL. Bare paths are never uploaded.
77
+ - **`defaultModel`** lets `wavespeed run -p "…"` (no model arg) work.
78
+ - **Aliases** are named shortcuts that bundle model + default inputs. Run `wavespeed aliases` to see them; `wavespeed run <alias> -h` shows the resolved schema. CLI `-i k=v` overrides alias defaults.
69
79
 
70
80
  ## Auth
71
81
 
72
- `wavespeed status` shows whether the user is signed in. If not, ask them to run `wavespeed login` (opens https://wavespeed.ai/accesskey). **Never** ask the user to paste an API key into the chat — the CLI handles it.
82
+ - CLI: `wavespeed status` shows whether the user is signed in. If not, ask them to run `wavespeed login` (opens https://wavespeed.ai/accesskey).
83
+ - MCP: if the tools ask for authorization, the user approves the connection once (in Claude Code: `/mcp`, pick `wavespeed`).
84
+ - **Never** ask the user to paste an API key into the chat.
73
85
 
74
- ## Pitfalls
86
+ ## Cost and credits
75
87
 
76
- - Local files: use `@./file.jpg` in `-i` values. Bare paths are NOT uploaded and the model will reject them.
77
- - Don't invent model IDs. Always confirm via `wavespeed models` or `wavespeed schema <id>` before running.
78
- - Use `--json` on every `run` so you can read `outputs[0]` programmatically.
79
- - `wavespeed delete` requires `--yes` when run non-interactively (that includes you).
80
- - Cost and spend: `wavespeed price <id> -i k=v --json` estimates a run without generating or charging; `wavespeed balance` shows remaining credit; `wavespeed usage` (totals, per-model) and `wavespeed billings` (per-charge records) show what was spent.
81
- - If a run fails with `Insufficient credits` (or says a top-up is required), the balance is too low: do not retry. Tell the user, and give them https://wavespeed.ai/top-up to add credits (`wavespeed balance` shows the balance and the link). You cannot pay for them.
82
- - A `run` that fails with a gateway or network error (502/503/504, connection reset, timeout) does NOT mean the task failed, and the submit request is never retried automatically, so re-running can create a duplicate paid task. Do not re-run immediately. If the error contains a task id (`task_id` / prediction id), keep checking it with `wavespeed show <id> --json` until its status is terminal (`completed`, `failed`, `cancelled`, `timeout`, `deleted`). If no id was returned, check recent predictions with `wavespeed history --json` (add `--model <id>`; default window is the last 24h) and re-run once only if none matches. A client-side wait timeout or an interrupted `run` does not mean the task failed: tasks can run for a long time, so do not give up after a fixed time.
88
+ - `wavespeed price <id> -i k=v --json` (MCP: `get_price`) estimates a run without generating or charging. The shortcuts have `--estimate` / `estimate_only`.
89
+ - `wavespeed balance` (MCP: `get_balance`) shows the remaining credit; `wavespeed usage` and `wavespeed billings` show what was spent.
90
+ - If a run fails with `Insufficient credits` (or says a top-up is required), the balance is too low: do not retry. Tell the user and give them https://wavespeed.ai/top-up. You cannot pay for them.
83
91
 
84
- ## Shortcuts for common image/video work
92
+ ## Pitfalls
85
93
 
86
- `wavespeed generate image|video`, `wavespeed edit image|video`, `wavespeed extend video` use the WaveSpeed /chat models and choose the endpoint from the inputs (`--image`, `--first-frame`, `--ref-image/--ref-video/--ref-audio`, `--video`; `@./path` uploads). Pass `-m` only when the user names a model. Run with `--estimate --json` first for videos; the request may be adapted to the model and the changes are printed. Use `wavespeed run <model>` for exact control.
94
+ - Don't invent model IDs. Confirm with `wavespeed models` or `wavespeed schema <id>` (MCP: `list_models`, `get_model_schema`) before a generic run.
95
+ - Local files: use `@./file.jpg`. Bare paths are NOT uploaded and the model will reject them. The hosted MCP server cannot read local files at all.
96
+ - `wavespeed delete` requires `--yes` when run non-interactively (that includes you).
97
+ - A run that fails with a gateway or network error (502/503/504, connection reset, timeout) does NOT mean the task failed, and the submit request is never retried automatically, so re-running can create a duplicate paid task. Do not re-run immediately. If the error contains a task id (`task_id` / prediction id), keep checking it with `wavespeed show <id> --json` (MCP: `get_prediction`) until its status is terminal (`completed`, `failed`, `cancelled`, `timeout`, `deleted`). If no id was returned, check recent predictions with `wavespeed history --json` (MCP: `list_predictions`; add the model; default window is the last 24h) and re-run once only if none matches. A client-side wait timeout or an interrupted run does not mean the task failed: tasks can run for a long time, so do not give up after a fixed time.