@wavespeed/cli 0.1.0

package/dist/lib/download-flag.js

@@ -0,0 +1,24 @@
+// Shared --download flag handling for image/video/run.
+//
+// Behavior (matches genmedia):
+//   (no flag)                  → no download, print URLs
+//   --download                 → save to outputDir with smart filename
+//   --download "./out.png"     → save to that path (single output)
+//   --download "./out/{index}.{ext}"  → templated path (multi output)
+// Commander hands `--download` with no value as boolean `true`. With a value it
+// gives us the string. With nothing, the property is `undefined`.
+export function resolveDownloadOpt(value) {
+    if (value === undefined)
+        return { enabled: false };
+    if (value === true)
+        return { enabled: true };
+    if (typeof value === 'string' && value.length > 0)
+        return { enabled: true, template: value };
+    return { enabled: false };
+}
+export function downloadOptsFromFlag(flagValue, base) {
+    const r = resolveDownloadOpt(flagValue);
+    if (!r.enabled)
+        return null;
+    return { ...base, template: r.template };
+}

package/dist/lib/dynamic-help.js

@@ -0,0 +1,162 @@
+// `wavespeed run <model> --help` introspects the model's request schema and
+// prints the actual flags the model accepts (matches genmedia's behavior).
+//
+// Called from cli.ts BEFORE Commander parses, so we can intercept --help.
+import chalk from 'chalk';
+import { fetchModels } from './api.js';
+import { findAlias } from './config.js';
+function getRequestSchema(m) {
+    return m.api_schema?.api_schemas?.[0]?.request_schema;
+}
+function typeLabel(p) {
+    if (Array.isArray(p.type))
+        return p.type.join('|');
+    if (p.type === 'array' && p.items?.type)
+        return `${p.items.type}[]`;
+    return p.type ?? 'any';
+}
+function wrap(text, indent, width = 92) {
+    const words = text.replace(/\s+/g, ' ').trim().split(' ');
+    const lines = [];
+    let cur = '';
+    for (const w of words) {
+        if ((cur + ' ' + w).length > width - indent.length) {
+            if (cur)
+                lines.push(cur);
+            cur = w;
+        }
+        else {
+            cur = cur ? cur + ' ' + w : w;
+        }
+    }
+    if (cur)
+        lines.push(cur);
+    return lines.map((l) => indent + chalk.gray(l)).join('\n');
+}
+/**
+ * Detect `wavespeed run <model> --help` (or `-h`) in argv. Returns the model id
+ * if matched, else null. Order doesn't matter (`--help` can come before or after
+ * the model).
+ */
+export function detectRunHelp(argv) {
+    const args = argv.slice(2);
+    if (args[0] !== 'run')
+        return null;
+    if (!args.some((a) => a === '--help' || a === '-h'))
+        return null;
+    // Find the first positional that looks like a model id (contains '/').
+    // We allow any non-flag token though — even a typo'd id should trigger this
+    // path so the error message guides the user.
+    for (const a of args.slice(1)) {
+        if (!a.startsWith('-'))
+            return a;
+    }
+    return null;
+}
+export async function printDynamicRunHelp(token) {
+    // Resolve aliases up-front so `wavespeed run <alias> -h` shows the underlying
+    // model's schema. Track the alias name + its default input for the example.
+    let modelId = token;
+    let aliasName;
+    let aliasDefaults;
+    if (!token.includes('/')) {
+        const alias = findAlias(token);
+        if (alias) {
+            modelId = alias.model;
+            aliasName = token;
+            aliasDefaults = alias.input;
+        }
+    }
+    let payload;
+    try {
+        payload = await fetchModels({});
+    }
+    catch (err) {
+        // Offline / not signed in — defer to static help.
+        process.stderr.write(chalk.gray(`(Could not fetch live schema: ${err.message ?? String(err)}. Falling back to static help.)\n`));
+        return;
+    }
+    const model = payload.models.find((m) => m.model_id === modelId);
+    if (!model) {
+        process.stdout.write(chalk.yellow(`Unknown model "${modelId}".`) +
+            chalk.gray(`  Try `) +
+            chalk.cyan(`wavespeed models "${modelId.split('/').pop()}"`) +
+            chalk.gray(' to search.\n'));
+        process.exit(1);
+    }
+    const schema = getRequestSchema(model);
+    if (!schema?.properties) {
+        process.stdout.write(chalk.yellow(`Model "${modelId}" has no published schema.`) +
+            chalk.gray('  Run it generically with `-i k=v` pairs.\n'));
+        process.exit(0);
+    }
+    const required = new Set(schema.required ?? []);
+    const order = (schema['x-order-properties'] ?? Object.keys(schema.properties)).filter((k) => k in schema.properties);
+    console.log();
+    console.log(chalk.hex('#7c5cff').bold(`  wavespeed run ${aliasName ?? model.model_id}`) +
+        (aliasName ? chalk.gray(`  →  ${model.model_id}`) : ''));
+    console.log(chalk.gray('  type:  ') +
+        chalk.white(model.type ?? 'unknown') +
+        (model.base_price !== undefined
+            ? chalk.gray('   base price: ') + chalk.green(`$${model.base_price}`)
+            : ''));
+    if (model.description)
+        console.log(wrap(model.description, '  '));
+    if (aliasDefaults && Object.keys(aliasDefaults).length > 0) {
+        console.log();
+        console.log(chalk.gray('  alias defaults: ') + chalk.gray(JSON.stringify(aliasDefaults)));
+    }
+    console.log();
+    console.log(chalk.bold('Usage:  ') +
+        chalk.cyan(`wavespeed run ${aliasName ?? model.model_id}`) +
+        chalk.gray(' [-i key=value ...] [--download [path]] [--json]'));
+    console.log();
+    console.log(chalk.bold('Inputs') +
+        chalk.gray(`  (${order.length} field${order.length === 1 ? '' : 's'}, ${required.size} required)`));
+    console.log();
+    const nameWidth = Math.max(...order.map((n) => n.length), 8);
+    for (const name of order) {
+        const p = schema.properties[name];
+        const flag = required.has(name) ? chalk.red('*') : ' ';
+        const t = chalk.magenta(typeLabel(p).padEnd(10));
+        console.log(`  ${flag} ${chalk.cyan(name.padEnd(nameWidth))}  ${t}`);
+        if (p.description)
+            console.log(wrap(p.description, '    '.padEnd(nameWidth + 6)));
+        const tail = [];
+        if (p.default !== undefined)
+            tail.push(`default: ${JSON.stringify(p.default)}`);
+        if (p.enum)
+            tail.push(`enum: ${p.enum.map((v) => String(v)).join(' | ')}`);
+        if (p.minimum !== undefined || p.maximum !== undefined)
+            tail.push(`range: ${p.minimum ?? '−∞'}..${p.maximum ?? '∞'}`);
+        if (p.minItems !== undefined || p.maxItems !== undefined)
+            tail.push(`items: ${p.minItems ?? 0}..${p.maxItems ?? '∞'}`);
+        if (tail.length)
+            console.log(' '.repeat(nameWidth + 6) + chalk.gray(tail.join('  ·  ')));
+    }
+    // Build a copy-paste example: required fields + prompt, skipping anything
+    // already supplied by an alias's defaults.
+    const seedFields = [...required];
+    if (!required.has('prompt') && 'prompt' in schema.properties)
+        seedFields.push('prompt');
+    const example = seedFields
+        .filter((n) => !aliasDefaults || !(n in aliasDefaults))
+        .map((n) => {
+        const p = schema.properties[n];
+        if (p?.default !== undefined)
+            return `-i ${n}=${JSON.stringify(p.default)}`;
+        if (p?.enum?.length)
+            return `-i ${n}=${JSON.stringify(p.enum[0])}`;
+        if (n.includes('prompt'))
+            return `-i ${n}="…"`;
+        if (n.includes('image') || n.includes('url'))
+            return `-i ${n}="<url>"`;
+        return `-i ${n}="…"`;
+    })
+        .join(' ');
+    console.log();
+    console.log(chalk.bold('Example:'));
+    console.log(`  ${chalk.cyan('wavespeed run ' + (aliasName ?? model.model_id) + (example ? ' ' + example : ''))}`);
+    console.log();
+    process.exit(0);
+}

package/dist/lib/inputs.js

@@ -0,0 +1,52 @@
+// Parse `--input key=value` pairs into a structured object suitable for the API.
+// - bare strings stay strings
+// - "123" / "1.5" parsed as number
+// - "true" / "false" parsed as boolean
+// - "[a,b,c]" parsed as array of strings
+// - JSON values (starting with { or [) parsed as JSON
+// - keys with dots like "size.width" become nested
+function coerce(raw) {
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    if (raw === 'null')
+        return null;
+    if (/^-?\d+$/.test(raw))
+        return parseInt(raw, 10);
+    if (/^-?\d+\.\d+$/.test(raw))
+        return parseFloat(raw);
+    if (raw.startsWith('{') || raw.startsWith('[')) {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    return raw;
+}
+export function parseInputs(pairs = []) {
+    const out = {};
+    for (const pair of pairs) {
+        const eq = pair.indexOf('=');
+        if (eq === -1) {
+            throw new Error(`Invalid --input value "${pair}". Use key=value.`);
+        }
+        const key = pair.slice(0, eq).trim();
+        const val = coerce(pair.slice(eq + 1));
+        setPath(out, key, val);
+    }
+    return out;
+}
+function setPath(obj, dotted, value) {
+    const parts = dotted.split('.');
+    let cur = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const k = parts[i];
+        if (typeof cur[k] !== 'object' || cur[k] === null)
+            cur[k] = {};
+        cur = cur[k];
+    }
+    cur[parts[parts.length - 1]] = value;
+}

package/dist/lib/log.js

@@ -0,0 +1,27 @@
+// Tiny logging helper so commands can emit progress to stderr while keeping
+// stdout reserved for the final --json payload (and downstream pipes).
+let jsonMode = false;
+export function setJsonMode(on) {
+    jsonMode = on;
+}
+export function isJsonMode() {
+    return jsonMode;
+}
+export function log(line) {
+    if (jsonMode)
+        return;
+    process.stdout.write(line + '\n');
+}
+export function info(line) {
+    if (jsonMode) {
+        process.stderr.write(line + '\n');
+        return;
+    }
+    process.stdout.write(line + '\n');
+}
+export function emitJson(payload) {
+    process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+}
+export function emitJsonError(message, extra = {}) {
+    process.stdout.write(JSON.stringify({ error: message, ...extra }, null, 2) + '\n');
+}

package/dist/lib/output.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { Readable } from 'node:stream';
+import chalk from 'chalk';
+import { resolveOutputDir } from './config.js';
+const EXT_FROM_URL = /\.([a-z0-9]{2,5})(?:\?|#|$)/i;
+function extFromUrl(url, fallback) {
+    const m = url.match(EXT_FROM_URL);
+    if (m)
+        return m[1].toLowerCase();
+    return fallback;
+}
+function slug(input) {
+    return input
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 48);
+}
+function stamp() {
+    return new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+}
+function renderTemplate(tpl, vars) {
+    return tpl.replace(/\{(\w+)\}/g, (_, k) => vars[k] ?? `{${k}}`);
+}
+export async function downloadOutputs(urls, opts = {}) {
+    const baseDir = path.resolve(opts.outputDir || resolveOutputDir());
+    const ts = stamp();
+    const tag = opts.prompt ? slug(opts.prompt) : opts.model ? slug(opts.model) : 'output';
+    const saved = [];
+    for (let i = 0; i < urls.length; i++) {
+        const url = urls[i];
+        const ext = extFromUrl(url, opts.ext || 'bin');
+        let filepath;
+        if (opts.template) {
+            const rendered = renderTemplate(opts.template, {
+                index: String(i + 1),
+                ext,
+                stamp: ts,
+                slug: tag,
+            });
+            filepath = path.resolve(rendered);
+            // Single-output, no {index} → use the template path verbatim.
+            // Multi-output, no {index} → suffix to avoid clobbering.
+            if (urls.length > 1 && !opts.template.includes('{index}')) {
+                const parsed = path.parse(filepath);
+                filepath = path.join(parsed.dir, `${parsed.name}-${i + 1}${parsed.ext}`);
+            }
+        }
+        else {
+            const suffix = urls.length > 1 ? `-${i + 1}` : '';
+            filepath = path.join(baseDir, `${ts}-${tag}${suffix}.${ext}`);
+        }
+        fs.mkdirSync(path.dirname(filepath), { recursive: true });
+        const res = await fetch(url);
+        if (!res.ok || !res.body) {
+            throw new Error(`Download failed for ${url}: ${res.status} ${res.statusText}`);
+        }
+        await pipeline(Readable.fromWeb(res.body), fs.createWriteStream(filepath));
+        saved.push(filepath);
+    }
+    return saved;
+}
+export function printOutputs(saved, remote) {
+    console.log();
+    if (saved.length) {
+        console.log(chalk.green('Saved:'));
+        for (const f of saved)
+            console.log('  ' + chalk.cyan(path.relative(process.cwd(), f)));
+        console.log();
+    }
+    console.log(chalk.gray(saved.length ? 'Source URLs:' : 'URLs:'));
+    for (const u of remote)
+        console.log('  ' + chalk.cyan(u));
+    console.log();
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@wavespeed/cli",
+  "version": "0.1.0",
+  "description": "WaveSpeed CLI — one command to run any WaveSpeed AI model from your terminal.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "wavespeed": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "start": "node dist/cli.js",
+    "prepublishOnly": "npm run build",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "lint": "tsc --noEmit",
+    "test": "tsx src/cli.ts --version"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "wavespeed",
+    "ai",
+    "cli",
+    "image-generation",
+    "video-generation",
+    "generative-ai",
+    "creative-tools"
+  ],
+  "author": "WaveSpeedAI <support@wavespeed.ai>",
+  "license": "MIT",
+  "homepage": "https://wavespeed.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/WaveSpeedAI/cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/WaveSpeedAI/cli/issues"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
+    "chalk": "^5.3.0",
+    "clipboardy": "^4.0.0",
+    "commander": "^12.1.0",
+    "conf": "^13.0.0",
+    "open": "^10.1.0",
+    "ora": "^8.1.0",
+    "wavespeed": "^0.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "prettier": "^3.3.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0"
+  }
+}

package/skills/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: wavespeed
+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.
+---
+
+# WaveSpeed
+
+You have access to the `wavespeed` CLI. Every generation flows through one verb. There are no `image` / `video` shortcuts; the model id is always explicit.
+
+## The three-step pattern
+
+```bash
+# 1. FIND a model — search the live catalog
+wavespeed models "nano banana"
+wavespeed models --type image-to-video --popular
+
+# 2. INSPECT its inputs — dynamic schema, per model
+wavespeed run google/nano-banana-2/text-to-image -h
+
+# 3. RUN it — always pass --json so you can read the result
+wavespeed run google/nano-banana-2/text-to-image \
+  -p "a cyberpunk skyline at golden hour" \
+  -i aspect_ratio="16:9" -i resolution="2k" --json
+```
+
+`run --json` returns `{ model, prompt, outputs: [url, ...], saved: [path, ...], elapsed_ms, raw }`. Use the URL when the user wants a link. Add `--download` if they need bytes on disk.
+
+## Recommended defaults
+
+| Use case | Model |
+|---|---|
+| Text → image | `google/nano-banana-2/text-to-image` |
+| Image edit (instruction-driven) | `google/nano-banana-2/edit` — requires `images: [url, ...]` |
+| Text → video | `bytedance/seedance-2.0/text-to-video` |
+| Image → video | `bytedance/seedance-2.0/image-to-video` — requires `image: url` |
+
+These are good starting points. Browse alternatives with `wavespeed models <query>`.
+
+## Common recipes
+
+```bash
+# Edit an existing image — upload first, then pass the URL
+URL=$(wavespeed upload ./input.jpg --json | jq -r .url)
+wavespeed run google/nano-banana-2/edit \
+  -p "replace the background with a sunlit kitchen" \
+  -i images="[\"$URL\"]" --json
+
+# Image-to-video — same pattern
+URL=$(wavespeed upload ./hero.jpg --json | jq -r .url)
+wavespeed run bytedance/seedance-2.0/image-to-video \
+  -p "subtle parallax, gentle wind" \
+  -i image="$URL" -i duration=5 --json
+
+# Save outputs locally with a template
+wavespeed run ... -p "..." --download "./out/{index}.{ext}"
+```
+
+## Project config and aliases
+
+If `wavespeed.json` exists (created by `wavespeed init`):
+
+- **`defaultModel`** — lets `wavespeed run -p "…"` (no model arg) work.
+- **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.
+
+The CLI never modifies the user's prompt or inputs. What you typed is what hits the API.
+
+## Auth
+
+`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.
+
+## Pitfalls
+
+- Local file paths don't auto-upload — call `wavespeed upload` first to get a CDN URL.
+- Don't invent model IDs. Always confirm via `wavespeed models` or `wavespeed schema <id>` before running.
+- Use `--json` on every `run` so you can read `outputs[0]` programmatically.