reelforge 0.3.1 → 0.3.2

package/README.md

@@ -14,37 +14,43 @@ Or use directly without install:
 npx reelforge <command>
 ```
 
-After install, two binaries are on your `PATH` — `reelforge` and the short alias `rf`. Both behave identically:
+After install, two binaries are on your `PATH` — `reelforge` and the short alias `rf`. Both behave identically; the docs use `rf` from here on.
 
 ```bash
 rf --version            # same as `reelforge --version`
-rf create "..." -o out.mp4
 ```
 
 ## Quick start
 
-`reelforge` ships pointing at the hosted instance (`https://reelforge.timor419.com`). Get an activation code from the admin, log in once, and call:
+The CLI ships pointing at the hosted instance (`https://reelforge.timor419.com`). Log in once, then call:
 
 ```bash
 npm install -g reelforge
-reelforge login                                # opens browser, picks up token automatically
-reelforge whoami                               # balance + api_keys
-reelforge create "为什么我们还没找到外星文明？" -o space.mp4
-# or the short alias:
-rf create "为什么我们还没找到外星文明？" -o space.mp4
+rf login                                       # opens browser; headless? rf login <api_key>
+rf whoami                                      # balance + api_keys
+rf create "为什么我们还没找到外星文明？"          # auto-saves to ./<title>-<id>.mp4 in cwd
 ```
 
 That's the whole story — no server to run.
 
+### Output behavior
+
+| invocation | result |
+|---|---|
+| `rf create "..."` | Saves to `./<sanitized-title>-<task_id_short>.mp4`, prints the path |
+| `rf create "..." -o ./videos/space.mp4` | Saves to that exact path (must include filename, not just a directory) |
+| `rf create "..." --no-download` | Skips local save, prints JSON result with `video_url` |
+| `rf create "..." \| jq .video_url` | When stdout is piped, download is skipped automatically |
+
 ### Self-hosting
 
 If you want to run your own ReelForge Studio (own LLM / RunningHub keys, your own pricing) clone the upstream repo, `pnpm dev`, then point the CLI at it:
 
 ```bash
-reelforge --server http://localhost:8501 health
+rf --server http://localhost:8501 health
 # or persist:
 export REELFORGE_SERVER=http://localhost:8501
-# or via `reelforge login <key> --server http://localhost:8501`
+# or via `rf login <key> --server http://localhost:8501`
 ```
 
 ## Global options
@@ -60,7 +66,7 @@ export REELFORGE_SERVER=http://localhost:8501
 
 ## Command map
 
-Run `reelforge <command> --help` for full details on any of these.
+Run `rf <command> --help` for full details on any of these.
 
 ### Core capabilities
 
@@ -100,7 +106,7 @@ Run `reelforge <command> --help` for full details on any of these.
 
 ### End-to-end pipelines
 
-All `pipelines *` commands submit an **async task** and (by default) poll until it finishes with a live progress indicator on stderr. Use `--no-wait` to return immediately with a `task_id`, then `reelforge tasks wait <id>` later.
+All `pipelines *` commands submit an **async task** and (by default) poll until it finishes with a live progress indicator on stderr. Use `--no-wait` to return immediately with a `task_id`, then `rf tasks wait <id>` later.
 
 | command | what it does |
 |---|---|
@@ -133,25 +139,28 @@ All `pipelines *` commands submit an **async task** and (by default) poll until
 ## Examples
 
 ```bash
-# 1. End-to-end "text → video" with zero external APIs (Edge TTS + static template)
-reelforge pipelines standard \
+# 1. One-click out a video (auto-saves to ./<title>-<id>.mp4 in cwd)
+rf create "为什么我们还没找到外星文明？"
+
+# 2. Same, but with a fixed script and explicit output path
+rf pipelines standard \
   -t "Hello world. This is scene one.\n\nThis is scene two." \
   --mode fixed --title "Smoke Test" \
   --frame-template 1080x1920/static_default.html \
   --tts-voice en-US-AriaNeural -o smoke.mp4
 
-# 2. Inspect existing tasks & redownload a finished video
-reelforge tasks list --limit 5
-reelforge history get <task-id> --download recovered.mp4
+# 3. Inspect existing tasks & redownload a finished video
+rf tasks list --limit 5
+rf history get <task-id> --download recovered.mp4
 
-# 3. JSON pipe for automation
-reelforge workflows list --kind image --json | jq '.workflows[].key'
+# 4. JSON pipe for automation
+rf workflows list --kind image --json | jq '.workflows[].key'
 
-# 4. Configure & test LLM
-reelforge config set llm.api_key sk-xxxxx
-reelforge config set llm.base_url https://dashscope.aliyuncs.com/compatible-mode/v1
-reelforge config set llm.model qwen-plus
-reelforge llm chat -p 'one-sentence summary of antifragile'
+# 5. Configure & test LLM (self-hosted)
+rf config set llm.api_key sk-xxxxx
+rf config set llm.base_url https://dashscope.aliyuncs.com/compatible-mode/v1
+rf config set llm.model qwen-plus
+rf llm chat -p 'one-sentence summary of antifragile'
 ```
 
 ## Tip — getting unstuck
@@ -159,23 +168,10 @@ reelforge llm chat -p 'one-sentence summary of antifragile'
 Every level has `--help`:
 
 ```bash
-reelforge --help                     # top-level overview
-reelforge pipelines --help           # list of pipelines
-reelforge pipelines standard --help  # full option reference
-reelforge tts edge --help            # one specific command
-```
-
-## Development & publishing
-
-```bash
-cd cli
-npm install
-npm run build
-npm link                           # makes `reelforge` available globally for testing
-reelforge health                     # try it out
-
-# Publish to npm
-npm publish --access public
+rf --help                     # top-level overview
+rf pipelines --help           # list of pipelines
+rf pipelines standard --help  # full option reference
+rf tts edge --help            # one specific command
 ```
 
 ## License

package/dist/commands/create.js

@@ -82,6 +82,63 @@ async function saveLastCreate(body) {
     await fs.mkdir(path.dirname(LAST_CREATE_PATH), { recursive: true });
     await fs.writeFile(LAST_CREATE_PATH, JSON.stringify(body, null, 2) + "\n", "utf-8");
 }
+// ── Filename derivation ─────────────────────────────────────────
+//
+// Cascade (highest → lowest):
+//   1. result.title              — server's actual video title (LLM or explicit)
+//   2. body.title                — user-supplied --title (pre-task fallback)
+//   3. raw topic (mode=generate, length ≤ 60, no @-prefix)
+//   4. @file stem                — when text was loaded from @./script.txt
+//   5. "reelforge" literal
+// Always suffixed with "-<task_id[:8]>" to avoid collisions.
+const FILENAME_MAX_CHARS = 40;
+function sanitizeFilename(name) {
+    const cleaned = name
+        .replace(/[\/\\:*?"<>|\r\n\t]+/g, "-")
+        .replace(/\s+/g, " ")
+        .trim()
+        .replace(/^[-.\s]+|[-.\s]+$/g, "");
+    const chars = Array.from(cleaned);
+    if (chars.length <= FILENAME_MAX_CHARS)
+        return cleaned;
+    return chars.slice(0, FILENAME_MAX_CHARS).join("").replace(/[-.\s]+$/g, "");
+}
+function computeDefaultFilename(args) {
+    const ext = args.ext || "mp4";
+    const shortId = args.taskId.slice(0, 8);
+    let base;
+    if (args.resultTitle && args.resultTitle.trim()) {
+        base = sanitizeFilename(args.resultTitle);
+    }
+    else if (args.bodyTitle && args.bodyTitle.trim()) {
+        base = sanitizeFilename(args.bodyTitle);
+    }
+    else if (args.mode === "generate" &&
+        args.rawTextInput &&
+        !args.rawTextInput.startsWith("@") &&
+        Array.from(args.rawTextInput).length <= 60) {
+        base = sanitizeFilename(args.rawTextInput);
+    }
+    else if (args.fileStemFromAt) {
+        base = sanitizeFilename(args.fileStemFromAt);
+    }
+    return `${base || "reelforge"}-${shortId}.${ext}`;
+}
+async function validateOutputPath(out) {
+    if (out.endsWith("/") || out.endsWith("\\")) {
+        throw new Error(`-o must include a filename (got directory-only path: ${out}). Example: -o ./videos/space.mp4`);
+    }
+    try {
+        const stat = await fs.stat(out);
+        if (stat.isDirectory()) {
+            throw new Error(`-o must include a filename (path exists as a directory: ${out}). Example: -o ${out.replace(/[\\/]+$/, "")}/space.mp4`);
+        }
+    }
+    catch (e) {
+        if (e.code !== "ENOENT")
+            throw e;
+    }
+}
 /** Camel-case CLI options → snake_case body, only including provided fields */
 function optsToBody(opts) {
     const out = {};
@@ -186,7 +243,8 @@ export function registerCreate(program) {
         .option("--redo", "replay last successful create from ~/.reelforge/last-create.json")
         .option("--dry-run", "print the final request body + estimated units; do NOT submit")
         .option("--no-wait", "submit and return task_id immediately (do not poll)")
-        .option("-o, --output <file>", "save the final video to this path (only when waiting)")
+        .option("-o, --output <file>", "save the final video to this exact path (must include filename, e.g. ./out/space.mp4). Default: auto-named file in current directory.")
+        .option("--no-download", "do not save the video locally — just print the JSON result with video_url")
         .option("--poll-ms <ms>", "poll interval while waiting", (v) => parseInt(v, 10), 1500)
         .option("--timeout-ms <ms>", "max wait time before aborting (default unlimited)", (v) => parseInt(v, 10))
         .addHelpText("after", [
@@ -200,9 +258,15 @@ export function registerCreate(program) {
         "  Visual  : --frame-template --media-workflow --prompt-prefix",
         "  TTS     : --tts-voice --tts-speed --tts-inference-mode --tts-workflow --voice-id --ref-audio",
         "  BGM     : --bgm --bgm-volume --bgm-mode",
-        "  Output  : --video-fps --template-params -o --no-wait --poll-ms --timeout-ms",
+        "  Output  : --video-fps --template-params -o --no-download --no-wait --poll-ms --timeout-ms",
         "  Workflow: --recipe --redo --dry-run",
         "",
+        "Output behavior:",
+        "  No flag     → saves to ./<title>-<task_id>.mp4 in current directory, prints the path",
+        "  -o <path>   → saves to that exact path (must include filename, not just a directory)",
+        "  --no-download → skips local save, just prints JSON result with video_url",
+        "  (when stdout is piped, --no-download is implied automatically)",
+        "",
         "Explore available resources (separate commands):",
         "  reelforge templates list                  # all HTML templates",
         "  reelforge workflows list --kind image     # all AI image workflows",
@@ -210,41 +274,47 @@ export function registerCreate(program) {
         "  reelforge tts voices --locale zh          # Edge TTS voice ids",
         "  reelforge bgm list                        # built-in BGM files",
         "",
-        "Examples:",
-        "  # Minimum — defaults out 5 scenes, image background, Yunjian voice",
-        '  reelforge create "为什么我们还没找到外星文明？"',
+        "Examples (`rf` is a short alias for `reelforge`):",
+        "  # Minimum — saves to ./<title>-<short_id>.mp4 in cwd",
+        '  rf create "为什么我们还没找到外星文明？"',
+        "",
+        "  # Pick the exact output path",
+        '  rf create "..." -o ./videos/space.mp4',
         "",
         "  # Long script from a file, fixed mode (no LLM scriptwriting)",
-        "  reelforge create @./script.txt --mode fixed --split-mode paragraph",
+        "  rf create @./script.txt --mode fixed --split-mode paragraph",
         "",
         "  # Landscape (1920x1080)",
-        '  reelforge create "..." --frame-template 1920x1080/image_default.html',
+        '  rf create "..." --frame-template 1920x1080/image_default.html',
         "",
         "  # AI-generated video background instead of still image",
-        '  reelforge create "..." \\',
+        '  rf create "..." \\',
         "    --frame-template 1080x1920/video_default.html \\",
         "    --media-workflow runninghub/video_wan2.2.json",
         "",
         "  # Add BGM",
-        '  reelforge create "..." --bgm bgm/Echoes.mp3 --bgm-volume 0.3 --bgm-mode loop',
+        '  rf create "..." --bgm bgm/Echoes.mp3 --bgm-volume 0.3 --bgm-mode loop',
         "",
         "  # Change voice + speed",
-        '  reelforge create "..." --tts-voice zh-CN-XiaoxiaoNeural --tts-speed 1.0',
+        '  rf create "..." --tts-voice zh-CN-XiaoxiaoNeural --tts-speed 1.0',
         "",
         "  # Full recipe in one file",
-        "  reelforge create --recipe ./space.recipe.json",
+        "  rf create --recipe ./space.recipe.json",
         "",
         "  # Override a field on top of a recipe",
-        '  reelforge create --recipe ./space.recipe.json --text "新主题" -n 8',
+        '  rf create --recipe ./space.recipe.json --text "新主题" -n 8',
         "",
         "  # Replay last successful create",
-        "  reelforge create --redo",
+        "  rf create --redo",
         "",
         "  # Replay last but tweak one knob",
-        "  reelforge create --redo --tts-speed 1.0",
+        "  rf create --redo --tts-speed 1.0",
         "",
         "  # See exactly what would be sent (no submission)",
-        '  reelforge create "..." -n 7 --bgm bgm/Echoes.mp3 --dry-run',
+        '  rf create "..." -n 7 --bgm bgm/Echoes.mp3 --dry-run',
+        "",
+        "  # Pipe-friendly: skip local download, take video_url for downstream",
+        '  rf create "..." --no-download --json | jq -r .video_url',
         "",
         "Recipe file format (every field is optional; all keys match the REST API body):",
         "  {",
@@ -260,6 +330,10 @@ export function registerCreate(program) {
         "  }",
     ].join("\n"))
         .action(async (topicArg, opts) => {
+        // Validate -o early so we fail before submitting a paid task
+        if (opts.output) {
+            await validateOutputPath(opts.output);
+        }
         // 1. Layer defaults: --redo → --recipe → CLI opts → positional topic
         let body = {};
         if (opts.redo) {
@@ -278,6 +352,12 @@ export function registerCreate(program) {
         // CLI options layer
         const fromOpts = optsToBody(opts);
         body = { ...body, ...fromOpts };
+        // Capture the raw text input (with potential @-prefix) for filename derivation.
+        // After `resolveText` we lose the @path → file stem mapping.
+        const rawTextInput = topicArg ?? (typeof body.text === "string" ? body.text : undefined);
+        const fileStemFromAt = rawTextInput?.startsWith("@")
+            ? path.parse(rawTextInput.slice(1)).name
+            : undefined;
         // Positional topic wins for `text` (with @file support)
         if (topicArg) {
             body.text = await resolveText(topicArg);
@@ -324,9 +404,33 @@ export function registerCreate(program) {
             throw new Error(t.error || `Task ended with status ${t.status}`);
         }
         const result = t.result;
-        if (opts.output && result?.video_url) {
-            await downloadTo(result.video_url, opts.output);
-            success(`Saved → ${opts.output}`);
+        // Decide where (or whether) to save locally.
+        //   -o            → that exact path
+        //   --no-download → skip
+        //   stdout piped  → skip (clig.dev: don't dump binary-touching side effects into a script)
+        //   otherwise     → auto-named in cwd
+        if (result?.video_url) {
+            const stdoutIsPipe = !process.stdout.isTTY;
+            const skipDownload = !!opts.noDownload || (stdoutIsPipe && !opts.output);
+            let savedPath;
+            if (opts.output) {
+                savedPath = opts.output;
+            }
+            else if (!skipDownload) {
+                savedPath = computeDefaultFilename({
+                    resultTitle: result.title,
+                    bodyTitle: finalBody.title,
+                    mode: finalBody.mode,
+                    rawTextInput,
+                    fileStemFromAt,
+                    taskId: t.id,
+                    ext: "mp4",
+                });
+            }
+            if (savedPath) {
+                await downloadTo(result.video_url, savedPath);
+                success(`Saved → ${savedPath}`);
+            }
         }
         print({ task_id: t.id, status: t.status, ...result });
     });

package/dist/index.js

@@ -66,19 +66,14 @@ program
 program.addHelpText("afterAll", [
     "",
     "Examples (tip: `rf` works wherever you see `reelforge`):",
-    "  reelforge create '为什么我们还没有找到外星文明？' -o space.mp4",
-    "  rf create '为什么我们还没有找到外星文明？' -o space.mp4",
-    "  reelforge llm chat --prompt 'explain antifragile in 3 sentences'",
-    "  reelforge tts edge --text 'hello world' --voice en-US-AriaNeural -o out.mp3",
-    "  reelforge images generate --prompt 'a cat' --workflow selfhost/image_flux.json -o cat.png",
-    "  reelforge pipelines standard --text 'why we explore space' --tts-voice zh-CN-YunjianNeural",
-    "  reelforge tasks list --status running",
-    "  reelforge config get",
-    "",
-    "Setup before publishing to npm:",
-    "  1) cd cli && npm install && npm run build",
-    "  2) npm link  (test locally as `reelforge`)",
-    "  3) npm publish --access public",
+    "  rf create '为什么我们还没有找到外星文明？'              # auto-saves to ./<title>-<id>.mp4 in cwd",
+    "  rf create '...' -o ./videos/space.mp4                # pick the exact path",
+    "  rf llm chat --prompt 'explain antifragile in 3 sentences'",
+    "  rf tts edge --text 'hello world' --voice en-US-AriaNeural -o out.mp3",
+    "  rf images generate --prompt 'a cat' --workflow selfhost/image_flux.json -o cat.png",
+    "  rf pipelines standard --text 'why we explore space' --tts-voice zh-CN-YunjianNeural",
+    "  rf tasks list --status running",
+    "  rf config get",
 ].join("\n"));
 registerAuth(program);
 registerCreate(program);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "reelforge",
-  "version": "0.3.1",
-  "description": "CLI for ReelForge Studio — AI video engine. Every REST API exposed as a command, with --help on every level.",
+  "version": "0.3.2",
+  "description": "CLI for ReelForge Studio — AI video engine. Installs as both `reelforge` and the short alias `rf`. Every REST API exposed as a command, with --help on every level.",
   "license": "Apache-2.0",
   "type": "module",
   "bin": {