@facelessad/cli 1.0.2 → 1.1.1

package/README.md

@@ -27,6 +27,65 @@ stops on it immediately instead of polling forever. For long-running
 builds a webhook is still the better tool — a stuck shell is a stuck CI
 job. See https://facelessad.com/developers → Webhooks.
 
+## Getting the finished video
+
+`--wait` tells you when the video is done, but it never prints the video URL.
+Three ways to get the file:
+
+```bash
+facelessad download 103 --out ad.mp4        # saves into the CURRENT directory
+facelessad status 103 --json | jq -r .url   # the raw link, valid ~1 hour
+```
+
+The third is the browser: every video made through the CLI also appears in My
+Files at facelessad.com.
+
+Since 1.1.1 `download` prints the full path and the file size, and fails
+loudly on an empty file instead of reporting success. The link is signed and
+expires in about an hour — the video itself does not, so ask for the status
+again to get a fresh one.
+
+## Custom style (1.1.0)
+
+Most tools accept a look of your own instead of one of the built-in styles.
+`facelessad tools` marks which ones (`supports.customStyle`):
+
+```bash
+facelessad create --tool motion-graphics --url https://your-product.com \
+  --style custom \
+  --custom-style "Retro terminal — phosphor green on near-black, scan lines, chunky mono type" --wait
+```
+
+What to describe depends on what the tool builds. Animated Ad, Character,
+Music Video, Inspiration, Motivational and Slideshow render images, so
+describe the illustration or cinematic style. Motion Graphics, SaaS UI Ad,
+Text Animation and Video Banner generate their graphics as code, so describe
+typography, palette and motion. Crude Drawings has no custom style.
+
+Product Showcase builds both — cinematic clips animated from your real
+product photo, and text graphics drawn in code on top — so it takes two
+descriptions:
+
+```bash
+facelessad create --tool product-showcase --product-image https://.../bottle.jpg \
+  --text "A steel bottle that keeps drinks cold for 24 hours" \
+  --style custom \
+  --custom-style "Frozen tundra — cracked ice, pale blue rim light, slow orbiting camera" \
+  --custom-graphics-style "Deep navy typography, thin white hairlines — the video reads light" --wait
+```
+
+Leave `--custom-graphics-style` out and it is written for you from the first
+description.
+
+Your text is expanded into a full style specification before the video is
+built. `facelessad status <id> --json` returns the expanded text as
+`customStyle`; feed it back with `--no-refine-style` to give a whole
+campaign one identical look.
+
+`--style-hint` is now an alias: with no `--style`, it is treated exactly like
+`--custom-style`. Before 1.1.0 it only reached the script writer and could
+not change how the video looked.
+
 ## Flag spellings (1.0.1)
 
 Both spellings are accepted, because the older ones appeared on the

package/index.js

@@ -111,6 +111,10 @@ if (flags['no-music'] === true) { flags.music = 'false'; delete flags['no-music'
  */
 const KNOWN_FLAGS = new Set([
   'tool', 'url', 'text', 'duration', 'aspect', 'language', 'style', 'style-hint',
+  // 1.1.0 (§673): custom style. --style custom yksin ei riita — palvelin
+  // vastaa custom_style_required, ja se on tarkoitus: tyylin sisalto ON
+  // kayttajan teksti.
+  'custom-style', 'custom-graphics-style', 'no-refine-style',
   'structure', 'hook', 'video-mode', 'brand-color', 'brand-name', 'cta', 'name',
   'voice', 'gender', 'no-voice', 'music', 'sfx', 'captions', 'product-image',
   'no-brand-kit', 'no-winners', 'brand-kit',
@@ -220,6 +224,13 @@ function buildBody() {
   set('language', flags.language !== undefined ? String(flags.language) : undefined);
   set('style', flags.style !== undefined ? String(flags.style) : undefined);
   set('style_hint', flags['style-hint'] !== undefined ? String(flags['style-hint']) : undefined);
+  // 1.1.0 (§673): oma tyyli. --custom-style on ainoa lippu joka oikeasti
+  // vaihtaa videon ilmeen; --style-hint on nykyaan sen alias silloin kun
+  // --style on antamatta. --custom-graphics-style koskee vain
+  // product-showcasea (video + sen paalle koodilla piirretyt grafiikat).
+  set('custom_style', flags['custom-style'] !== undefined ? String(flags['custom-style']) : undefined);
+  set('custom_graphics_style', flags['custom-graphics-style'] !== undefined ? String(flags['custom-graphics-style']) : undefined);
+  if (flags['no-refine-style'] === true) body.custom_style_refine = false;
   set('ad_structure', flags.structure !== undefined ? String(flags.structure) : undefined);
   set('hook_formula', flags.hook !== undefined ? String(flags.hook) : undefined);
   set('video_mode', flags['video-mode'] !== undefined ? String(flags['video-mode']) : undefined);
@@ -371,8 +382,18 @@ const commands = {
     const file = String(flags.out || ('facelessad-' + id + '.mp4'));
     const res = await fetch(d.url);
     if (!res.ok) die('Download failed: HTTP ' + res.status, 'download_failed');
-    fs.writeFileSync(file, Buffer.from(await res.arrayBuffer()));
-    out({ ok: true, file }, 'Saved ' + file);
+    const buf = Buffer.from(await res.arrayBuffer());
+    // 1.1.1: tyhjä tiedosto tulosti ennen saman "Saved" kuin onnistunut lataus.
+    if (!buf.length) die('Download produced an empty file — the link may have expired. Run `facelessad status ' + id + '` and try again.', 'empty_download');
+    fs.writeFileSync(file, buf);
+    // 1.1.1: pelkkä tiedostonimi ei kertonut MIHIN tallennettiin. Tiedosto
+    // menee työhakemistoon, ei Downloadsiin, ja käyttäjä jäi etsimään sitä
+    // (omistajan raportti 12.8.2026). Absoluuttinen polku ja koko ääneen.
+    const full = path.resolve(file);
+    const mb = buf.length / (1024 * 1024);
+    const size = mb >= 1 ? mb.toFixed(1) + ' MB' : Math.max(1, Math.round(buf.length / 1024)) + ' kB';
+    out({ ok: true, file, path: full, bytes: buf.length },
+      'Saved ' + full + dim(' (' + size + ')'));
   },
 
   async help() {
@@ -388,10 +409,13 @@ Commands:
   create --tool <id> ...      Create a video (returns an id immediately)
   status <id> [--wait]        Status; --wait polls until done
   list [--limit --offset]     Your videos, newest first
-  download <id> [--out file]  Save the finished mp4
+  download <id> [--out file]  Save the finished mp4 into the current directory
 
 Create flags:
   --tool --url --text --duration --aspect --language --style --style-hint
+  --custom-style "<look you want>"  (with --style custom; see facelessad tools)
+  --custom-graphics-style "<...>"   (product-showcase only)
+  --no-refine-style                 (use your text verbatim, don't expand it)
   --structure --hook --video-mode --brand-color --brand-name --cta --name
   --voice --gender --no-voice --music --sfx --captions --product-image
   --no-brand-kit --no-winners --brand-kit <id> (see: facelessad brands)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@facelessad/cli",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "description": "Create faceless video ads from your terminal or build scripts — the FacelessAd command line.",
   "license": "MIT",
   "type": "module",