parley-live 0.2.0 → 0.4.0

package/README.md

@@ -16,7 +16,10 @@ parley ugc-ad --product product.jpg --name "Cold Brew Kit" --actor jordan --mark
 
 | Command | What it does |
 |---|---|
-| `parley doctor` | Node, server, session, credits, live engines, the `@last` outputs, and the fix for anything missing. Run it first; `--json` for agents. |
+| `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`, `location add\|cast\|list`, `shot add\|list`, `render <shotId> [--wait]`, `assemble`, `reels`. Every subcommand takes `--project proj_…`. |
+| `parley deploy <dir> --name <slug>` | Ship a built static site (index.html at the root) to a live URL. Reuse `--project proj_…` to redeploy the same site at the same URL. Free. |
 | `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. |
@@ -50,6 +53,20 @@ The CLI remembers the last image and the last clip it made (`~/.parley/last.json
 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

package/dist/index.js

@@ -14,10 +14,20 @@
  *
  * Run `parley help <command>` for the flags of one command.
  */
-import { readFileSync, existsSync, mkdirSync } from 'node:fs';
+import { readFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { api, authWebUrl, backendUrl, clearCredentials, CliError, downloadTo, fileToDataUri, isUrl, loadCredentials, loadLast, openInBrowser, rememberLast, resolveRef, saveCredentials, sleep, } from './client.js';
-const VERSION = '0.2.0';
+const VERSION = '0.4.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];
@@ -362,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 })),
@@ -406,6 +420,420 @@ 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.
+ */
+const VOICE_MAX_CHARS = 5000;
+const VOICE_SPLIT_TARGET = 4500;
+/**
+ * Split a long narration into sections of at most `max` characters, cutting
+ * at paragraph breaks first, then sentence ends, then (last resort) spaces,
+ * so a section never ends mid-word and rarely mid-sentence.
+ */
+export function splitNarration(text, max = VOICE_SPLIT_TARGET) {
+    const clean = text.replace(/\r\n/g, '\n').trim();
+    if (clean.length <= max)
+        return [clean];
+    const sections = [];
+    let current = '';
+    const push = () => { if (current.trim())
+        sections.push(current.trim()); current = ''; };
+    const units = clean.split(/\n\s*\n/).flatMap((para) => {
+        if (para.length <= max)
+            return [para];
+        const sentences = para.match(/[^.!?]+[.!?]+["')\]]*\s*|[^.!?]+$/g) || [para];
+        return sentences.flatMap((s) => {
+            if (s.length <= max)
+                return [s];
+            const words = s.split(/\s+/);
+            const chunks = [];
+            let w = '';
+            for (const word of words) {
+                if ((w + ' ' + word).trim().length > max) {
+                    chunks.push(w.trim());
+                    w = word;
+                }
+                else
+                    w = (w + ' ' + word).trim();
+            }
+            if (w)
+                chunks.push(w);
+            return chunks;
+        });
+    });
+    for (const unit of units) {
+        const sep = current && /\n\s*\n/.test(clean.slice(clean.indexOf(unit) - 3, clean.indexOf(unit))) ? '\n\n' : ' ';
+        if ((current + sep + unit).trim().length > max)
+            push();
+        current = current ? `${current}${sep}${unit}` : unit;
+    }
+    push();
+    return sections;
+}
+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('|')}] [--split] [--no-fallback] [--out narration.wav]`);
+    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 split = p.flags.split === true || text.length > VOICE_MAX_CHARS;
+    if (text.length > VOICE_MAX_CHARS && p.flags.split !== true) {
+        note(`The text is ${text.length} characters (over one request's ${VOICE_MAX_CHARS}); splitting into sections and joining them into one narration.`);
+    }
+    const sections = split ? splitNarration(text) : [text];
+    const common = { quality, ...(voice ? { voice } : {}), ...(p.flags['no-fallback'] === true ? { allowFallback: false } : {}) };
+    const parts = [];
+    for (let i = 0; i < sections.length; i++) {
+        note(sections.length > 1
+            ? `Narrating section ${i + 1}/${sections.length} (${sections[i].length} characters) with the ${quality} voice${voice ? ` (${voice})` : ''}…`
+            : `Narrating ${sections[i].length} characters with the ${quality} voice${voice ? ` (${voice})` : ''}…`);
+        parts.push(await api('/api/voice/generate', { body: { text: sections[i], ...common } }));
+    }
+    let finalUrl = parts[0].audioUrl;
+    let durationSeconds = parts[0].durationSeconds;
+    if (parts.length > 1) {
+        note(`Joining ${parts.length} sections into one narration…`);
+        const j = await api('/api/voice/join', { body: { urls: parts.map((x) => x.audioUrl) } });
+        finalUrl = j.audioUrl;
+        durationSeconds = j.durationSeconds;
+    }
+    const out = outPathFor(p, `parley-voice-${Date.now()}.wav`);
+    const bytes = await downloadTo(finalUrl, out);
+    rememberLast('audio', { file: out, url: finalUrl });
+    const warnings = parts.map((x) => x.voiceWarning).filter((w) => !!w);
+    if (warnings.length)
+        console.error(`warning: ${warnings[0]}${warnings.length > 1 ? ` (${warnings.length} sections)` : ''}`);
+    const creditsCharged = parts.reduce((s, x) => s + (x.creditsCharged || 0), 0);
+    const engines = [...new Set(parts.map((x) => x.engine))].join('+');
+    emit({ ok: true, file: out, bytes, audioUrl: finalUrl, durationSeconds, engine: engines, voice: parts[0].voice, creditsCharged, sections: parts.length, sectionUrls: parts.map((x) => x.audioUrl), voiceWarning: warnings[0] ?? null }, `Saved ${out} (${durationSeconds ?? '?'}s, ${engines}, ${creditsCharged} credits${parts.length > 1 ? `, ${parts.length} sections joined` : ''})\nHosted: ${finalUrl}`);
+}
+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 === 'location' && action === 'add') {
+        const P = needProject();
+        const name = str(p.flags.name);
+        const description = str(p.flags.description);
+        if (!name || !description)
+            throw new CliError('studio location add needs --name and --description (the place, time of day, light, the props that identify it).');
+        const l = await api(`/api/studio/projects/${P}/locations`, { body: { name, description } });
+        return out({ ok: true, location: l }, () => `Location ${l.name} created: ${l.id}\nNext: parley studio location cast ${l.id}`);
+    }
+    if (group === 'location' && action === 'cast') {
+        if (!target)
+            throw new CliError('Usage: parley studio location cast <locationId> [--count 1] [--force]');
+        const body = { count: num(p.flags.count, 1) };
+        if (p.flags.force === true)
+            body.force = true;
+        note('Casting the location (renders its reference image)…');
+        const r = await api(`/api/studio/locations/${target}/cast`, { body });
+        const refs = r.location?.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 === 'location' && action === 'list') {
+        const P = needProject();
+        const r = await api(`/api/studio/projects/${P}/locations`);
+        const items = Array.isArray(r) ? r : r.locations || [];
+        return out({ ok: true, locations: items }, () => items.map((l) => `${l.id}  ${l.name}  refs=${(l.reference_image_paths || []).length}`).join('\n') || '(no locations 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 | location add|cast|list | shot add|list | render <shotId> | assemble | reels> … (see `parley help studio`)');
+}
+const DEPLOY_MAX_FILES = 600;
+const DEPLOY_MAX_TOTAL_BYTES = 40 * 1024 * 1024;
+const DEPLOY_SKIP_DIRS = new Set(['node_modules', '.git', '.svn', '.hg', '.parley', '.cache', '.next', '.nuxt', '.turbo', 'coverage']);
+const TEXT_EXT = new Set(['html', 'htm', 'css', 'js', 'mjs', 'cjs', 'map', 'json', 'txt', 'md', 'svg', 'xml', 'webmanifest', 'txt', 'csv', 'ics', 'rss', 'atom', 'yml', 'yaml', 'toml', 'wasm.txt']);
+const MIME = {
+    html: 'text/html', htm: 'text/html', css: 'text/css', js: 'text/javascript', mjs: 'text/javascript', cjs: 'text/javascript', map: 'application/json',
+    json: 'application/json', txt: 'text/plain', md: 'text/markdown', svg: 'image/svg+xml', xml: 'application/xml', webmanifest: 'application/manifest+json',
+    png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp', avif: 'image/avif', ico: 'image/x-icon',
+    mp4: 'video/mp4', webm: 'video/webm', mp3: 'audio/mpeg', wav: 'audio/wav', ogg: 'audio/ogg',
+    woff: 'font/woff', woff2: 'font/woff2', ttf: 'font/ttf', otf: 'font/otf', pdf: 'application/pdf', wasm: 'application/wasm', glb: 'model/gltf-binary',
+};
+function walkDir(root, rel = '') {
+    const out = [];
+    for (const entry of readdirSync(path.join(root, rel), { withFileTypes: true })) {
+        if (entry.name.startsWith('.DS_Store'))
+            continue;
+        const r = rel ? `${rel}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            if (!DEPLOY_SKIP_DIRS.has(entry.name))
+                out.push(...walkDir(root, r));
+        }
+        else if (entry.isFile())
+            out.push(r);
+    }
+    return out;
+}
+/**
+ * parley deploy <dir> --name <project> [--project proj_…] [--summary "…"]
+ * Ships a built static site (the folder with index.html at its root) to
+ * Parley's Cloudflare Pages deploy: every file is written into a fresh
+ * workspace (text as text, binaries base64), then deployed. Prints the live
+ * URL. Static only: the server's deploy is a direct upload with no build
+ * step, so run your build first and point this at its output.
+ */
+async function cmdDeploy(p) {
+    const dir = p.positionals[0];
+    const name = str(p.flags.name);
+    if (!dir || !name)
+        throw new CliError('Usage: parley deploy <built-site-dir> --name <project-name> [--project proj_…] [--summary "…"]\n  The dir must contain index.html at its root (run your build first).');
+    const root = path.resolve(dir);
+    if (!existsSync(root) || !statSync(root).isDirectory())
+        throw new CliError(`Not a directory: ${dir}`);
+    if (!existsSync(path.join(root, 'index.html')))
+        throw new CliError(`No index.html at the root of ${dir}. Point deploy at the BUILT output (dist/, build/, out/, _site/), not the source.`);
+    if (!/[a-z0-9]/i.test(name))
+        throw new CliError('--name must contain at least one letter or digit.');
+    const files = walkDir(root);
+    if (files.length === 0)
+        throw new CliError('The directory is empty.');
+    if (files.length > DEPLOY_MAX_FILES)
+        throw new CliError(`${files.length} files is over the ${DEPLOY_MAX_FILES}-file limit; deploy the built output only.`);
+    let total = 0;
+    for (const f of files)
+        total += statSync(path.join(root, f)).size;
+    if (total > DEPLOY_MAX_TOTAL_BYTES)
+        throw new CliError(`${Math.round(total / 1048576)} MB is over the ${DEPLOY_MAX_TOTAL_BYTES / 1048576} MB limit. Move large media to Parley-hosted URLs (parley image / video print them) and reference them instead of shipping them.`);
+    const project = str(p.flags.project) || `proj_site-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+    if (!/^proj_[A-Za-z0-9_-]{6,}$/.test(project))
+        throw new CliError('--project must look like proj_ followed by at least six letters, digits, _ or -.');
+    note(`Uploading ${files.length} files (${Math.round(total / 1024)} KB) into workspace ${project}…`);
+    let n = 0;
+    for (const f of files) {
+        const abs = path.join(root, f);
+        const ext = path.extname(f).slice(1).toLowerCase();
+        const mimeType = MIME[ext] || (TEXT_EXT.has(ext) ? 'text/plain' : 'application/octet-stream');
+        const isText = TEXT_EXT.has(ext) || mimeType.startsWith('text/');
+        const buf = readFileSync(abs);
+        await api(`/api/workspace/${project}/files`, {
+            body: { path: f.replace(/\\/g, '/'), content: isText ? buf.toString('utf8') : buf.toString('base64'), mimeType, isBase64: !isText, allowFullRewrite: true },
+        });
+        n++;
+        if (n % 25 === 0)
+            note(`  ${n}/${files.length}`);
+    }
+    note('Deploying…');
+    const summary = str(p.flags.summary);
+    const d = await api('/api/deploy-project', { body: { workspaceId: project, projectName: name, ...(summary ? { summary } : {}) } });
+    let url = d.url;
+    let deploymentId = d.deploymentId;
+    if (!url && d.jobId) {
+        // Asynchronous variant: poll the job until it reports a URL.
+        const deadline = Date.now() + 20 * 60 * 1000;
+        const pollMs = Number(process.env.PARLEY_POLL_MS) || 4000;
+        let last = '';
+        while (Date.now() < deadline) {
+            await sleep(pollMs);
+            const j = await api(`/api/deploy-project/jobs/${d.jobId}`);
+            const stage = j.progress?.stage || j.stage || j.status;
+            if (stage !== last) {
+                note(`  ${stage}${j.progress?.message ? ` – ${j.progress.message}` : ''}`);
+                last = stage;
+            }
+            if (j.status === 'failed' || j.ok === false)
+                throw new CliError(j.error || j.message || 'Deploy failed.');
+            url = j.url || j.result?.url;
+            deploymentId = j.deploymentId || j.result?.deploymentId;
+            if (url && (j.status === 'succeeded' || j.status === 'done' || j.status === 'complete' || j.stage === 'done'))
+                break;
+            if (url && !j.status)
+                break;
+        }
+    }
+    if (!url)
+        throw new CliError(`Deploy did not return a URL: ${JSON.stringify(d).slice(0, 200)}`);
+    emit({ ok: true, url, projectName: name, workspaceId: project, deploymentId: deploymentId ?? null, files: files.length, bytes: total }, `Live: ${url}\nWorkspace ${project} (${files.length} files). Redeploy the same site with --project ${project}.`);
+}
 /**
  * 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,
@@ -442,13 +870,45 @@ async function cmdApi(p) {
  * the last outputs available as @last. Exit 0 always; `ready` says whether a
  * generation would succeed right now.
  */
-async function cmdDoctor() {
+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;
@@ -481,35 +941,39 @@ async function cmdDoctor() {
         }
     }
     const last = loadLast();
-    report.last = { image: last.image?.url ?? last.image?.file ?? null, video: last.video?.url ?? last.video?.file ?? null };
-    report.ready = report.nodeOk === true && report.reachable === true && report.signedIn === true && (typeof report.credits !== 'number' || report.credits > 0);
+    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)'}`);
+    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))
-        console.log(`last      image=${report.last.image || '-'}  video=${report.last.video || '-'}`);
+    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 = {
-        doctor: 'parley doctor [--json]\n  Node, server, session, credits, live engines and the @last outputs, with the fix for anything missing. Run this first.',
+        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('|')}] [--split] [--no-fallback] [--out narration.wav]\n  Narration as a hosted WAV (natural voice 1 credit per 1,000 characters; studio 1 per 300). Text over 5,000 characters is split at paragraph and sentence breaks and joined back into one narration. Becomes @last for --narration.`,
+        voices: 'parley voices\n  The narration personas, the tiers and their prices.',
+        studio: 'parley studio character add|cast|list · location add|cast|list · shot add|list · render <shotId> [--wait] · assemble · reels\n  The film pipeline without JSON: cast characters and locations (identity locks), 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.`,
+        deploy: 'parley deploy <built-site-dir> --name <project-name> [--project proj_…] [--summary "…"]\n  Ship a built static site (index.html at the root) to a live URL on Parley\'s hosting. Reuse --project to redeploy the same site.',
         api: 'parley api <GET|POST|PATCH|PUT|DELETE> </path> [--data \'{...}\' | --data @file.json]\n  Signed raw call to any Parley endpoint (Studio projects, characters, shots, renders, reels).',
         engines: 'parley engines\n  Which video engines this server can run right now and their credit rates.',
         'camera-moves': 'parley camera-moves\n  The named camera-move presets accepted by `parley video --move`.',
@@ -535,7 +999,17 @@ async function main(argv) {
                 break;
             case 'doctor':
             case 'status':
-                await cmdDoctor();
+                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();
@@ -574,6 +1048,9 @@ async function main(argv) {
             case 'api':
                 await cmdApi(p);
                 break;
+            case 'deploy':
+                await cmdDeploy(p);
+                break;
             case 'help':
             case '--help':
             case '-h':

package/package.json

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