wavespeed-cli: Instructions file for Claude Code

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

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.

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:

1. JSON-first stdout protocol (src/lib/log.ts). When --json is set, stdout is reserved for the final JSON payload only; progress, spinners, and human text go to stderr. Use setJsonMode/log/emitJson/emitJsonError in any new command.

2. 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 @path marker (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 1 prompt-reference renaming), print every change, and --estimate shows the final input; run never does this. Never widen @ into heuristic auto-detection of bare paths — that was tried and deliberately reverted.