parley-live 0.1.0 → 0.2.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,13 @@ 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` | Node, server, session, credits, live engines, the `@last` outputs, and the fix for anything missing. Run it first; `--json` for agents. |
+| `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 +42,16 @@ 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
+```
+
 ## For agents
 
 Add `--json` to any command and read the last line of stdout:
@@ -51,7 +62,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,8 @@
  */
 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.2.0';
 function parseArgs(argv) {
     const out = { command: '', positionals: [], flags: {} };
     const rest = [...argv];
@@ -72,6 +72,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 +144,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 +189,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 +207,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 +246,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) {
@@ -413,11 +434,79 @@ 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() {
+    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.`);
+    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 };
+    report.ready = report.nodeOk === 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(`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 || '-'}`);
+    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 [--json]\n  Node, server, session, credits, live engines and the @last outputs, with the fix for anything missing. Run this first.',
+        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 +533,10 @@ async function main(argv) {
             case 'login':
                 await cmdLogin(p);
                 break;
+            case 'doctor':
+            case 'status':
+                await cmdDoctor();
+                break;
             case 'logout':
                 await cmdLogout();
                 break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "parley-live",
-  "version": "0.1.0",
+  "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.",
   "license": "MIT",
   "type": "module",