pp-wavespeed

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/ai/wavespeed/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# 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.3 or newer):

```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.

## 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 a binary file to WaveSpeed media storage.

**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.

**run** — Submit generation tasks to slash-delimited WaveSpeed model paths.

- `wavespeed-pp-cli run <model-id> --input '<json>'` — Submit a model run with JSON inputs.
- `wavespeed-pp-cli run <model-id> --input-file request.json --price --wait --download` — Price, submit, poll, and download output URLs.

**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 <task_id>` — 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.

## Novel commands / Workflows (D2C content production)

WaveSpeed ships a content-production layer for D2C brands posting to social
(Instagram, TikTok, Facebook, X). It is **produce-only**: it emits post-ready
files plus a per-platform `manifest.json` a downstream social-posting tool
consumes. Every novel command emits a uniform agent envelope
(`command`, `results`, `suggested_next`, `recommended_action`,
`cost_spent`, `library_record_errors`, `partial_failure`) and supports
`--dry-run` to preview planned files, costs, and merged params without spending.

Novel commands record each generation to a local library DB by default; pass
`--no-record` to opt out. Plain `run` does the inverse — pass `--record` to
record it. A library write failure is logged and surfaced in
`library_record_errors`; it never fails a successful generation.

**Plan**

- `wavespeed-pp-cli plan brief-to-shotlist --prompt "<brief>" --platforms instagram,tiktok` — turn a brief into a structured shotlist. Hybrid planner: `--planner deterministic|llm|auto` (default `auto`), with an LLM fallback via `--planner-model <id>`. `--aspects` and `--from-file` are also accepted.
- `wavespeed-pp-cli plan model-pick <intent>` — recommend a model for an intent from the live catalog.
- `wavespeed-pp-cli plan cost-estimate <shotlist.json>` — price a shotlist against `/model/pricing` and your balance.

**Produce**

- `wavespeed-pp-cli pack --concept "<concept>" --platforms instagram,tiktok` — multi-platform pack at stable `packs/<slug>/<platform>/` paths with a per-platform manifest. Flags: `--aspects`, `--concurrency`, `--max-cost`, `--on-failure abort|continue`, `--history`, `--clean`, `--strict-video`, `--model`, `--brand`, `--seed`, `--out-dir`.
- `wavespeed-pp-cli batch --from shots.csv --max-cost 5.00` — submit many prompts from CSV/JSON. `--fail-tolerant` (default fail-fast), `--concurrency`, `--model`, `--brand`.
- `wavespeed-pp-cli variants --base shotlist.json --vary seed --count 4` — controlled sweep (`--vary seed|style|model`, `--values`).
- `wavespeed-pp-cli compose --steps "text->image,image->video" --prompt "..." --models m1,m2` — explicit step pipeline; a failed step rolls back later steps.

**Refine**

- `wavespeed-pp-cli aspects <image> --platforms instagram,tiktok` — re-frame one image to target ratios (`--aspects`, `--outpaint`, `--prompt`, `--model`).
- `wavespeed-pp-cli restyle <image> --brand helm` — apply a brand/style (`--style`, `--model`).

**Library**

- `wavespeed-pp-cli library list --brand helm --platform instagram --since 30d` — list recorded generations (`--model`, `--tag`, `--limit`).
- `wavespeed-pp-cli library search "<query>"` — FTS5 prompt search (`--limit`).
- `wavespeed-pp-cli library show <id>` — one generation with its tags.
- `wavespeed-pp-cli library tag <id> --add hero --remove draft` — tag management.
- `wavespeed-pp-cli library export <dir>` — export matching generations as JSON.
- `wavespeed-pp-cli library cost-report --since 30d --group-by brand` — cost rollup (`--group-by brand|model|platform|tag`).

**QA**

- `wavespeed-pp-cli qa preflight <shotlist.json>` — pass/warn/fail checks (balance vs cost, model availability, prompt safety, platform request-shape, brand coverage).

**Brand**

- `wavespeed-pp-cli brand init <name> --from-file brand.json` — create a profile (or use field flags: `--style-anchors`, `--negative`, `--palette`, `--voice`, `--models`, `--platforms`). Non-interactive by default.
- `wavespeed-pp-cli brand show <name>`, `brand list`, `brand apply <name>` (sets the active brand in `wavespeed.json`), `brand edit <name>`.

A full agent chain: `brand apply → plan brief-to-shotlist → plan cost-estimate → qa preflight → pack`, piping JSON between steps.

### 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 "<capability in your own words>"
```

`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.

## Auth Setup

Run `wavespeed-pp-cli auth setup` to print the URL and steps for getting a key (add `--launch` to open the URL). Then set:

```bash
export WAVESPEED_API_KEY="<your-key>"
```

Or persist it in `~/.config/wavespeed-pp-cli/config.toml`.

Run `wavespeed-pp-cli doctor` to verify setup.

## Agent Mode

Add `--agent` to any command. Expands to: `--json --compact --no-input --no-color --yes`.

- **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 id,name,status
  ```

- **Prev