parley-live 0.1.0 → 0.3.0

package/README.md

@@ -5,7 +5,7 @@ Generate images, video clips, YouTube thumbnails and spokesperson product ads fr
 ```bash
 npm install -g parley-live
 parley login                     # one browser sign-in, stored under ~/.parley
-parley account                   # your credit balance
+parley doctor                    # everything an agent needs to know before spending: session, credits, engines, fixes
 parley image "a matte black espresso machine on marble, morning light" --out hero.png
 parley video "steam rises, slow push in" --image hero.png --look standard --move dolly-in --ratio 9:16
 parley thumbnail "I tested every AI video tool" --overlay "ALL OF THEM" --variants 3
@@ -16,12 +16,15 @@ parley ugc-ad --product product.jpg --name "Cold Brew Kit" --actor jordan --mark
 
 | Command | What it does |
 |---|---|
-| `parley login` | Device-code sign-in. Prints a link, you sign in once in the browser, the CLI receives a session token. |
+| `parley doctor [--require <version>]` | Node, server, session, credits, live engines, the `@last` outputs, whether a newer release exists, and the fix for anything missing. `--require` fails "ready" when this CLI is older than what your skills expect. Run it first; `--json` for agents. |
+| `parley voice "<text>" \| --file script.txt` | Narration as a hosted WAV. `--voice warm\|energetic\|documentary\|deep\|bright\|storyteller`, `--quality natural\|fish\|studio`, `--no-fallback`, `--out`. Natural voice: 1 credit per 1,000 characters; studio: 1 per 300. Becomes `@last` for `--narration`. `parley voices` lists personas and prices. |
+| `parley studio …` | The film pipeline without JSON: `character add\|cast\|list`, `shot add\|list`, `render <shotId> [--wait]`, `assemble`, `reels`. Every subcommand takes `--project proj_…`. |
+| `parley login [--no-browser]` | Device-code sign-in. Prints a link, you sign in once in the browser, the CLI receives a session token. `--no-browser` prints the link instead of opening it (cloud sandboxes, SSH). |
 | `parley account` | Credit balance. |
 | `parley engines` | Which video engines this server can run right now, with credit rates. |
 | `parley camera-moves` | The named camera-move presets accepted by `video --move`. |
-| `parley image "<prompt>"` | Generate an image. `--model`, `--size`, `--quality`, `--image-size`, `--ref <file\|url>` (repeatable), `--out`. |
-| `parley video "<motion prompt>"` | Animate a still (`--image`) or text-to-video (`--look photoreal`). `--look`, `--move` (repeatable, up to 3), `--duration`, `--ratio`, `--out`. |
+| `parley image "<prompt>"` | Generate an image. `--ratio 16:9\|9:16\|1:1\|4:3\|3:4` sizes it for the destination; `--model`, `--quality`, `--image-size`, `--ref <file\|url\|@last>` (repeatable), `--out`. |
+| `parley video "<motion prompt>"` | Animate a still (`--image <file\|url\|@last>`) or text-to-video (`--look photoreal`). `--look`, `--move` (repeatable, up to 3), `--duration`, `--ratio`, `--out`. |
 | `parley thumbnail "<title>"` | 1-3 YouTube thumbnail variants. `--overlay`, `--accent`, `--person`, `--out <dir>`. |
 | `parley ugc-ad` | Product photo → spokesperson ad with a marketplace CTA end-card. `--product`, `--name`, `--actor` or `--face`, `--angle`, `--marketplace`, `--points`, `--seconds`, `--url`, `--out`. |
 | `parley youtube` | A complete faceless video from ordered beat stills: animated per beat, cut to `--narration` with crossfades, `--music` ducked, `--captions` burned in. `--beat` (repeatable, hosted https URLs), `--tier fast\|standard\|cinematic`, `--silent`, `--project`, `--out`. |
@@ -41,6 +44,30 @@ parley ugc-ad --product product.jpg --name "Cold Brew Kit" --actor jordan --mark
 
 `--move` works with every look. On `camera` the move drives the engine; on the others it becomes precise camera direction in the prompt. A named move beats "the camera moves dramatically" every time.
 
+### Chaining with `@last`
+
+The CLI remembers the last image and the last clip it made (`~/.parley/last.json`), so a still becomes a clip without re-typing a URL:
+
+```bash
+parley image "matte black espresso machine on marble, morning light" --ratio 9:16 --out hero.png
+parley video "steam rises, a hand lifts the cup" --image @last --move dolly-in --ratio 9:16
+parley image "same machine, top-down on oak" --ref @last --ratio 1:1
+parley voice --file script.txt --voice documentary --out narration.wav
+parley youtube --beat https://…/01.png --beat https://…/02.png --narration @last --captions
+```
+
+### A film from the terminal
+
+```bash
+parley studio character add --project proj_letter-7f3k --name Maya --description "Maya, 32, athletic, oval face, dark hair in a low knot, oat technical top"
+parley studio character cast char_… 
+parley studio shot add --project proj_letter-7f3k --order 0 --framing "Maya at a kitchen table at dawn, medium shot" \
+  --directing "She unfolds the letter and reads. Clip ends with her eyes on the page." \
+  --characters char_… --duration 12 --camera "arri-alexa-35, dolly-in"
+parley studio render shot_… --wait
+parley studio assemble --project proj_letter-7f3k --title "The Letter" --synopsis "A woman reads the letter she avoided."
+```
+
 ## For agents
 
 Add `--json` to any command and read the last line of stdout:
@@ -51,7 +78,9 @@ Add `--json` to any command and read the last line of stdout:
 
 Errors are `{"ok":false,"error":"…","code":N}`. Exit codes: `2` not signed in, `3` cannot reach the server, `4` not enough credits, `5` the model declined the prompt, `64` bad usage, `1` anything else. Progress goes to stderr, results to stdout.
 
-The MIT-licensed agent skills that teach Claude Code, Cursor and Codex how to use this CLI well live in the [`skills`](../skills) directory.
+The MIT-licensed agent skills that teach Claude Code, Cursor, Codex, Gemini CLI, Copilot and 20 other agents how to use this CLI well live at [github.com/onehermes/parley-skills](https://github.com/onehermes/parley-skills): `npx skills add onehermes/parley-skills`.
+
+In a cloud sandbox or over SSH: `parley login --no-browser` prints the approval link, `PARLEY_TOKEN` skips login entirely, and `npx -y parley-live …` runs without a global install.
 
 ## Configuration
 

package/dist/client.js

@@ -169,6 +169,39 @@ export function fileToDataUri(filePath) {
 export function isUrl(s) {
     return /^https?:\/\//i.test(s);
 }
+function lastPath() {
+    return path.join(homeDir(), 'last.json');
+}
+export function loadLast() {
+    try {
+        const p = lastPath();
+        if (!existsSync(p))
+            return {};
+        const parsed = JSON.parse(readFileSync(p, 'utf8'));
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function rememberLast(kind, entry) {
+    try {
+        mkdirSync(homeDir(), { recursive: true });
+        const cur = loadLast();
+        cur[kind] = { file: path.resolve(entry.file), url: entry.url, at: new Date().toISOString() };
+        writeFileSync(lastPath(), JSON.stringify(cur, null, 2) + '\n');
+    }
+    catch { /* best effort: chaining is a convenience, never a failure */ }
+}
+/** Resolve "@last" (or "@last-image" / "@last-video") to the most recent output of that kind. */
+export function resolveRef(ref, kind) {
+    if (ref !== '@last' && ref !== `@last-${kind}`)
+        return ref;
+    const last = loadLast()[kind];
+    if (!last)
+        throw new CliError(`No previous ${kind} on this machine yet. Make one first (parley ${kind} …), then pass @last.`);
+    return last.url || last.file;
+}
 export function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }

package/dist/index.js

@@ -16,8 +16,18 @@
  */
 import { readFileSync, existsSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
-import { api, authWebUrl, backendUrl, clearCredentials, CliError, downloadTo, fileToDataUri, isUrl, loadCredentials, openInBrowser, saveCredentials, sleep, } from './client.js';
-const VERSION = '0.1.0';
+import { api, authWebUrl, backendUrl, clearCredentials, CliError, downloadTo, fileToDataUri, isUrl, loadCredentials, loadLast, openInBrowser, rememberLast, resolveRef, saveCredentials, sleep, } from './client.js';
+const VERSION = '0.3.0';
+/** Semver-ish compare: 1 if a > b, -1 if a < b, 0 if equal (numeric parts only). */
+function compareVersions(a, b) {
+    const pa = a.replace(/^v/, '').split('.').map((x) => parseInt(x, 10) || 0);
+    const pb = b.replace(/^v/, '').split('.').map((x) => parseInt(x, 10) || 0);
+    for (let i = 0; i < 3; i++) {
+        if ((pa[i] || 0) !== (pb[i] || 0))
+            return (pa[i] || 0) > (pb[i] || 0) ? 1 : -1;
+    }
+    return 0;
+}
 function parseArgs(argv) {
     const out = { command: '', positionals: [], flags: {} };
     const rest = [...argv];
@@ -72,6 +82,10 @@ async function cmdLogin(p) {
     const backend = backendUrl(str(p.flags.backend));
     const started = await api('/api/auth/device/start', { method: 'POST', body: {}, auth: false, backend });
     const link = `${authWebUrl()}/desktop-auth?code=${encodeURIComponent(started.user_code)}`;
+    // --no-browser: print the link only. The right choice inside a cloud
+    // sandbox or over SSH, where "open a browser" means someone else's screen.
+    if (p.flags['no-browser'] === true)
+        process.env.PARLEY_NO_BROWSER = '1';
     const opened = openInBrowser(link);
     // Always on stderr, even in --json mode: an agent driving `parley login
     // --json` must be able to relay the link to the person who has to click it.
@@ -140,12 +154,22 @@ function outPathFor(p, defaultName) {
 async function cmdImage(p) {
     const prompt = p.positionals.join(' ').trim();
     if (!prompt)
-        throw new CliError('Usage: parley image "<prompt>" [--model gpt-image-2|gemini-3-pro-image-preview] [--size 1024x1024|1024x1536|1536x1024] [--quality low|medium|high] [--image-size 1K|2K|4K] [--ref <file|url>]... [--out file.png]');
-    const refs = list(p.flags.ref).map((r) => (isUrl(r) ? r : fileToDataUri(r)));
+        throw new CliError(`Usage: parley image "<prompt>" [--ratio ${Object.keys(RATIO_TO_SIZE).join('|')}] [--model gpt-image-2|gemini-3-pro-image-preview] [--size 1024x1024|1024x1536|1536x1024] [--quality low|medium|high] [--image-size 1K|2K|4K] [--ref <file|url|@last>]... [--out file.png]`);
+    const refs = list(p.flags.ref).map((r) => resolveRef(r, 'image')).map((r) => (isUrl(r) ? r : fileToDataUri(r)));
     const body = { prompt };
     const model = str(p.flags.model);
     if (model)
         body.model = model;
+    // --ratio is the destination-first way to size an image: it sets the exact
+    // gpt-image-2 size AND the aspect ratio the other models take, so the same
+    // flag works whichever model serves the request. --size still wins if given.
+    const ratio = str(p.flags.ratio);
+    if (ratio) {
+        if (!(ratio in RATIO_TO_SIZE))
+            throw new CliError(`--ratio must be one of ${Object.keys(RATIO_TO_SIZE).join(', ')}`);
+        body.aspectRatio = ratio;
+        body.gptImageSize = RATIO_TO_SIZE[ratio];
+    }
     const size = str(p.flags.size);
     if (size)
         body.gptImageSize = size;
@@ -175,8 +199,13 @@ async function cmdImage(p) {
     }
     else
         throw new CliError('The server returned no image.');
+    rememberLast('image', { file: out, url: r.imageUrl ?? null });
     emit({ ok: true, file: out, bytes, model: r.model, imageUrl: r.imageUrl ?? null, revisedPrompt: r.revisedPrompt ?? null }, `Saved ${out} (${Math.round(bytes / 1024)} KB, ${r.model})${r.imageUrl ? `\nHosted: ${r.imageUrl}` : ''}`);
 }
+/** Destination ratio → the exact gpt-image-2 size (the other models take the ratio itself). */
+const RATIO_TO_SIZE = {
+    '16:9': '1536x1024', '9:16': '1024x1536', '1:1': '1024x1024', '4:3': '1536x1024', '3:4': '1024x1536',
+};
 const LOOKS = ['fast', 'standard', 'cinematic', 'photoreal', 'transform', 'camera'];
 const LOOK_TO_PROVIDER = {
     fast: 'hailuo', standard: 'kling', illustrated: 'kling', cinematic: 'veo', photoreal: 'seedance-2.0', transform: 'gemini-omni', camera: 'higgsfield-dop',
@@ -188,7 +217,8 @@ async function cmdVideo(p) {
     const look = str(p.flags.look, 'standard');
     if (!(look in LOOK_TO_PROVIDER))
         throw new CliError(`Unknown --look "${look}". Use one of: ${LOOKS.join(', ')}.`);
-    const image = str(p.flags.image);
+    const imageFlag = str(p.flags.image);
+    const image = imageFlag ? resolveRef(imageFlag, 'image') : undefined;
     const imageFiles = image ? [isUrl(image) ? image : fileToDataUri(image)] : [];
     if (!image && look !== 'photoreal') {
         throw new CliError('Every look except "photoreal" animates a still: pass --image <file|url> (make one with `parley image` first), or use --look photoreal for text-to-video.');
@@ -226,6 +256,7 @@ async function cmdVideo(p) {
     const out = outPathFor(p, `parley-video-${jobId}.mp4`);
     const src = r.videoUrl || `${backendUrl()}/video/jobs/${jobId}/result?download=1`;
     const bytes = await downloadTo(src, out);
+    rememberLast('video', { file: out, url: r.videoUrl ?? null });
     emit({ ok: true, file: out, bytes, jobId, videoUrl: r.videoUrl ?? null, model: r.model ?? null, duration: r.duration ?? null, width: r.width ?? null, height: r.height ?? null, deduped: created.deduped === true }, `Saved ${out} (${Math.round(bytes / 1024)} KB, ${r.model || look}, ${r.duration ?? '?'}s)${r.videoUrl ? `\nHosted: ${r.videoUrl}` : ''}`);
 }
 async function cmdThumbnail(p) {
@@ -341,12 +372,16 @@ async function cmdYoutube(p) {
     const tier = str(p.flags.tier, 'standard');
     if (!YT_TIERS.includes(tier))
         throw new CliError(`--tier must be one of ${YT_TIERS.join(', ')}`);
-    const narration = str(p.flags.narration);
+    const narrationFlag = str(p.flags.narration);
+    const narration = narrationFlag ? resolveRef(narrationFlag, 'audio') : undefined;
     const music = str(p.flags.music);
     const project = str(p.flags.project);
     const silent = p.flags.silent === true;
     if (!narration && !silent) {
-        throw new CliError('Pass --narration <https audio URL> (the voiceover the video is cut to), or --silent if the user explicitly wants no voiceover.');
+        throw new CliError('Pass --narration <https audio URL | @last> (the voiceover the video is cut to; make one with `parley voice`), or --silent if the user explicitly wants no voiceover.');
+    }
+    if (narration && !isUrl(narration)) {
+        throw new CliError(`--narration must be a public https URL (got "${narration}"). \`parley voice\` prints one, and @last reuses it.`);
     }
     const body = {
         beats: beats.map((imageUrl) => ({ imageUrl })),
@@ -385,6 +420,222 @@ async function cmdYoutube(p) {
     const bytes = await downloadTo(videoUrl, out);
     emit({ ok: true, file: out, bytes, jobId: created.jobId, videoUrl, estimatedCredits: created.estimatedCredits ?? null, result: job.result }, `Saved ${out} (${Math.round(bytes / 1024)} KB)\nHosted: ${videoUrl}`);
 }
+const VOICES = ['warm', 'energetic', 'documentary', 'deep', 'bright', 'storyteller'];
+const VOICE_TIERS = ['natural', 'fish', 'studio'];
+/**
+ * parley voice "<text>" | --file script.txt [--voice warm|…] [--quality natural|fish|studio]
+ *   [--no-fallback] [--out narration.wav]
+ * Narration as a hosted WAV. Natural (Kokoro) costs 1 credit per 1,000
+ * characters, studio (ElevenLabs) 1 per 300; the server never ships the
+ * synthetic fallback voice silently (voiceWarning), and --no-fallback refuses
+ * it outright. The result is @last for --narration.
+ */
+async function cmdVoice(p) {
+    const file = str(p.flags.file);
+    let text = p.positionals.join(' ').trim();
+    if (file) {
+        if (!existsSync(file))
+            throw new CliError(`Script file not found: ${file}`);
+        text = readFileSync(file, 'utf8').trim();
+    }
+    if (!text)
+        throw new CliError(`Usage: parley voice "<text>" | --file script.txt [--voice ${VOICES.join('|')}] [--quality ${VOICE_TIERS.join('|')}] [--no-fallback] [--out narration.wav]`);
+    if (text.length > 5000)
+        throw new CliError(`The text is ${text.length} characters; each request takes up to 5,000. Split the script into sections and make one file per section.`);
+    const voice = str(p.flags.voice);
+    if (voice && !VOICES.includes(voice))
+        throw new CliError(`--voice must be one of ${VOICES.join(', ')}`);
+    const quality = str(p.flags.quality, 'natural');
+    if (!VOICE_TIERS.includes(quality))
+        throw new CliError(`--quality must be one of ${VOICE_TIERS.join(', ')}`);
+    const body = { text, quality, ...(voice ? { voice } : {}), ...(p.flags['no-fallback'] === true ? { allowFallback: false } : {}) };
+    note(`Narrating ${text.length} characters with the ${quality} voice${voice ? ` (${voice})` : ''}…`);
+    const r = await api('/api/voice/generate', { body });
+    const out = outPathFor(p, `parley-voice-${Date.now()}.wav`);
+    const bytes = await downloadTo(r.audioUrl, out);
+    rememberLast('audio', { file: out, url: r.audioUrl });
+    if (r.voiceWarning)
+        console.error(`warning: ${r.voiceWarning}`);
+    emit({ ok: true, file: out, bytes, audioUrl: r.audioUrl, durationSeconds: r.durationSeconds, engine: r.engine, voice: r.voice, creditsCharged: r.creditsCharged, voiceWarning: r.voiceWarning ?? null }, `Saved ${out} (${r.durationSeconds ?? '?'}s, ${r.engine}, ${r.creditsCharged} credits)\nHosted: ${r.audioUrl}`);
+}
+async function cmdVoices() {
+    const v = await api('/api/voice/voices', { auth: false });
+    if (JSON_MODE) {
+        console.log(JSON.stringify({ ok: true, ...v }));
+        return;
+    }
+    for (const x of v.voices)
+        console.log(`${x.id.padEnd(13)} ${x.label}`);
+    console.log('');
+    for (const [tier, t] of Object.entries(v.tiers))
+        console.log(`${tier.padEnd(13)} ${t.creditsPer} (${t.engine})`);
+    console.log(`\nup to ${v.maxChars} characters per request`);
+}
+/**
+ * parley studio <character|shot|render|assemble|reels> …
+ * First-class Studio commands over the same API `parley api` reaches, so a
+ * person at a terminal gets the film pipeline without writing JSON:
+ *   studio character add --project P --name N --description D [--tags a,b] [--wardrobe W] [--voice V]
+ *   studio character cast <characterId> [--count 1] [--direction "…"] [--force]
+ *   studio character list --project P
+ *   studio shot add --project P --order N --framing "…" --directing "…" [--characters id,id] [--location id]
+ *                   [--duration 12] [--camera "arri-alexa-35, dolly-in"] [--line "characterId:text"]…
+ *   studio shot list --project P
+ *   studio render <shotId> [--force] [--wait]
+ *   studio assemble --project P --title T [--synopsis S] [--title-text X] [--music path] [--narration url]
+ *   studio reels --project P
+ */
+async function cmdStudio(p) {
+    const [group, action, target] = p.positionals;
+    const project = str(p.flags.project);
+    const needProject = () => {
+        if (!project || !/^proj_[A-Za-z0-9_-]{6,}$/.test(project))
+            throw new CliError('--project must be a Studio project id like proj_letter-7f3k (proj_ plus at least six letters, digits, _ or -).');
+        return project;
+    };
+    const out = (obj, human) => { if (JSON_MODE)
+        console.log(JSON.stringify(obj));
+    else
+        console.log(human()); };
+    if (group === 'character' && action === 'add') {
+        const P = needProject();
+        const name = str(p.flags.name);
+        const description = str(p.flags.description);
+        if (!name || !description)
+            throw new CliError('studio character add needs --name and --description (the identity lock: age, build, face, hair, skin, wardrobe).');
+        const body = { name, description };
+        const tags = list(p.flags.tags);
+        if (tags.length)
+            body.personalityTags = tags;
+        const wardrobe = str(p.flags.wardrobe);
+        if (wardrobe)
+            body.wardrobe = wardrobe;
+        const voice = str(p.flags.voice);
+        if (voice)
+            body.voiceId = voice;
+        const c = await api(`/api/studio/projects/${P}/characters`, { body });
+        return out({ ok: true, character: c }, () => `Character ${c.name} created: ${c.id}\nNext: parley studio character cast ${c.id}`);
+    }
+    if (group === 'character' && action === 'cast') {
+        if (!target)
+            throw new CliError('Usage: parley studio character cast <characterId> [--count 1] [--direction "…"] [--force]');
+        const body = { count: num(p.flags.count, 1) };
+        const direction = str(p.flags.direction);
+        if (direction)
+            body.additionalDirection = direction;
+        if (p.flags.force === true)
+            body.force = true;
+        note('Casting (renders the reference image)…');
+        const r = await api(`/api/studio/characters/${target}/cast`, { body });
+        const refs = r.character?.reference_image_paths || r.reference_image_paths || [];
+        return out({ ok: true, ...r }, () => `${r.skipped_reason ? r.skipped_reason + '\n' : ''}Reference images: ${refs.length ? refs.join(', ') : '(see JSON)'}`);
+    }
+    if (group === 'character' && action === 'list') {
+        const P = needProject();
+        const r = await api(`/api/studio/projects/${P}/characters`);
+        const items = Array.isArray(r) ? r : r.characters || [];
+        return out({ ok: true, characters: items }, () => items.map((c) => `${c.id}  ${c.name}  refs=${(c.reference_image_paths || []).length}`).join('\n') || '(no characters yet)');
+    }
+    if (group === 'shot' && action === 'add') {
+        const P = needProject();
+        const framing = str(p.flags.framing);
+        const directing = str(p.flags.directing);
+        if (!framing || !directing)
+            throw new CliError('studio shot add needs --framing (the still) and --directing (what happens, with the ending stated).');
+        const body = { orderIndex: num(p.flags.order, 0), framingPrompt: framing, directingPrompt: directing };
+        const chars = list(p.flags.characters);
+        if (chars.length)
+            body.characterIds = chars;
+        const location = str(p.flags.location);
+        if (location)
+            body.locationId = location;
+        const duration = str(p.flags.duration);
+        if (duration)
+            body.durationSeconds = Number(duration);
+        const camera = str(p.flags.camera);
+        if (camera)
+            body.cameraEmulation = camera;
+        const lines = list(p.flags.line).map((l) => { const i = l.indexOf(':'); if (i < 1)
+            throw new CliError('--line must be "characterId:text"'); return { characterId: l.slice(0, i).trim(), text: l.slice(i + 1).trim() }; });
+        if (lines.length)
+            body.dialogLines = lines;
+        const s = await api(`/api/studio/projects/${P}/shots`, { body });
+        return out({ ok: true, shot: s }, () => `Shot #${(s.order_index ?? 0) + 1} created: ${s.id}\nNext: parley studio render ${s.id} --wait`);
+    }
+    if (group === 'shot' && action === 'list') {
+        const P = needProject();
+        const r = await api(`/api/studio/projects/${P}/shots`);
+        const items = Array.isArray(r) ? r : r.shots || [];
+        return out({ ok: true, shots: items }, () => items.map((s) => `#${(s.order_index ?? 0) + 1}  ${s.id}  ${String(s.status).padEnd(9)} ${s.duration_seconds ?? '?'}s  ${s.camera_emulation || ''}${s.video_path ? '  clip ready' : ''}`).join('\n') || '(no shots yet)');
+    }
+    if (group === 'render') {
+        const shotId = action;
+        if (!shotId)
+            throw new CliError('Usage: parley studio render <shotId> [--force] [--wait]');
+        const body = {};
+        if (p.flags.force === true)
+            body.force = true;
+        note('Starting the render (a single multi-minute call)…');
+        const r = await api(`/api/studio/shots/${shotId}/render`, { body });
+        if (r.skipped_reason)
+            return out({ ok: true, ...r }, () => r.skipped_reason);
+        if (p.flags.wait !== true)
+            return out({ ok: true, ...r }, () => `Render started for ${shotId} (status ${r.status ?? 'running'}). Poll with: parley studio shot list --project ${r.project_id || '<project>'}`);
+        const P = r.project_id || project;
+        if (!P)
+            throw new CliError('Cannot wait without a project id; pass --project.');
+        const deadline = Date.now() + 45 * 60 * 1000;
+        const pollMs = Number(process.env.PARLEY_POLL_MS) || 30000;
+        let last = '';
+        while (Date.now() < deadline) {
+            await sleep(pollMs);
+            const shots = await api(`/api/studio/projects/${P}/shots`).then((x) => (Array.isArray(x) ? x : x.shots || []));
+            const s = shots.find((x) => x.id === shotId);
+            if (!s)
+                throw new CliError(`Shot ${shotId} disappeared from project ${P}.`);
+            if (s.status !== last) {
+                note(`  ${s.status}`);
+                last = s.status;
+            }
+            if (s.status === 'ready' && s.video_path)
+                return out({ ok: true, shot: s }, () => `Shot ${shotId} rendered: ${s.video_path}`);
+            if (s.status === 'failed')
+                throw new CliError(`Shot ${shotId} failed to render${s.error ? `: ${s.error}` : ''}.`);
+        }
+        throw new CliError('Timed out waiting for the render (45 minutes).');
+    }
+    if (group === 'assemble') {
+        const P = needProject();
+        const title = str(p.flags.title);
+        if (!title)
+            throw new CliError('studio assemble needs --title (and usually --synopsis).');
+        const body = { title };
+        const synopsis = str(p.flags.synopsis);
+        if (synopsis)
+            body.synopsis = synopsis;
+        const titleText = str(p.flags['title-text']);
+        if (titleText)
+            body.titleText = titleText;
+        const music = str(p.flags.music);
+        if (music)
+            body.musicPath = music;
+        const narration = str(p.flags.narration);
+        if (narration)
+            body.narrationUrl = resolveRef(narration, 'audio');
+        note('Assembling the reel (score generated and ducked automatically)…');
+        const reel = await api(`/api/studio/projects/${P}/assemble`, { body });
+        if (reel.public_url)
+            rememberLast('video', { file: reel.video_path || reel.public_url, url: reel.public_url });
+        return out({ ok: true, reel }, () => `Reel ${reel.id || ''}: ${reel.public_url || reel.video_path || '(see JSON)'}`);
+    }
+    if (group === 'reels') {
+        const P = needProject();
+        const r = await api(`/api/studio/projects/${P}/reels`);
+        const items = r.reels || (Array.isArray(r) ? r : []);
+        return out({ ok: true, reels: items }, () => items.map((x) => `${x.id}  ${x.public_url || x.video_path}`).join('\n') || '(no reels yet)');
+    }
+    throw new CliError('Usage: parley studio <character add|cast|list | shot add|list | render <shotId> | assemble | reels> … (see `parley help studio`)');
+}
 /**
  * parley api <GET|POST|PATCH|PUT|DELETE> <path> [--data '<json>' | --data @file.json]
  * Signed raw call to any Parley endpoint (the Studio's projects, characters,
@@ -413,11 +664,114 @@ async function cmdApi(p) {
     else
         console.log(JSON.stringify(r, null, 2));
 }
+/**
+ * parley doctor [--json]
+ * One call that tells an agent (or a person) exactly what state this machine
+ * is in and what to do next: Node version, whether the API is reachable,
+ * whether a session exists, the credit balance, which engines are live, and
+ * the last outputs available as @last. Exit 0 always; `ready` says whether a
+ * generation would succeed right now.
+ */
+async function cmdDoctor(p) {
+    const report = { cli: VERSION, node: process.version, backendUrl: backendUrl() };
+    const fixes = [];
+    const major = Number(process.version.replace(/^v/, '').split('.')[0]);
+    report.nodeOk = major >= 20;
+    if (!report.nodeOk)
+        fixes.push(`Node ${process.version} is too old: install Node 20 or newer.`);
+    // --require <version>: the skills declare the CLI they were written for.
+    // A CLI older than that is not "ready", whatever else is fine, so an agent
+    // never runs a skill against a CLI that lacks the commands the skill uses.
+    const required = str(p.flags.require);
+    if (required) {
+        report.required = required;
+        report.cliOk = compareVersions(VERSION, required) >= 0;
+        if (!report.cliOk)
+            fixes.push(`parley ${VERSION} is older than the ${required} these skills expect: run \`npm install -g parley-live@latest\` (or use \`npx -y parley-live@latest\`).`);
+    }
+    else {
+        report.cliOk = true;
+    }
+    // Best-effort "is there a newer release" check against the registry; never
+    // blocks, never fails the report (a sandbox without npm access just skips it).
+    // PARLEY_SKIP_UPDATE_CHECK=1 turns it off (tests, air-gapped CI).
+    if (process.env.PARLEY_SKIP_UPDATE_CHECK !== '1')
+        try {
+            const ctrl = new AbortController();
+            const t = setTimeout(() => ctrl.abort(), 3000);
+            const r = await fetch('https://registry.npmjs.org/parley-live/latest', { signal: ctrl.signal, headers: { Accept: 'application/json' } });
+            clearTimeout(t);
+            if (r.ok) {
+                const latest = (await r.json()).version;
+                if (latest) {
+                    report.latest = latest;
+                    if (compareVersions(latest, VERSION) > 0)
+                        report.update = `parley-live ${latest} is available (you have ${VERSION}): npm install -g parley-live@latest`;
+                }
+            }
+        }
+        catch { /* offline or blocked: fine */ }
+    try {
+        const e = await api('/video/engines', { auth: false });
+        report.reachable = true;
+        report.engines = Object.fromEntries(Object.entries(e.engines).map(([k, v]) => [k, { ready: v.ready, creditsPerSec: v.creditsPerSec ?? null, fallback: v.fallback ?? null }]));
+        report.cameraMoves = Array.isArray(e.cameraMoves) ? e.cameraMoves.length : 0;
+    }
+    catch (e) {
+        report.reachable = false;
+        fixes.push(`Cannot reach ${backendUrl()} (${e?.message || e}). Check the network, or set PARLEY_BACKEND_URL if you use a different server.`);
+    }
+    const creds = loadCredentials();
+    report.signedIn = false;
+    if (!creds && !process.env.PARLEY_TOKEN) {
+        fixes.push('Not signed in: run `parley login` (or `parley login --no-browser` and open the printed link). In CI or a cloud sandbox, set PARLEY_TOKEN instead.');
+    }
+    else if (report.reachable) {
+        try {
+            const bal = await api('/api/credits/balance');
+            report.signedIn = true;
+            report.email = creds?.email ?? null;
+            report.credits = bal.credits_balance;
+            if (bal.credits_balance <= 0)
+                fixes.push('Credit balance is 0: top up at https://labs.parley.live before generating.');
+        }
+        catch (e) {
+            if (e instanceof CliError && e.exitCode === 2)
+                fixes.push('The stored session is no longer valid: run `parley login` again.');
+            else
+                fixes.push(`Could not read the balance: ${e?.message || e}`);
+        }
+    }
+    const last = loadLast();
+    report.last = { image: last.image?.url ?? last.image?.file ?? null, video: last.video?.url ?? last.video?.file ?? null, audio: last.audio?.url ?? last.audio?.file ?? null };
+    report.ready = report.nodeOk === true && report.cliOk === true && report.reachable === true && report.signedIn === true && (typeof report.credits !== 'number' || report.credits > 0);
+    report.fixes = fixes;
+    if (JSON_MODE) {
+        console.log(JSON.stringify({ ok: true, ...report }));
+        return;
+    }
+    console.log(`parley ${VERSION} on Node ${process.version}${report.nodeOk ? '' : '  (too old)'}${report.update ? `  (update: ${report.latest})` : ''}${required ? `  (skills expect ${required}: ${report.cliOk ? 'ok' : 'TOO OLD'})` : ''}`);
+    console.log(`server    ${report.backendUrl}  ${report.reachable ? 'reachable' : 'UNREACHABLE'}`);
+    console.log(`session   ${report.signedIn ? `signed in as ${report.email || 'user'}, ${report.credits} credits` : 'not signed in'}`);
+    if (report.engines) {
+        const live = Object.entries(report.engines).filter(([, v]) => v.ready).map(([k]) => k);
+        console.log(`engines   ${live.join(', ')}  (${report.cameraMoves} camera moves)`);
+    }
+    if (report.last && (report.last.image || report.last.video || report.last.audio))
+        console.log(`last      image=${report.last.image || '-'}  video=${report.last.video || '-'}  audio=${report.last.audio || '-'}`);
+    console.log(`ready     ${report.ready ? 'yes' : 'no'}`);
+    for (const f of fixes)
+        console.log(`  fix: ${f}`);
+}
 function help(topic) {
     const lines = {
-        login: 'parley login [--backend URL]\n  Sign in once in your browser. Stores a session token under ~/.parley (or $PARLEY_HOME).',
-        image: 'parley image "<prompt>" [--model gpt-image-2|gemini-3-pro-image-preview] [--size 1024x1024|1024x1536|1536x1024] [--quality low|medium|high] [--image-size 1K|2K|4K] [--ref <file|url>]... [--out file]\n  Generate an image. --ref passes reference images (identity / style locks).',
-        video: `parley video "<motion prompt>" --image <file|url> [--look ${LOOKS.join('|')}] [--move <slug>]... [--duration 5] [--ratio 16:9|9:16|1:1] [--out clip.mp4]\n  Animate a still (or --look photoreal for text-to-video). --move adds named camera moves; see \`parley camera-moves\`.`,
+        doctor: 'parley doctor [--require <version>] [--json]\n  Node, server, session, credits, live engines, the @last outputs and whether a newer release exists, with the fix for anything missing. --require fails "ready" when this CLI is older than what your skills expect. Run this first.',
+        voice: `parley voice "<text>" | --file script.txt [--voice ${VOICES.join('|')}] [--quality ${VOICE_TIERS.join('|')}] [--no-fallback] [--out narration.wav]\n  Narration as a hosted WAV (natural voice 1 credit per 1,000 characters; studio 1 per 300). Becomes @last for --narration.`,
+        voices: 'parley voices\n  The narration personas, the tiers and their prices.',
+        studio: 'parley studio character add|cast|list · shot add|list · render <shotId> [--wait] · assemble · reels\n  The film pipeline without JSON: cast characters (identity lock), write shots ("lens look, move" camera), render, assemble a reel. Every subcommand takes --project proj_… and --json.',
+        login: 'parley login [--no-browser] [--backend URL]\n  Sign in once in your browser. --no-browser prints the link instead of opening it (cloud sandboxes, SSH). Stores a session token under ~/.parley (or $PARLEY_HOME).',
+        image: `parley image "<prompt>" [--ratio ${Object.keys(RATIO_TO_SIZE).join('|')}] [--model gpt-image-2|gemini-3-pro-image-preview] [--quality low|medium|high] [--image-size 1K|2K|4K] [--ref <file|url|@last>]... [--out file]\n  Generate an image. --ratio sizes it for the destination; --ref passes reference images (identity / style locks).`,
+        video: `parley video "<motion prompt>" --image <file|url|@last> [--look ${LOOKS.join('|')}] [--move <slug>]... [--duration 5] [--ratio 16:9|9:16|1:1] [--out clip.mp4]\n  Animate a still (@last = the image you just made) or --look photoreal for text-to-video. --move adds named camera moves; see \`parley camera-moves\`.`,
         thumbnail: 'parley thumbnail "<video title>" [--variants 1-3] [--overlay "2-4 WORDS"] [--accent WORD] [--person true|false] [--out dir]',
         'ugc-ad': `parley ugc-ad --product <image> --name "Product" [--actor maya|jordan|sofia|marcus | --face <image>] [--angle ${ANGLES.join('|')}] [--marketplace ${MARKETPLACES.join('|')}] [--points "a;b;c"] [--seconds 3-16] [--url https://...] [--out ad.mp4]`,
         youtube: `parley youtube --beat <https still>... [--narration <https audio>] [--music <https audio>] [--tier ${YT_TIERS.join('|')}] [--captions] [--silent] [--project <workspace id>] [--out video.mp4]\n  Animate ordered beat stills and cut them to the narration into one finished video.`,
@@ -444,6 +798,20 @@ async function main(argv) {
             case 'login':
                 await cmdLogin(p);
                 break;
+            case 'doctor':
+            case 'status':
+                await cmdDoctor(p);
+                break;
+            case 'voice':
+            case 'narrate':
+                await cmdVoice(p);
+                break;
+            case 'voices':
+                await cmdVoices();
+                break;
+            case 'studio':
+                await cmdStudio(p);
+                break;
             case 'logout':
                 await cmdLogout();
                 break;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "parley-live",
-  "version": "0.1.0",
-  "description": "Generate images, video clips, YouTube thumbnails and product ads from the terminal with Parley. Built for coding agents: every command has a --json mode.",
+  "version": "0.3.0",
+  "description": "Generate images, video clips with named camera moves, narration, YouTube thumbnails, product ads, complete videos and Studio films from the terminal with Parley. Built for coding agents: every command has a --json mode.",
   "license": "MIT",
   "type": "module",
   "bin": {