@wavespeed/cli 0.3.0 → 0.4.1

package/README.md

@@ -90,9 +90,9 @@ wavespeed run ... -p "..." --json | jq '.outputs[0]'
 - **`defaultModel`** — `wavespeed run -p "…"` (no model arg) uses this. Can itself be an alias name.
 - **`aliases`** — your own shortcuts. `wavespeed run hero -p "…"` expands to model + input. CLI `-i k=v` flags override. `wavespeed run hero -h` shows the resolved schema. List them with `wavespeed aliases`.
 
-Resolution: positional with `/` is a model ID; otherwise looked up as an alias. Merge order on inputs: `alias.input` → `--input-file` → `-i k=v` → `-p`. **The CLI never rewrites your prompt or input values**, with one explicit exception: local file paths become hosted URLs.
+Resolution: positional with `/` is a model ID; otherwise looked up as an alias. Merge order on inputs: `alias.input` → `--input-file` → `-i k=v` → `-p`. **The CLI never rewrites your prompt or input values.** The one way to hand it a local file is the explicit `@` marker below — bare paths are passed through untouched, never uploaded.
 
-**Local files as inputs.** `-i image=./cat.png` uploads the file first and submits its URL — no separate `wavespeed upload` step. A bare value is only treated as a file when it has a media extension (image/video/audio) *and* exists on disk; prompt fields never auto-detect. Prefix with `@` (`-i image=@./cat.png`) to force an upload of any file — then a missing file is an error instead of a pass-through. The same file referenced twice uploads once.
+**Local files as inputs.** `-i image=@./cat.png` (curl-style) uploads the file and submits its hosted URL — no separate `wavespeed upload` step. Only `@`-prefixed values upload; a missing `@` file is an error. Identical bytes are content-hash cached for 24h, so repeated runs (and `price --upload`) reuse one upload and spare your quota.
 
 ## Recommended starting models
 
@@ -133,11 +133,13 @@ wavespeed models [query]                 Browse the live catalog (cached 1h)
 wavespeed aliases                        List aliases from wavespeed.json + user config
 
 # files
-wavespeed upload <file...>               Upload local file(s) → CDN URLs
+wavespeed upload <file...>               Upload local file(s) → CDN URLs (24h dedup cache)
 wavespeed download <url...>              Save URLs to disk
 
 # account & history
 wavespeed balance                        Show your current credit balance
+wavespeed usage [--since --until]        Spend + request counts, per-model (last 7d)
+wavespeed billings [--type --since …]    Itemized charges and refunds
 wavespeed price <model> -i k=v           Estimate the cost of a run (no charge)
 wavespeed top-up                         Open https://wavespeed.ai/top-up
 wavespeed history [--limit --status …]   List recent predictions (last 24h)

package/dist/cli.js

@@ -21,6 +21,8 @@ import { registerHistory } from './commands/history.js';
 import { registerShow } from './commands/show.js';
 import { registerDelete } from './commands/delete.js';
 import { registerOpen } from './commands/open.js';
+import { registerBillings } from './commands/billings.js';
+import { registerUsage } from './commands/usage.js';
 import { detectRunHelp, printDynamicRunHelp } from './lib/dynamic-help.js';
 // Read version from package.json at runtime so a bump in package.json is
 // reflected automatically (no second place to keep in sync).
@@ -64,6 +66,8 @@ registerHistory(program);
 registerShow(program);
 registerDelete(program);
 registerOpen(program);
+registerBillings(program);
+registerUsage(program);
 registerInit(program);
 registerSkill(program);
 program

package/dist/commands/billings.js

@@ -0,0 +1,82 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { fetchBillings } from '../lib/api.js';
+import { toIso } from '../lib/time.js';
+function money(v) {
+    if (v === undefined)
+        return '';
+    return `$${v.toFixed(4)}`;
+}
+function formatTime(iso) {
+    try {
+        return new Date(iso).toISOString().replace('T', ' ').slice(0, 19) + ' UTC';
+    }
+    catch {
+        return iso;
+    }
+}
+export function registerBillings(program) {
+    program
+        .command('billings')
+        .description('List itemized charges and refunds (billing records)')
+        .option('--page <n>', 'Page number', '1')
+        .option('--limit <n>', 'Page size (1-100)', '20')
+        .option('--type <t>', 'Filter by type: deduct or refund')
+        .option('--model <uuid>', 'Filter by model')
+        .option('--key <uuid>', 'Filter by the API key that generated the charge')
+        .option('--since <time>', 'Records after this time (ISO or YYYY-MM-DD)')
+        .option('--until <time>', 'Records before this time (ISO or YYYY-MM-DD)')
+        .option('--json', 'Emit JSON: {page, has_more, items}')
+        .action(async (opts) => {
+        const spinner = !opts.json ? ora('Fetching billing records…').start() : null;
+        try {
+            const data = await fetchBillings({
+                page: parseInt(opts.page, 10),
+                pageSize: parseInt(opts.limit, 10),
+                type: opts.type,
+                model: opts.model,
+                accessKey: opts.key,
+                startTime: opts.since ? toIso(opts.since) : undefined,
+                endTime: opts.until ? toIso(opts.until, true) : undefined,
+            });
+            spinner?.stop();
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+                return;
+            }
+            const items = data.items ?? [];
+            console.log();
+            console.log(chalk.bold(`${items.length} record${items.length === 1 ? '' : 's'}`) +
+                chalk.gray(`  · page ${data.page}${data.has_more ? '  · more available (--page)' : ''}`));
+            console.log();
+            if (items.length === 0) {
+                console.log(chalk.gray('  no billing records in this range.'));
+                console.log();
+                return;
+            }
+            let pageTotal = 0;
+            for (const b of items) {
+                const sign = b.billing_type === 'refund' ? chalk.green('+') : chalk.red('-');
+                pageTotal += (b.billing_type === 'refund' ? 1 : -1) * b.price;
+                const model = b.prediction?.model_uuid ?? '';
+                console.log(`  ${sign}${money(b.price).padEnd(10)} ${chalk.gray(formatTime(b.created_at))}  ` +
+                    chalk.white(model.padEnd(40)) +
+                    (b.access_key_name ? chalk.gray(` key:${b.access_key_name}`) : ''));
+                if (b.prediction?.uuid) {
+                    console.log('      ' + chalk.gray('prediction: ') + chalk.cyan(b.prediction.uuid));
+                }
+            }
+            console.log();
+            console.log(chalk.gray('  page net: ') +
+                (pageTotal < 0 ? chalk.red(`-$${Math.abs(pageTotal).toFixed(4)}`) : chalk.green(`+$${pageTotal.toFixed(4)}`)));
+            console.log();
+        }
+        catch (err) {
+            spinner?.fail(err.message ?? String(err));
+            if (opts.json) {
+                process.stdout.write(JSON.stringify({ error: err.message ?? String(err) }, null, 2) + '\n');
+            }
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/delete.js

@@ -7,10 +7,20 @@ export function registerDelete(program) {
         .command('delete')
         .description('Delete one or more predictions from your history')
         .argument('<id...>', 'Prediction ID(s) to delete')
-        .option('-y, --yes', 'Skip the confirmation prompt')
+        .option('-y, --yes', 'Skip the confirmation prompt (required in scripts / non-interactive use)')
         .option('--json', 'Emit JSON: {deleted: [...ids]}')
         .action(async (ids, opts) => {
-        if (!opts.yes && !opts.json) {
+        // --json controls output format only; it must never stand in for
+        // consent. Interactive terminals get the prompt, scripts must say -y.
+        if (!opts.yes) {
+            if (!process.stdin.isTTY) {
+                const msg = 'Refusing to delete without confirmation. Pass --yes in non-interactive use.';
+                if (opts.json)
+                    process.stdout.write(JSON.stringify({ error: msg }, null, 2) + '\n');
+                else
+                    console.error(chalk.red(msg));
+                process.exit(1);
+            }
             const go = await confirm({
                 message: `Delete ${ids.length} prediction${ids.length === 1 ? '' : 's'} from your history? This cannot be undone.`,
                 default: false,

package/dist/commands/history.js

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
 import ora from 'ora';
-import { fetchHistory } from '../lib/api.js';
+import { fetchHistory, PREDICTION_STATUSES } from '../lib/api.js';
+import { toIso } from '../lib/time.js';
 function statusBadge(status) {
     const map = {
         completed: chalk.bgGreen.black,
@@ -34,11 +35,19 @@ export function registerHistory(program) {
         .option('--page <n>', 'Page number', '1')
         .option('--limit <n>', 'Page size (1-100)', '20')
         .option('--model <id>', 'Filter by model ID')
-        .option('--status <s>', 'Filter by status (completed, failed, processing, pending)')
-        .option('--since <iso>', 'Show predictions created after this ISO timestamp')
-        .option('--until <iso>', 'Show predictions created before this ISO timestamp')
+        .option('--status <s>', 'Filter by status (created, processing, completed, failed, cancelled, timeout)')
+        .option('--since <time>', 'Predictions created after this time (ISO or YYYY-MM-DD)')
+        .option('--until <time>', 'Predictions created before this time (ISO or YYYY-MM-DD)')
         .option('--json', 'Emit JSON: {page, items: [...]}')
         .action(async (opts) => {
+        if (opts.status && !PREDICTION_STATUSES.includes(opts.status)) {
+            const msg = `Unknown status "${opts.status}". One of: ${PREDICTION_STATUSES.join(', ')}.`;
+            if (opts.json)
+                process.stdout.write(JSON.stringify({ error: msg }, null, 2) + '\n');
+            else
+                console.error(chalk.red('Error: ') + msg);
+            process.exit(1);
+        }
         const spinner = !opts.json ? ora('Fetching history…').start() : null;
         try {
             const data = await fetchHistory({
@@ -46,8 +55,8 @@ export function registerHistory(program) {
                 pageSize: parseInt(opts.limit, 10),
                 model: opts.model,
                 status: opts.status,
-                createdAfter: opts.since,
-                createdBefore: opts.until,
+                createdAfter: opts.since ? toIso(opts.since) : undefined,
+                createdBefore: opts.until ? toIso(opts.until, true) : undefined,
             });
             spinner?.stop();
             if (opts.json) {
@@ -57,7 +66,10 @@ export function registerHistory(program) {
             const items = data.items ?? [];
             console.log();
             console.log(chalk.bold(`${items.length} prediction${items.length === 1 ? '' : 's'}`) +
-                chalk.gray(`  · page ${data.page}`));
+                chalk.gray(`  · page ${data.page}`) +
+                // The silent 24h default made "where did yesterday's runs go?" a
+                // recurring surprise; name the window whenever it applies.
+                (opts.since || opts.until ? '' : chalk.gray('  · last 24h (widen with --since)')));
             console.log();
             if (items.length === 0) {
                 console.log(chalk.gray('  no predictions in this range. Try --since "2026-01-01" for a wider window.'));

package/dist/commands/price.js

@@ -3,6 +3,9 @@ import ora from 'ora';
 import { fetchPricing } from '../lib/api.js';
 import { parseInputs } from '../lib/inputs.js';
 import { resolveModelToken } from '../lib/config.js';
+import { collectLocalFiles, resolveLocalFiles } from '../lib/local-files.js';
+import { uploadWithCache } from '../lib/upload-cache.js';
+import { requireClient } from '../lib/client.js';
 export function registerPrice(program) {
     program
         .command('price')
@@ -10,6 +13,7 @@ export function registerPrice(program) {
         .argument('<model>', 'Model ID or alias')
         .option('-i, --input <pair...>', 'Inputs as key=value (same syntax as `wavespeed run`)', [])
         .option('-p, --prompt <text>', 'Shorthand for --input prompt=<text>')
+        .option('--upload', 'Upload @file inputs first so media-based pricing is exact (quota applies; identical bytes cached 24h)')
         .option('--json', 'Emit JSON')
         .action(async (modelArg, opts) => {
         const resolved = resolveModelToken(modelArg);
@@ -21,22 +25,74 @@ export function registerPrice(program) {
                 console.error(chalk.red('Error: ') + msg);
             process.exit(1);
         }
-        const inputs = { ...(resolved.defaultInput ?? {}) };
+        let inputs = { ...(resolved.defaultInput ?? {}) };
         Object.assign(inputs, parseInputs(opts.input ?? []));
         if (opts.prompt)
             inputs.prompt = opts.prompt;
+        // Pricing that depends on media (e.g. per-second video upscaling) is
+        // measured server-side from the URL, so a local path is useless to the
+        // pricing engine. Uploading is slow and quota-limited, so it is opt-in:
+        // without --upload we stop and say why, rather than silently sending a
+        // filesystem path and quoting from garbage.
+        const localRefs = collectLocalFiles(inputs);
+        let uploadedUrls = {};
+        if (localRefs.length > 0 && !opts.upload) {
+            const files = [...new Set(localRefs.map((r) => r.path))].join(', ');
+            const msg = `Input references local file(s): ${files}. ` +
+                'Pricing for media-dependent models is measured from a hosted URL. ' +
+                'Re-run with --upload to upload them for an exact quote (uses upload quota; identical bytes are cached 24h), or pass a URL directly.';
+            if (opts.json)
+                process.stdout.write(JSON.stringify({ error: msg }, null, 2) + '\n');
+            else
+                console.error(chalk.red('Error: ') + msg);
+            process.exit(1);
+        }
+        if (localRefs.length > 0 && opts.upload) {
+            const client = requireClient();
+            const upSpinner = !opts.json ? ora('Uploading for an exact quote…').start() : null;
+            try {
+                const resolvedFiles = await resolveLocalFiles(inputs, {
+                    upload: async (file) => {
+                        const { url, cached } = await uploadWithCache(file, (f) => client.upload(f));
+                        uploadedUrls[file] = url;
+                        if (cached)
+                            upSpinner && (upSpinner.text = 'Using cached upload…');
+                        return url;
+                    },
+                });
+                inputs = resolvedFiles.input;
+                upSpinner?.succeed(resolvedFiles.uploaded > 0 ? 'Uploaded.' : 'All files already uploaded (cache).');
+            }
+            catch (err) {
+                upSpinner?.fail(err.message ?? String(err));
+                if (opts.json)
+                    process.stdout.write(JSON.stringify({ error: err.message ?? String(err) }, null, 2) + '\n');
+                process.exit(1);
+            }
+        }
         const spinner = !opts.json ? ora('Calculating price…').start() : null;
         try {
             const data = await fetchPricing(resolved.model, inputs);
             spinner?.stop();
             if (opts.json) {
-                process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+                process.stdout.write(JSON.stringify({ ...data, uploaded: uploadedUrls }, null, 2) + '\n');
                 return;
             }
             console.log();
+            const effective = data.discounted_price > 0 ? data.discounted_price : data.price;
             console.log(chalk.bold('Estimated cost'));
             console.log('  ' + chalk.gray('model:   ') + chalk.cyan(data.model_id));
-            console.log('  ' + chalk.gray('price:   ') + chalk.green(`$${data.unit_price}`) + chalk.gray(` ${data.currency ?? 'USD'} per call`));
+            console.log('  ' + chalk.gray('price:   ') + chalk.green(`$${effective}`) + chalk.gray(` ${data.currency ?? 'USD'} per call`) +
+                (data.discounted_price > 0 && data.discounted_price !== data.price
+                    ? chalk.gray(`  (list $${data.price})`)
+                    : ''));
+            console.log();
+            for (const [file, url] of Object.entries(uploadedUrls)) {
+                console.log('  ' + chalk.gray('uploaded: ') + chalk.gray(file + ' → ') + chalk.cyan(url));
+            }
+            if (Object.keys(uploadedUrls).length > 0) {
+                console.log('  ' + chalk.gray('`wavespeed run` reuses these uploads automatically (content-hash cache).'));
+            }
             console.log();
             console.log(chalk.gray('Run it: ') + chalk.cyan(`wavespeed run ${modelArg}` + (opts.prompt ? ` -p "${opts.prompt}"` : '')));
             console.log();

package/dist/commands/run.js

@@ -5,6 +5,8 @@ import fs from 'node:fs';
 import { requireClient } from '../lib/client.js';
 import { parseInputs } from '../lib/inputs.js';
 import { resolveLocalFiles } from '../lib/local-files.js';
+import { submitPrediction, waitForPrediction } from '../lib/api.js';
+import { uploadWithCache } from '../lib/upload-cache.js';
 import { downloadOutputs, printOutputs } from '../lib/output.js';
 import { emitJson, emitJsonError, isJsonMode, log, setJsonMode } from '../lib/log.js';
 import { downloadOptsFromFlag } from '../lib/download-flag.js';
@@ -67,7 +69,7 @@ export function registerRun(program) {
         .command('run')
         .description('Run any Wavespeed model — generic invoke with --input key=value pairs')
         .argument('[model]', 'Model ID, alias name, or omit to use defaultModel.')
-        .option('-i, --input <pair...>', 'Inputs as key=value (repeatable). Local media paths auto-upload; @path forces upload. Dotted keys nest.', [])
+        .option('-i, --input <pair...>', 'Inputs as key=value (repeatable). @path uploads a local file and passes its URL. Dotted keys nest.', [])
         .option('-p, --prompt <text>', 'Shorthand for --input prompt=<text>')
         .option('--input-file <path>', 'JSON file with full input object')
         .option('--download [path]', 'Save outputs locally (optional path template, e.g. "./out/{index}.{ext}")')
@@ -95,14 +97,13 @@ export function registerRun(program) {
         Object.assign(input, parseInputs(opts.input ?? []));
         if (opts.prompt)
             input.prompt = opts.prompt;
-        // Local paths become hosted URLs before submission. Uploads go straight
-        // to object storage via a presigned PUT, so this is one extra round trip
-        // per distinct file rather than a reason to make the user run `upload`
-        // first and paste the result back.
+        // `@path` inputs become hosted URLs before submission. Only the
+        // explicit @ marker uploads — the CLI never guesses that a bare value
+        // was meant to be a file.
         try {
             const uploadSpinner = !isJsonMode() ? ora({ color: 'magenta' }) : null;
             const resolved = await resolveLocalFiles(input, {
-                upload: (file) => client.upload(file),
+                upload: async (file) => (await uploadWithCache(file, (f) => client.upload(f))).url,
                 onUpload: (file, i, total) => {
                     uploadSpinner?.start(total > 1
                         ? `Uploading ${path.basename(file)} (${i + 1}/${total})…`
@@ -123,55 +124,86 @@ export function registerRun(program) {
             (aliasName ? chalk.gray(`  (alias: ${aliasName})`) : ''));
         if (input.prompt)
             log(chalk.gray('  prompt: ') + chalk.white(String(input.prompt)));
+        // Submit and poll are deliberately separate calls. The moment the task
+        // exists we print its ID and arm a SIGINT handler — a paid generation
+        // must never be orphaned by a Ctrl+C or a dropped SSH session with the
+        // user left holding nothing to query.
         const spinner = ora({ text: 'Submitting…', color: 'magenta' });
         if (!isJsonMode())
             spinner.start();
         const startedAt = Date.now();
+        let submitted;
+        try {
+            submitted = await submitPrediction(model, input, { sync: !!opts.sync });
+        }
+        catch (err) {
+            const message = err.message ?? String(err);
+            spinner.fail(message);
+            if (isJsonMode())
+                emitJsonError(message);
+            process.exit(1);
+        }
+        const predictionId = submitted.id;
+        if (predictionId && !isJsonMode()) {
+            spinner.stopAndPersist({
+                symbol: chalk.gray('·'),
+                text: chalk.gray('prediction: ') + chalk.white(predictionId),
+            });
+            spinner.start('Generating…');
+        }
+        const abortNote = () => {
+            // Runs on Ctrl+C while the task is still going server-side. The task
+            // is NOT cancelled — it completes and is charged — so hand the user
+            // the way back to it.
+            process.stderr.write('\n' +
+                chalk.yellow('Interrupted — the task keeps running on the server.') +
+                '\n' +
+                (predictionId
+                    ? chalk.gray('  resume:  ') + chalk.cyan(`wavespeed show ${predictionId}`) + '\n'
+                    : ''));
+            process.exit(130);
+        };
+        if (predictionId)
+            process.on('SIGINT', abortNote);
         let result;
         try {
-            const iv = setInterval(() => {
-                const s = Math.floor((Date.now() - startedAt) / 1000);
-                spinner.text = `Generating… ${s}s`;
-            }, 200);
-            try {
-                result = await client.run(model, input, { enableSyncMode: !!opts.sync });
+            if (submitted.status === 'completed') {
+                // Sync mode finished within the request.
+                result = submitted;
             }
-            finally {
-                clearInterval(iv);
+            else if (!predictionId) {
+                throw new Error(`No prediction ID in response: ${JSON.stringify(submitted)}`);
+            }
+            else {
+                const iv = setInterval(() => {
+                    const s = Math.floor((Date.now() - startedAt) / 1000);
+                    spinner.text = `Generating… ${s}s`;
+                }, 200);
+                try {
+                    result = await waitForPrediction(predictionId, { intervalMs: 1000 });
+                }
+                finally {
+                    clearInterval(iv);
+                }
             }
             spinner.succeed(`Done in ${Math.floor((Date.now() - startedAt) / 1000)}s.`);
         }
         catch (err) {
             const message = err.message ?? String(err);
-            const syncTimeout = opts.sync ? extractSyncTimeoutDetails(message) : null;
-            if (syncTimeout && !isJsonMode()) {
-                spinner.fail('Sync mode timed out; the task is still processing asynchronously.');
-                log(chalk.gray('  reason: ') + message);
-                if (syncTimeout.predictionId) {
-                    log(chalk.gray('  prediction: ') + chalk.white(syncTimeout.predictionId));
-                    log(chalk.gray('  query:      ') + chalk.cyan(`wavespeed show ${syncTimeout.predictionId}`));
-                }
-                if (syncTimeout.resultUrl) {
-                    log(chalk.gray('  result URL: ') + chalk.cyan(syncTimeout.resultUrl));
-                }
-            }
-            else {
-                spinner.fail(message);
+            spinner.fail(message);
+            if (predictionId && !isJsonMode()) {
+                log(chalk.gray('  prediction: ') + chalk.white(predictionId));
+                log(chalk.gray('  query:      ') + chalk.cyan(`wavespeed show ${predictionId}`));
             }
             if (isJsonMode()) {
-                emitJsonError(message, syncTimeout
-                    ? {
-                        sync_timeout: true,
-                        prediction_id: syncTimeout.predictionId,
-                        result_url: syncTimeout.resultUrl,
-                        query_command: syncTimeout.predictionId
-                            ? `wavespeed show ${syncTimeout.predictionId}`
-                            : undefined,
-                    }
-                    : {});
+                emitJsonError(message, predictionId ? { prediction_id: predictionId, query_command: `wavespeed show ${predictionId}` } : {});
             }
             process.exit(1);
         }
+        finally {
+            if (predictionId)
+                process.removeListener('SIGINT', abortNote);
+        }
         const urls = extractUrls(result);
         let saved = [];
         const dlOpts = downloadOptsFromFlag(opts.download, {
@@ -193,6 +225,7 @@ export function registerRun(program) {
         }
         if (isJsonMode()) {
             emitJson({
+                id: predictionId,
                 model,
                 prompt: typeof input.prompt === 'string' ? input.prompt : undefined,
                 outputs: urls,

package/dist/commands/upload.js

@@ -2,10 +2,11 @@ import chalk from 'chalk';
 import ora from 'ora';
 import fs from 'node:fs';
 import { requireClient } from '../lib/client.js';
+import { uploadWithCache } from '../lib/upload-cache.js';
 export function registerUpload(program) {
     program
         .command('upload')
-        .description('Upload one or more local files to Wavespeed and print their CDN URLs')
+        .description('Upload one or more local files to Wavespeed and print their CDN URLs (identical bytes reuse the same upload for 24h)')
         .argument('<file...>', 'Path(s) to file(s)')
         .option('--json', 'Emit a JSON object on stdout')
         .action(async (files, opts) => {
@@ -25,9 +26,9 @@ export function registerUpload(program) {
         for (const file of files) {
             const spinner = !opts.json ? ora(`Uploading ${file}…`).start() : null;
             try {
-                const url = await client.upload(file);
+                const { url, cached } = await uploadWithCache(file, (f) => client.upload(f));
                 urls.push(url);
-                spinner?.succeed(`${file} → ${url}`);
+                spinner?.succeed(`${file} → ${url}` + (cached ? ' (cached)' : ''));
             }
             catch (err) {
                 const message = err.message ?? String(err);

package/dist/commands/usage.js

@@ -0,0 +1,62 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { fetchUsageStats } from '../lib/api.js';
+import { toIso } from '../lib/time.js';
+export function registerUsage(program) {
+    program
+        .command('usage')
+        .description('Usage statistics: spend, request counts, per-model breakdown (default: last 7 days)')
+        .option('--since <time>', 'Start of the window (ISO or YYYY-MM-DD)')
+        .option('--until <time>', 'End of the window (ISO or YYYY-MM-DD)')
+        .option('--model <uuid>', 'Restrict to one model')
+        .option('--json', 'Emit the raw stats as JSON')
+        .action(async (opts) => {
+        const spinner = !opts.json ? ora('Fetching usage…').start() : null;
+        try {
+            const now = new Date();
+            const start = opts.since
+                ? toIso(opts.since)
+                : new Date(now.getTime() - 7 * 24 * 3600 * 1000).toISOString();
+            const end = opts.until ? toIso(opts.until, true) : now.toISOString();
+            const stats = await fetchUsageStats(start, end, opts.model);
+            spinner?.stop();
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(stats, null, 2) + '\n');
+                return;
+            }
+            const s = stats.summary;
+            const failed = s.total_requests - s.success_requests;
+            console.log();
+            console.log(chalk.bold('Usage ') +
+                chalk.gray(`${start.slice(0, 10)} → ${end.slice(0, 10)}`) +
+                (opts.since || opts.until ? '' : chalk.gray('  · last 7d (widen with --since)')));
+            console.log();
+            console.log('  ' + chalk.gray('total spend:   ') + chalk.green(`$${s.total_cost.toFixed(4)}`));
+            console.log('  ' +
+                chalk.gray('requests:      ') +
+                chalk.white(`${s.total_requests}`) +
+                chalk.gray(`  (${s.success_requests} ok, ${failed} failed)`));
+            console.log();
+            const models = [...(stats.per_model_usage ?? [])].sort((a, b) => b.total_cost - a.total_cost);
+            if (models.length > 0) {
+                console.log(chalk.bold('  By model'));
+                for (const m of models.slice(0, 15)) {
+                    console.log('    ' +
+                        chalk.cyan(m.model_uuid.padEnd(44)) +
+                        chalk.green(`$${m.total_cost.toFixed(4)}`.padStart(10)) +
+                        (m.total_count ? chalk.gray(`  ×${m.total_count}`) : ''));
+                }
+                if (models.length > 15)
+                    console.log(chalk.gray(`    … ${models.length - 15} more (use --json)`));
+                console.log();
+            }
+        }
+        catch (err) {
+            spinner?.fail(err.message ?? String(err));
+            if (opts.json) {
+                process.stdout.write(JSON.stringify({ error: err.message ?? String(err) }, null, 2) + '\n');
+            }
+            process.exit(1);
+        }
+    });
+}

package/dist/lib/api.js

@@ -117,7 +117,9 @@ export async function fetchBalance() {
     return apiGet('/api/v3/balance');
 }
 export async function fetchPricing(modelId, inputs) {
-    return apiPost('/api/v3/model/pricing', { model_id: modelId, inputs });
+    // /model/price is the documented pricing endpoint; /model/pricing is a
+    // legacy contract kept for old clients and absent from the public docs.
+    return apiPost('/api/v3/model/price', { model_id: modelId, inputs });
 }
 export async function fetchHistory(query = {}) {
     const now = new Date();
@@ -127,7 +129,6 @@ export async function fetchHistory(query = {}) {
         page_size: query.pageSize ?? 20,
         created_after: query.createdAfter ?? oneDayAgo.toISOString(),
         created_before: query.createdBefore ?? now.toISOString(),
-        include_inputs: true,
     };
     if (query.model)
         body.model = query.model;
@@ -141,3 +142,67 @@ export async function fetchPrediction(id) {
 export async function deletePredictions(ids) {
     await apiPost('/api/v3/predictions/delete', { ids });
 }
+// Server-side prediction status enum (api-server internal/model/prediction.go).
+// Validated client-side so `--status pending` fails with the real list instead
+// of a server 400 or a silently empty page.
+export const PREDICTION_STATUSES = [
+    'created',
+    'processing',
+    'completed',
+    'failed',
+    'cancelled',
+    'timeout',
+];
+/**
+ * Submit a prediction WITHOUT waiting for it. Split from polling so the
+ * caller can print the prediction ID the moment it exists — a Ctrl+C or
+ * dropped connection mid-generation must never orphan a paid task.
+ */
+export async function submitPrediction(model, input, opts = {}) {
+    const body = { ...input };
+    if (opts.sync)
+        body.enable_sync_mode = true;
+    return apiPost(`/api/v3/${model}`, body);
+}
+/**
+ * Poll a prediction until it reaches a terminal status. `onTick` fires each
+ * round so the caller can keep a spinner honest.
+ */
+export async function waitForPrediction(id, opts = {}) {
+    const interval = opts.intervalMs ?? 1000;
+    for (;;) {
+        const item = await fetchPrediction(id);
+        opts.onTick?.(item.status);
+        if (item.status === 'completed')
+            return item;
+        if (item.status === 'failed' || item.status === 'cancelled' || item.status === 'timeout') {
+            throw new Error(`Prediction ${item.status}${item.error ? `: ${item.error}` : ''} (task_id: ${id})`);
+        }
+        if (opts.signal?.cancelled)
+            throw new Error(`cancelled (task_id: ${id})`);
+        await new Promise((r) => setTimeout(r, interval));
+    }
+}
+export async function fetchBillings(query = {}) {
+    const body = {
+        page: query.page ?? 1,
+        page_size: query.pageSize ?? 20,
+    };
+    if (query.type)
+        body.billing_type = query.type;
+    if (query.startTime)
+        body.start_time = query.startTime;
+    if (query.endTime)
+        body.end_time = query.endTime;
+    if (query.model)
+        body.model_uuid = query.model;
+    if (query.accessKey)
+        body.access_key_uuid = query.accessKey;
+    return apiPost('/api/v3/billings/search', body);
+}
+export async function fetchUsageStats(startTime, endTime, model) {
+    const body = { start_time: startTime, end_time: endTime };
+    if (model)
+        body.model_uuid = model;
+    return apiPost('/api/v3/user/usage_stats', body);
+}

package/dist/lib/config.js

@@ -8,7 +8,19 @@ export const DEFAULTS = {
 export const userConfig = new Conf({
     projectName: 'wavespeed',
     defaults: {},
+    // The config file holds the API key in cleartext; owner-only, not the
+    // default 0664 that leaves it group-readable.
+    configFileMode: 0o600,
 });
+// conf only applies configFileMode on write. Tighten a config that an older
+// CLI version already left group-readable.
+try {
+    if (fs.existsSync(userConfig.path))
+        fs.chmodSync(userConfig.path, 0o600);
+}
+catch {
+    /* best effort */
+}
 export const PROJECT_FILE = 'wavespeed.json';
 export function loadProjectConfig(cwd = process.cwd()) {
     let dir = cwd;
@@ -32,7 +44,9 @@ export function getApiKey() {
     return process.env.WAVESPEED_API_KEY || userConfig.get('apiKey');
 }
 export function getBaseUrl() {
-    return userConfig.get('baseUrl') || DEFAULTS.baseUrl;
+    // Env first, matching how the key resolves: CI pointing one command at the
+    // test environment must not require editing the user-level config.
+    return process.env.WAVESPEED_BASE_URL || userConfig.get('baseUrl') || DEFAULTS.baseUrl;
 }
 export function resolveOutputDir() {
     const project = loadProjectConfig();

package/dist/lib/local-files.js

@@ -1,36 +1,14 @@
-// Turn local file paths in a model's input into hosted URLs.
+// Turn `@`-prefixed local file paths in a model's input into hosted URLs.
 //
-// Uploading is cheap now that the platform hands out a presigned PUT and the
-// bytes go straight to object storage, so making the user run `upload` first
-// and paste the URL back is pure friction. This module finds the paths and
-// swaps them for URLs; run.ts does it once, right before submitting.
-//
-// Two ways to point at a file:
-//
-//   -i image=@./cat.png    explicit — always uploaded, missing file is an error
-//   -i image=./cat.png     implicit — uploaded only if it looks like media AND
-//                          exists on disk; otherwise passed through untouched
-//
-// The implicit rule is deliberately narrow. A model input that happens to
-// match a filename in the working directory must not be silently replaced by
-// a URL, so a bare value has to clear both the extension check and the
-// existence check. Anything already a URL is left alone.
+// The syntax is explicit on purpose — `-i image=@./cat.png`, borrowed from
+// curl. An earlier draft also auto-detected bare paths (media extension +
+// exists on disk), but that meant the CLI could upload a file the user never
+// asked to share based on a heuristic; a value that merely looks like a
+// filename must never leave the machine. No `@`, no upload: bare paths pass
+// through to the API untouched and fail model validation there if they were
+// meant to be files.
 import fs from 'node:fs';
 import path from 'node:path';
-// Extensions the platform's models actually accept as inputs. Kept explicit
-// rather than "any file that exists": a bare `-i seed=1.txt` should stay a
-// string even in a directory that happens to contain 1.txt.
-const MEDIA_EXTENSIONS = new Set([
-    // images
-    '.png', '.jpg', '.jpeg', '.webp', '.gif', '.bmp', '.tiff', '.tif', '.heic', '.heif', '.avif',
-    // video
-    '.mp4', '.mov', '.webm', '.mkv', '.avi', '.m4v',
-    // audio
-    '.mp3', '.wav', '.flac', '.m4a', '.aac', '.ogg', '.opus',
-]);
-// Free-text fields never auto-detect: `-p ./notes.txt` means that literal
-// string. An explicit `@` still works if someone genuinely wants it.
-const NO_IMPLICIT_DETECTION = new Set(['prompt', 'negative_prompt', 'system_prompt']);
 function isRegularFile(p) {
     try {
         return fs.statSync(p).isFile();
@@ -39,46 +17,28 @@ function isRegularFile(p) {
         return false;
     }
 }
-function isUrl(value) {
-    return /^(https?:|data:|s3:|gs:)/i.test(value);
-}
 /**
- * Walk the input and list every value that should become an upload. Pure over
- * `exists`, so the decision rules can be tested without touching the disk.
+ * Walk the input and list every `@path` value. Pure over `exists`, so the
+ * rules can be tested without touching the disk.
  */
-export function collectLocalFiles(input, opts = {}) {
-    const exists = opts.exists ?? isRegularFile;
+export function collectLocalFiles(input, _opts = {}) {
     const found = [];
-    const walk = (node, at, key) => {
+    const walk = (node, at) => {
         if (Array.isArray(node)) {
-            // Arrays inherit the key of their container, so `image_urls.0` is still
-            // judged as `image_urls` — element indices are not field names.
-            node.forEach((v, i) => walk(v, at ? `${at}.${i}` : String(i), key));
+            node.forEach((v, i) => walk(v, at ? `${at}.${i}` : String(i)));
             return;
         }
         if (node && typeof node === 'object') {
             for (const [k, v] of Object.entries(node)) {
-                walk(v, at ? `${at}.${k}` : k, k);
+                walk(v, at ? `${at}.${k}` : k);
             }
             return;
         }
-        if (typeof node !== 'string' || node === '')
-            return;
-        if (node.startsWith('@')) {
-            found.push({ path: node.slice(1), at, explicit: true });
-            return;
-        }
-        if (isUrl(node))
-            return;
-        if (NO_IMPLICIT_DETECTION.has(key))
+        if (typeof node !== 'string' || !node.startsWith('@'))
             return;
-        if (!MEDIA_EXTENSIONS.has(path.extname(node).toLowerCase()))
-            return;
-        if (!exists(node))
-            return;
-        found.push({ path: node, at, explicit: false });
+        found.push({ path: node.slice(1), at });
     };
-    walk(input, '', '');
+    walk(input, '');
     return found;
 }
 function setAt(root, dotted, value) {
@@ -89,16 +49,18 @@ function setAt(root, dotted, value) {
     cur[parts[parts.length - 1]] = value;
 }
 /**
- * Replace local paths in `input` with uploaded URLs. Returns a new object;
- * the caller's input is not mutated. Distinct paths upload once even when
- * referenced several times — the same image passed as two fields is one
- * upload, not two.
+ * Replace `@path` values in `input` with uploaded URLs. Returns a new object;
+ * the caller's input is not mutated. A missing file is an error — the user
+ * explicitly asked for an upload, so a silent pass-through would submit the
+ * literal `@path` string to the model. Distinct paths upload once even when
+ * referenced several times.
  */
 export async function resolveLocalFiles(input, opts) {
     const refs = collectLocalFiles(input, opts);
     if (refs.length === 0)
         return { input, uploaded: 0 };
-    const missing = refs.filter((r) => r.explicit && !(opts.exists ?? isRegularFile)(r.path));
+    const exists = opts.exists ?? isRegularFile;
+    const missing = refs.filter((r) => !exists(r.path));
     if (missing.length > 0) {
         throw new Error(`File not found: ${missing.map((m) => m.path).join(', ')}`);
     }

package/dist/lib/time.js

@@ -0,0 +1,16 @@
+// The predictions-search API is strict RFC3339, so bare dates the CLI's own
+// hints suggest ("--since 2026-01-01") must be widened here, not rejected
+// there. Shared by history, billings, and usage so every time flag accepts
+// the same two forms: full ISO 8601 or YYYY-MM-DD.
+/** Accepts ISO 8601 or YYYY-MM-DD; returns RFC3339. Day-only values span the
+ * whole day: start-of-day normally, end-of-day when `endOfDay` is set. */
+export function toIso(value, endOfDay = false) {
+    if (/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+        return value + (endOfDay ? 'T23:59:59Z' : 'T00:00:00Z');
+    }
+    const d = new Date(value);
+    if (isNaN(d.getTime())) {
+        throw new Error(`Invalid time "${value}". Use ISO 8601 or YYYY-MM-DD.`);
+    }
+    return d.toISOString();
+}

package/dist/lib/upload-cache.js

@@ -0,0 +1,58 @@
+// Content-addressed cache of uploaded files: sha256(file bytes) → hosted URL.
+//
+// Uploads are quota-limited per organization and slow for large videos, while
+// the same file routinely goes up more than once — `price --upload` followed
+// by `run`, or the same reference image across a batch of runs. Hashing the
+// bytes (not the path) means a renamed or copied file still hits.
+//
+// TTL is 24h: hosted media does not expire that fast, but a bounded window
+// keeps the cache from ever serving a URL the platform has since removed.
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+const TTL_MS = 24 * 60 * 60 * 1000;
+function cacheFile() {
+    return path.join(os.homedir(), '.cache', 'wavespeed', 'uploads.json');
+}
+function readCache() {
+    try {
+        return JSON.parse(fs.readFileSync(cacheFile(), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function writeCache(entries) {
+    try {
+        fs.mkdirSync(path.dirname(cacheFile()), { recursive: true });
+        fs.writeFileSync(cacheFile(), JSON.stringify(entries));
+    }
+    catch {
+        /* best-effort; a failed cache write must never fail the upload */
+    }
+}
+export function hashFile(filePath) {
+    return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+}
+/**
+ * Upload through `doUpload` unless the identical bytes already went up within
+ * the TTL. Returns the hosted URL either way.
+ */
+export async function uploadWithCache(filePath, doUpload) {
+    const key = hashFile(filePath);
+    const entries = readCache();
+    const hit = entries[key];
+    if (hit && Date.now() - hit.uploaded_at < TTL_MS) {
+        return { url: hit.url, cached: true };
+    }
+    const url = await doUpload(filePath);
+    entries[key] = { url, uploaded_at: Date.now() };
+    // Drop expired entries while we are here so the file stays small.
+    for (const [k, v] of Object.entries(entries)) {
+        if (Date.now() - v.uploaded_at >= TTL_MS)
+            delete entries[k];
+    }
+    writeCache(entries);
+    return { url, cached: false };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wavespeed/cli",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "WaveSpeed CLI — one command to run any WaveSpeed AI model from your terminal.",
   "publishConfig": {
     "access": "public"

package/skills/SKILL.md

@@ -23,7 +23,7 @@ wavespeed run google/nano-banana-2/text-to-image \
   -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.
+`run --json` returns `{ id, model, prompt, outputs: [url, ...], saved: [path, ...], elapsed_ms, raw }`. Keep `id` — it is the handle for `wavespeed show <id>` if anything is interrupted. Use the URL when the user wants a link. Add `--download` if they need bytes on disk.
 
 ## Recommended defaults
 
@@ -39,17 +39,18 @@ These are good starting points. Browse alternatives with `wavespeed models <quer
 ## Common recipes
 
 ```bash
-# Edit an existing image — upload first, then pass the URL
-URL=$(wavespeed upload ./input.jpg --json | jq -r .url)
+# Edit an existing image — @path uploads the file and passes its URL (one step)
 wavespeed run google/nano-banana-2/edit \
   -p "replace the background with a sunlit kitchen" \
-  -i images="[\"$URL\"]" --json
+  -i images='["@./input.jpg"]' --json
 
-# Image-to-video — same pattern
-URL=$(wavespeed upload ./hero.jpg --json | jq -r .url)
+# Image-to-video — same @ marker for single-URL fields
 wavespeed run bytedance/seedance-2.0/image-to-video \
   -p "subtle parallax, gentle wind" \
-  -i image="$URL" -i duration=5 --json
+  -i image=@./hero.jpg -i duration=5 --json
+
+# Or upload separately when you need the URL itself
+URL=$(wavespeed upload ./hero.jpg --json | jq -r .url)
 
 # Save outputs locally with a template
 wavespeed run ... -p "..." --download "./out/{index}.{ext}"
@@ -62,7 +63,7 @@ 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.
+The CLI never modifies the user's prompt or inputs. The single exception is explicit: an `@path` value uploads that file and substitutes its hosted URL. Bare paths are never uploaded.
 
 ## Auth
 
@@ -70,6 +71,8 @@ The CLI never modifies the user's prompt or inputs. What you typed is what hits
 
 ## Pitfalls
 
-- Local file paths don't auto-upload — call `wavespeed upload` first to get a CDN URL.
+- Local files: use `@./file.jpg` in `-i` values. Bare paths are NOT uploaded and the model will reject them.
 - 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.
+- `wavespeed delete` requires `--yes` when run non-interactively (that includes you).
+- Spend questions: `wavespeed usage` (totals, per-model) and `wavespeed billings` (per-charge records).