wavespeed-cli
CLAUDE.md26 starsChanged 27 days agoMITView on GitHub
Tests use Vitest and live in src/**/*.test.ts alongside the code they cover (excluded from the tsc build via tsconfig.json's exclude). Add new tests for pure helpers when you touch them. End-to-end command behavior is still verified against api.wavespeed.ai with a real API key in a scratch directory — vitest only covers logic, not the HTTP surface. One generic generation verb. wavespeed run <model_id|alias> is the only generic generate command; generate|edit|extend (src/commands/media.ts) are fixed-model shortcuts for the /chat models. Everything else…
- Reads credentials
- Installs packages
In this repositoryOne other file it gives its agents.
- wavespeedSkill
The file
Files
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Commands
npm install
npm run dev -- <subcommand> [args] # run from source via tsx (no build needed)
npm run build # tsc → dist/
npm run lint # tsc --noEmit
npm test # vitest run (unit tests for pure helpers)
npm run test:smoke # `tsx src/cli.ts --version` — boots the CLI
npm run format # prettier on src/**/*.tsTests use Vitest and live in src/**/*.test.ts alongside the code they cover (excluded from the tsc build via tsconfig.json's exclude). Add new tests for pure helpers when you touch them. End-to-end command behavior is still verified against api.wavespeed.ai with a real API key in a scratch directory — vitest only covers logic, not the HTTP surface.
Architecture
One generic generation verb. wavespeed run <model_id|alias> is the only generic generate command; generate|edit|extend (src/commands/media.ts) are fixed-model shortcuts for the /chat models. Everything else is auxiliary (auth, catalog browse, schema, upload/download, project config).
Two invariants that span multiple files:
- JSON-first stdout protocol (
src/lib/log.ts). When--jsonis set, stdout is reserved for the final JSON payload only; progress, spinners, and human text go to stderr. UsesetJsonMode/log/emitJson/emitJsonErrorin any new command. - The CLI never mutates user input. What the user passes is what hits the API. Don't add silent prompt prefixes, palette injections, or style suffixes. The two explicit mechanisms that transform input are aliases (named bundles of extra inputs) and the
@pathmarker (src/lib/local-files.ts), which uploads the referenced file and substitutes its hosted URL. The shortcut verbs are the one deliberate exception: they pick the endpoint and fit the request to the model's schema (enum snapping, clamps,@image 1prompt-reference renaming), print every change, and--estimateshows the final input;runnever does this. Never widen@into heuristic auto-detection of bare paths — that was tried and deliberately reverted.
Live API as catalog source. src/lib/api.ts:fetchModels() calls GET /api/v3/models and caches the response to ~/.cache/wavespeed/models-<first 16 hex of sha256(baseUrl + "\n" + apiKey)>.json (1h TTL). The catalog differs per caller (public / paid org / internal), so the cache is per key; the name never contains the key itself (callerCacheId in src/lib/config.ts), and @wavespeed/mcp uses the same name and format so both tools share it. The upload cache is likewise uploads-<same id>.json. The legacy shared models.json/uploads.json are left in place for older versions. models, schema, and dynamic run -h all read from this single payload. There is no bundled catalog.
Dynamic per-model help. src/lib/dynamic-help.ts:detectRunHelp() is called from src/cli.ts:main() before Commander parses argv. When it matches wavespeed run <token> -h, it resolves aliases, fetches the schema, and prints model-specific input help. Falls through to Commander's static help on failure.
Token resolution (src/lib/config.ts:resolveModelToken()):
- Contains
/→ always a model ID. - Bare name → looked up in
aliases(project beats user); unknown bare names returnnullso the caller fails loudly. - Missing → falls back to
defaultModel(which itself may be an alias name).
Input merge order in run: alias.input < --input-file < -i k=v < -p prompt. CLI flags always override alias defaults.
Config locations:
wavespeed.json(walks up CWD tree) — project:defaultModel,aliases,outputDir.~/.config/wavespeed-nodejs/config.json(viaconf) — per-machine:apiKey,baseUrl,defaultModel,aliases.- Env vars:
WAVESPEED_API_KEY(overrides stored key) andWAVESPEED_BASE_URL(overrides stored base URL).
SDK boundary: the official wavespeed npm SDK is used for upload() only; run submits and polls itself (submitPrediction/waitForPrediction in src/lib/api.ts) so the prediction ID is visible from the moment it exists. Direct calls cover /api/v3/models, /api/v3/balance, /api/v3/model/price, /api/v3/predictions, /api/v3/predictions/<id>/result, /api/v3/predictions/delete, /api/v3/billings/search, and /api/v3/user/usage_stats. Every endpoint the CLI touches must be v3 AND documented in the public api-doc — no internal or legacy contracts.
Useful page URLs live in src/lib/links.ts — a single map consumed by wavespeed open and the status footer. Adding/renaming a link is a one-file change.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

