--- name: pp-wavespeed description: "Run any WaveSpeed model from the terminal, with price checks, safe uploads, and recovery-safe downloads. Trigger phrases: `generate an image with wavespeed`, `run a wavespeed model`, `make a video with seedance`, `check my wavespeed balance`, `how much will this wavespeed run cost`." author: "Cathryn Lavery" license: "Apache-2.0" argument-hint: " [args] | install cli|mcp" allowed-tools: "Read Bash" metadata: openclaw: requires: bins: - wavespeed-pp-cli install: - kind: go bins: [wavespeed-pp-cli] module: github.com/mvanhorn/printing-press-library/library/ai/wavespeed/cmd/wavespeed-pp-cli --- # WaveSpeed — Printing Press CLI ## Prerequisites: Install the CLI This skill drives the `wavespeed-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first: 1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows: ```bash npx -y @mvanhorn/printing-press-library install wavespeed --cli-only ``` 2. Verify: `wavespeed-pp-cli --version` 3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill. If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.6 or newer). This installs into `$GOPATH/bin` (default `$HOME/go/bin`), so add that directory to `$PATH` instead: ```bash go install github.com/mvanhorn/printing-press-library/library/ai/wavespeed/cmd/wavespeed-pp-cli@latest ``` If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds. WaveSpeed hosts image, video, audio, and 3D models behind one API. This CLI adds a dynamic model runner for slash-delimited model IDs, free price estimates, local file uploads, a generation library with cost reports, and a D2C content layer (plan, pack, batch, variants, compose, aspects, restyle, brand, qa). Paid submissions are never replayed, and every post-submit failure keeps the prediction ID and a recovery command. ## When to Use This CLI Use this CLI to generate or edit images and video with WaveSpeed models from scripts or agents: check prices, upload reference files, run models with waits and downloads, and keep a local record of every generation and its cost. Use the plan/pack/batch commands for multi-platform D2C content production. ## Anti-triggers Do not use this CLI for: - Training or fine-tuning models - Hosting or serving your own models ## Unique Capabilities These capabilities aren't available in any other tool for this API. ### Core - **`run`** — Submit WaveSpeed model runs with prompt shorthand, typed --set inputs, local @file media uploads, price estimates, waiting, recovery-safe downloads, and library recording. _Use it for any single generation; the prediction ID and recovery command survive every post-submit failure._ ```bash wavespeed-pp-cli run --model-id google/nano-banana-2/edit --prompt "a red mug on oak" --images @ref.png --set aspect_ratio=9:16 --wait --download 'out/mug_{index}.{ext}' --agent ``` - **`schema`** — Fetch the live WaveSpeed model catalog and print the request schema for a model or project alias. _Check accepted inputs and enums before a paid run._ ```bash wavespeed-pp-cli schema google/nano-banana-2/edit --agent ``` - **`price`** — Estimate WaveSpeed model pricing with the same input syntax used by run, without submitting a prediction. _Free; quote the cost before spending._ ```bash wavespeed-pp-cli price --model-id google/nano-banana-2/edit --set aspect_ratio=9:16 --set resolution=2k --agent ``` - **`aliases`** — Read wavespeed.json aliases, default model, and output directory settings for repeatable local workflows. _See which short names map to which models._ ```bash wavespeed-pp-cli aliases --agent ``` - **`init`** — Write a starter wavespeed.json with aliases, default model, and output directory. _Start a new image project._ ```bash wavespeed-pp-cli init ``` ### Media - **`upload`** — Upload local image, video, or audio files to WaveSpeed media storage for use as model input URLs, retrying stalled uploads with a size-scaled deadline. _Turn a local file into a URL a model accepts._ ```bash wavespeed-pp-cli upload ./ref.png --agent ``` - **`download`** — Download generated output URLs with directory, exact-path, or templated-path destinations, never sending API credentials to CDN hosts. _Re-fetch outputs from a finished prediction._ ```bash wavespeed-pp-cli download "$OUTPUT_URL" --output 'out/{index}.{ext}' ``` - **`last`** — Print or open the most recent downloaded output. _Grab the path of the last generated file._ ```bash wavespeed-pp-cli last ``` ### Plan - **`plan brief-to-shotlist`** — Turn a free-text brief into a structured shotlist across platforms and aspect ratios with a hybrid deterministic-parser/LLM planner. _Draft the shot list for a campaign._ ```bash wavespeed-pp-cli plan brief-to-shotlist --prompt "Helm Black launch" --platforms instagram,tiktok --agent ``` - **`plan model-pick`** — Recommend a model for an intent from the live catalog with rationale. _Choose a model for a job._ ```bash wavespeed-pp-cli plan model-pick "short product video" --agent ``` - **`plan cost-estimate`** — Price a shotlist against live /model/pricing and the account balance, with cached-pricing fallback and per-shot breakdown. _Check a shotlist fits the budget._ ```bash wavespeed-pp-cli plan cost-estimate shotlist.json --agent ``` - **`qa preflight`** — Pass/warn/fail validation of a shotlist: balance vs cost, model availability, prompt safety, platform request-shape, and brand coverage. _Gate a pack before producing it._ ```bash wavespeed-pp-cli qa preflight shotlist.json --agent ``` ### Produce - **`pack`** — Produce a multi-platform creative pack from one concept at stable packs/// paths with per-platform manifests, concurrency, cost ceiling, and image-dimension validation; a rerun archives the superseded manifest. _Produce platform-ready assets._ ```bash wavespeed-pp-cli pack --concept "Helm Black hero" --platforms instagram,tiktok --max-cost 5.00 --agent ``` - **`batch`** — Submit many prompts from CSV or JSON with a spend ceiling and fail-fast/fail-tolerant semantics; records completed generations before any abort. _Run a prompt list under a budget._ ```bash wavespeed-pp-cli batch --from prompts.csv --max-cost 5.00 --agent ``` - **`variants`** — Sweep seed, style, or model off a base shot to produce comparable outputs with side-by-side metadata. _Explore seeds or models for one shot._ ```bash wavespeed-pp-cli variants --base shotlist.json --vary seed --count 4 --agent ``` - **`compose`** — Run an explicit multi-step pipeline (text->image->upscale->video), feeding each step's output to the next, with rollback of later steps on failure. _Turn a prompt into an image and then a clip._ ```bash wavespeed-pp-cli compose --steps "text->image,image->video" --prompt "..." --models m1,m2 --agent ``` ### Refine - **`aspects`** — Re-frame one image into standard platform aspect ratios, using outpaint when supported and an anchored re-render otherwise. _Make 9:16 and 1:1 versions of a hero image._ ```bash wavespeed-pp-cli aspects hero.png --platforms instagram,tiktok --agent ``` - **`restyle`** — Apply a brand profile or explicit style to an existing asset via img2img with a style prompt. _Bring an asset onto brand._ ```bash wavespeed-pp-cli restyle hero.png --brand helm --agent ``` ### Library - **`library`** — List, search (FTS5), show, tag, export, and cost-report the local generation library by brand, model, platform, and tag. _Find a past generation or total spend._ ```bash wavespeed-pp-cli library cost-report --group-by model --agent ``` - **`brand`** — Create, inspect, apply, and edit brand profiles that auto-merge into pack, compose, variants, restyle, and run. _Set up a brand for consistent output._ ```bash wavespeed-pp-cli brand init helm --palette '#111,#eee' --voice calm ``` ## Command Reference **account_balance** — Manage account balance - `wavespeed-pp-cli account-balance` — Retrieve the authenticated account balance. **billings** — Billing and usage records - `wavespeed-pp-cli billings` — Search billing records for the authenticated account. **media_uploads** — Manage media uploads - `wavespeed-pp-cli media-uploads` — Upload one existing local media file (image, video or audio) to WaveSpeed storage and return its URL for model inputs. **model_pricing** — Manage model pricing - `wavespeed-pp-cli model-pricing` — Estimate the unit price for a model run using the same inputs that will be submitted to the model endpoint. **models** — Model catalog and model metadata - `wavespeed-pp-cli models` — List available WaveSpeed models and their API schemas. **prediction_deletions** — Manage prediction deletions - `wavespeed-pp-cli prediction-deletions` — Delete one or more predictions from history. **prediction_results** — Manage prediction results - `wavespeed-pp-cli prediction-results ` — Retrieve the latest status and result payload for a prediction task. **predictions** — Prediction submission history and result retrieval - `wavespeed-pp-cli predictions` — Query recent prediction history. The API history window is limited; sync accumulates across runs. **usage_stats** — Manage usage stats - `wavespeed-pp-cli usage-stats` — Retrieve usage statistics for the authenticated account. ### Finding the right command When you know what you want to do but not which command does it, ask the CLI directly: ```bash wavespeed-pp-cli which "" ``` `which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one match; exit code `2` means no confident match — fall back to `--help` or use a narrower query. `--json` (and other machine formats) keep that exit-2 contract and write `{"matches":[]}` on stdout so agents can inspect the envelope without treating a miss as success. ## Recipes ### Image edit with a reference, 9:16 at 2k ```bash wavespeed-pp-cli run --model-id google/nano-banana-2/edit --prompt "$PROMPT" --images https://wavespeed.ai/anchor.png --set aspect_ratio=9:16 --set resolution=2k --wait --download 'raw/shot_{index}.{ext}' --record --agent ``` Pass a URL or a local `@file`; local files upload automatically. The download template names each output. ### First-and-last-frame video ```bash wavespeed-pp-cli run --model-id bytedance/seedance-v1.5-pro/image-to-video --prompt "$MOTION" --image https://wavespeed.ai/a.jpg --last-image https://wavespeed.ai/b.jpg --set duration=5 --wait --wait-timeout 10m --download 'clip_{index}.{ext}' --record --agent ``` `--wait-timeout` bounds polling; on timeout the prediction ID and recovery command are printed. ### Spend for a session ```bash wavespeed-pp-cli billings --page-size 20 --agent ``` Billing rows carry the charged price per prediction. ### Plan a campaign ```bash wavespeed-pp-cli plan brief-to-shotlist --prompt "launch" --platforms instagram,tiktok --agent ``` Save the shotlist, then run `plan cost-estimate` and `qa preflight` on it before `pack`. ## Auth Setup WaveSpeed uses an API key sent as `Authorization: Bearer `. Create one at https://wavespeed.ai/accesskey and export it as `WAVESPEED_API_KEY`. `doctor` verifies the key with a free `/balance` read. Run `wavespeed-pp-cli doctor` to verify setup. ## Agent Mode Add `--agent` to any command. Expands to: `--json --compact --no-input --no-color`. Global format flags share one contract on promoted, novel, sync, and `--deliver` paths: - `--json` — one JSON document on stdout (sync progress events go to stderr) - `--compact` — keep identity/status/timestamp fields; does not change the document vs stream shape - `--csv` / `--plain` — tabular rows (collection envelopes unwrap to the row array) - `--quiet` — one identity value per row, no envelope - **Pipeable** — JSON on stdout, errors on stderr - **Filterable** — `--select` keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs: ```bash wavespeed-pp-cli billings --agent --select code,data,message ``` - **Previewable** — `--dry-run` shows the request without sending - **Offline-friendly** — sync/search commands can use the local SQLite store when available - **Non-interactive** — never prompts, every input is a flag - **Explicit confirmation** — `--agent` does not imply `--yes`; pass `--yes` separately only after the target, arguments, and side effects are clear - **Explicit retries** — use `--idempotent` only when an already-existing create should count as success ### Response envelope Commands that read from the local store or the API wrap output in a provenance envelope: ```json { "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."}, "results": } ``` Parse `.results` for data and `.meta.source` to know whether it's live or local. A human-readable `N results (live)` summary is printed to stderr only when stdout is a terminal AND no machine-format flag (`--json`, `--csv`, `--compact`, `--quiet`, `--plain`, `--select`) is set — piped/agent consumers and explicit-format runs get pure JSON on stdout. ## Paths and state Agents should treat the CLI's path resolver as part of the runtime contract: - Use `--home ` for one invocation, or set `WAVESPEED_HOME=` to relocate all four path kinds under one root. - Use per-kind env vars only when a specific kind must diverge: `WAVESPEED_CONFIG_DIR`, `WAVESPEED_DATA_DIR`, `WAVESPEED_STATE_DIR`, `WAVESPEED_CACHE_DIR`. - Resolution order is per-kind env var, `--home`, `WAVESPEED_HOME`, XDG (`XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME`), then platform defaults. - `config` contains settings like `config.toml` and profiles. `data` contains `credentials.toml`, `data.db`, cookies, and auth sidecars. `state` contains persisted queries, jobs, and `teach.log`. `cache` contains regenerable HTTP/cache files. - Stored secrets live in `credentials.toml` under the data dir. Existing legacy `config.toml` secrets are read for compatibility and leave `config.toml` on the first auth write. - Run `wavespeed-pp-cli doctor --fail-on warn` to surface path and credential-location warnings. `agent-context` exposes a schema v4 `paths` block for agents that need the resolved dirs. - For MCP, pass relocation through the MCP host config. The MCP binary does not inherit CLI flags: ```json { "mcpServers": { "wavespeed": { "command": "wavespeed-pp-mcp", "env": { "WAVESPEED_HOME": "/srv/wavespeed" } } } } ``` Fleet precedence: an inherited per-kind env var overrides an explicit `--home` for that kind. Use `WAVESPEED_HOME` or per-kind vars as durable fleet levers, and use `--home` only for a single invocation. Relocation is not reversible by unsetting env vars; move files manually before clearing `WAVESPEED_HOME`, or `doctor` will not find credentials left under the former root. ## Automatic learning This CLI ships a self-capturing learning loop. The CLI does its own bookkeeping: every invocation is journaled locally, a failed flag followed by a corrected retry auto-derives a `flag_alias` candidate, and a `teach` on a query family without a playbook auto-synthesizes a `playbook_candidate` from the session's journal. Your job is judgment only: `recall` first, act on surfaced candidates, `teach` the final answer, `playbook amend` when you observe a correction. You never record failures by hand. ### Step 1: `recall` before any discovery Before list/search/drill commands on a new user question, pass the question as an argv or MCP tool argument to `recall --agent`. Do not interpolate user-controlled text into a shell command line. Quoted `recall ""` breaks on an apostrophe, which is ordinary English. A quoted heredoc breaks when a body line equals the delimiter, and that delimiter is published in these docs. Write the question with a non-shell file-writing tool, then read it back as data: ```bash # Write the question verbatim with your file-writing tool (no shell involved). # Command substitution on a file only ever yields data — the shell never # parses the file's bytes as syntax. QUERY=$(cat /path/to/question.txt) wavespeed-pp-cli recall "$QUERY" --agent ``` Prefer MCP: pass the question as the tool's query argument. `"$QUERY"` after a file read is argv-safe; putting the question itself in the command text is not. The response envelope: ```json { "query": "...", "normalized": "", "query_entities": ["..."], "found": true | false, "match_score": 0.0, "results": [ { "resource_id": "...", "resource_type": "...", "venue": "...", "confidence": 2, "entity_match": "exact|partial|unknown", "source": "taught|preseed|pattern", "warnings": ["..."] } ], "mismatches": [ /* only when --debug-mismatches */ ], "warnings": [ /* top-level */ ], "candidates": [ { "id": 12, "class": "flag_alias | playbook_candidate", "summary": "...", "sightings": 3, "last_seen": "...", "rationale": "...", "next_action": ["", "wavespeed-pp-cli learnings confirm 12"] } ], "playbook": { "query_family": "...", "playbook": { "steps": [ { "cmd": "", "purpose": "..." } ], "entity_slots": ["$ENTITY"], "expected_tool_calls": 3 }, "slots_resolved": { "$ENTITY": { "token": "", "canonical": "" } }, "notes": "" }, "notes": "" } ``` Empty-store short-circuit: if the store has no learnings, playbooks, or candidates yet (recall finds nothing and `learnings list` and `learnings candidates` are both empty), skip recall for the rest of this session instead of taxing every query; resume recall-first once something has been taught. ### Step 2: decision tree Read `candidates`, `playbook`, `notes`, `results[0]`, and warnings in that order: ``` if Candidates present (warnings include "candidates_present"): -> candidates are try-then-confirm, never facts. Follow each candidate's two-step next_action verbatim: run the trial command first, then run `learnings confirm ` only after the trial verified the behavior. Reject a wrong candidate with `learnings reject `. -> NEVER re-teach something recall surfaced as a candidate; confirm or reject that candidate instead of teaching a duplicate. -> candidates ride alongside playbooks and resource hits, not instead of them; continue with the branches below after acting on them. if Playbook present: -> READ Playbook.notes verbatim FIRST (workarounds + gotchas the CLI surface doesn't expose) -> replay Playbook.steps in order, substituting Playbook.slots_resolved entries for the entity slot tokens. If a step's slot is unresolved, fall back to discovery for that step only. -> the Playbook's