@facelessad/cli 1.1.0 → 1.2.0

package/README.md

@@ -27,6 +27,24 @@ 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.
@@ -84,10 +102,76 @@ developers page and live on in scripts:
 | `--no-music` | `--music false` |
 | `-o` | `--out` |
 
-`--no-brand-kit` and `--no-winners` now work; before 1.0.1 they were
-accepted on the command line and silently dropped, so the video was built
-with the Brand Kit anyway. **An unknown flag is now an error** rather than
+`--no-brand-kit` now works; before 1.0.1 it was accepted on the command line
+and silently dropped, so the video was built with the Brand Kit anyway. **An unknown flag is now an error** rather than
 something quietly ignored — that silence is what hid the whole problem.
 
+## 1.2.0
+
+**Video Banner has flags.** Its copy and images were reachable through the
+HTTP API but had no flags at all, so the only way to set them was
+`--file body.json`:
+
+```bash
+facelessad create --tool video-banner --url https://example.com \
+  --headline "Ship ads in minutes" --subline "No camera, no crew" \
+  --cta-text "Try it free" --badge random_face --photo-query "nordic office" --wait
+```
+
+Leave the three texts out and they are written for you from the materials.
+Give a headline and only your own copy is used — the fields you leave empty
+stay empty rather than being written for you (`--text-mode` makes the choice
+explicit). `--background-image <url>` replaces the automatic photo pick
+entirely, and `--badge-image <url>` puts your own image in the corner instead
+of the AI face.
+
+**Product Showcase extra angles:** `--product-images url1,url2,url3` (up to 8),
+which improves how well the product keeps its shape and label across clips.
+
+**SaaS UI Ad takes screenshots.** The tool decomposes real screens with vision
+and rebuilds them animated — that is the whole point of it, and without them
+the ad is built from your written description alone:
+
+```bash
+facelessad create --tool saas-ui-ad --url https://your-app.com \
+  --screenshots "https://.../dashboard.png,https://.../editor.png" --wait
+```
+
+How many fit depends on the length, because each screen needs time on camera:
+1 for short, 3 for medium, 4 for long. `facelessad tools --tool saas-ui-ad`
+prints the limits.
+
+**Character does dialogue.** `--speakers 2` makes it a conversation between two
+characters instead of one narrator, and the ad structure has to match — the
+two pools are listed by `facelessad tools --tool character`:
+
+```bash
+facelessad create --tool character --url https://your-product.com \
+  --speakers 2 --structure ch-qa --gender-right male --wait
+```
+
+`--voice-right <id>` and `--gender-right female|male` steer the second voice.
+Leave them out and a distinct one is picked for you — a different gender
+first, then a different id. They need `--speakers 2`; without it the command
+stops before it reaches the network.
+
+**A flag that needs a value is an error without one.** `--brand-kit` on its own
+used to mean brand number 1, and `download 5 -o` used to write a file called
+`true`. Both now stop with `missing_value`. Flags that are booleans by nature
+(`--sfx`, `--no-voice`, `--wait`) are unaffected.
+
+**Boolean flags are validated.** `--captions yes`, `--captions 1` and
+`--captions TRUE` used to become **false** without a word, because only the
+exact string `true` was accepted. All the usual spellings now work in both
+directions, and anything else is an error instead of a silent guess.
+
+**`facelessad tools --tool <id>` shows every ad structure**, grouped the way
+the app groups them. It used to print only the default group — 17 of animated
+ad's 46, and 6 of motion graphics' 119.
+
+**`--winners` / `--no-winners` are gone.** Winning-ad analyses are not offered
+through the API while the feature is unfinished; the server no longer reads the
+field.
+
 Errors are printed with the API's own wording and exit code 1. The machine
 code (e.g. `unknown_style`) follows the message.

package/index.js

@@ -116,12 +116,54 @@ const KNOWN_FLAGS = new Set([
   // 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',
+  'voice', 'gender', 'no-voice', 'voice-over', 'music', 'sfx', 'captions', 'product-image',
+  // §708: character-dialogi — puhujamäärä ja toisen puhujan ääni.
+  'speakers', 'voice-right', 'gender-right',
+  'no-brand-kit', 'brand-kit',
+  // 1.2.0: showcasen lisäkulmat ja video-bannerin kahdeksan kenttää.
+  'product-images', 'screenshots',
+  'headline', 'subline', 'cta-text', 'text-mode',
+  'background-image', 'badge-image', 'badge', 'photo-query',
   'file', 'dry-run', 'wait', 'timeout', 'json', 'out', 'limit', 'offset', 'version',
 ]);
 const unknownFlags = Object.keys(flags).filter((f) => !KNOWN_FLAGS.has(f)).map((f) => '--' + f).concat(badShort);
 
+/**
+ * 1.2.0 — ARVOA VAATIVA LIPPU ILMAN ARVOA ON VIRHE.
+ *
+ * Sama hiljainen vikaluokka jota koko 1.0.1 korjasi, mutta yhtä kerrosta
+ * syvemmällä: lippu TUNNETAAN, se vain jäi ilman arvoa. Silloin sen arvoksi
+ * tulee `true`, ja jokainen String()-muunnos tekee siitä merkkijonon
+ * "true". Osa niistä pysähtyy palvelimen validointiin, mutta kaikki eivät —
+ * ja juuri ne jotka eivät, ovat pahimpia:
+ *
+ *   facelessad create --brand-kit --tool x   → brand_kit_id: 1
+ *       `Number(true) === 1` ja `Number.isInteger(1)`, joten `num()` päästi
+ *       sen läpi. Id 1 on oikea brändi — vain väärä. Video valmistuu toisen
+ *       brändin väreillä ja äänensävyllä eikä siitä kerrota missään.
+ *   facelessad download 5 -o                 → tiedosto nimeltä `true`
+ *       Ilman päätettä, työhakemistoon. 1.1.1 lisäsi juuri koko polun
+ *       tulostamisen siksi ettei tiedostoa löytynyt; tämä on sama ongelma
+ *       pahempana.
+ *   facelessad list --limit                  → limit=1, lista kutistuu
+ *   facelessad create --headline --tool …    → bannerin otsikoksi "true"
+ *   --brand-name, --cta, --language, --gender, --photo-query, --custom-style
+ *       → kaikki hiljaa väärä arvo, ei virhettä mistään
+ *
+ * Yksittäisten kutsupaikkojen paikkaaminen olisi jättänyt loput; tämä on
+ * yksi portti kaikille 39:lle. Totuusarvoliput (--sfx, --wait, --no-voice…)
+ * ovat tarkoituksella ulkopuolella: niille arvottomuus ON arvo.
+ */
+const BOOLEAN_FLAGS = new Set([
+  'no-captions', 'no-music', 'no-refine-style', 'no-voice', 'no-brand-kit',
+  'dry-run', 'wait', 'json', 'version',
+  // Näillä neljällä arvo on VALINNAINEN: `--sfx` tarkoittaa `--sfx true`.
+  'sfx', 'music', 'captions', 'voice-over',
+]);
+const missingValues = Object.keys(flags)
+  .filter((f) => flags[f] === true && KNOWN_FLAGS.has(f) && !BOOLEAN_FLAGS.has(f))
+  .map((f) => '--' + f);
+
 const asJson = flags.json === true || flags.json === 'true';
 
 // ────────────────────────── config / auth ──────────────────────────
@@ -200,6 +242,57 @@ function num(flag, raw) {
   return n;
 }
 
+/**
+ * §706 — `--duration` ottaa vastaan kolmen vaihtoehdon id:n TAI sekuntiluvun.
+ * Sekuntien kelvollisuuden ratkaisee palvelin (se tuntee työkalukohtaiset
+ * vaihtoehdot rekisteristä), joten täällä tarkistetaan vain muoto: id tai
+ * kokonaisluku. `facelessad tools --tool <id>` tulostaa vaihtoehdot.
+ */
+const DURATION_IDS = new Set(['short', 'medium', 'long']);
+function durationValue(raw) {
+  if (raw === undefined) return undefined;
+  if (raw === true) die('--duration needs a value: short | medium | long, or the seconds for that length', 'invalid_duration');
+  const v = String(raw).trim().toLowerCase();
+  if (DURATION_IDS.has(v)) return v;
+  const n = Number(raw);
+  if (!Number.isInteger(n)) {
+    die('--duration must be short, medium or long — or the seconds for that length. See: facelessad tools --tool <id>', 'invalid_duration');
+  }
+  return n;
+}
+
+/**
+ * §706 — kyselymerkkijono ilman `URLSearchParams.size`ä. Se on Nodessa vasta
+ * 18.16 / 19.8, mutta tämä paketti lupaa `node>=18`: sitä vanhemmalla 18:lla
+ * `q.size` on undefined, jolloin `?`-osa jäi pois KOKONAAN ja `--language`,
+ * `--gender`, `--limit` ja `--offset` katosivat ilman mitään ilmoitusta.
+ * Sama hiljainen luokka jota tämä paketti on muuten täynnä korjaamassa.
+ */
+function qs(q) {
+  return [...q.keys()].length ? '?' + q.toString() : '';
+}
+
+/**
+ * 1.2.0 — BOOLEAN-LIPUT VALIDOIDAAN. Tämä oli sama hiljainen vikaluokka jota
+ * koko 1.0.1 korjasi, mutta se jäi näihin kolmeen lippuun: koodi vertasi
+ * arvoa merkkijonoon "true", joten `--captions yes`, `--captions 1` ja
+ * `--captions TRUE` päätyivät kaikki arvoon FALSE ilman mitään ilmoitusta.
+ * Käyttäjä pyysi tekstitykset ja sai videon ilman.
+ *
+ * Nyt tavanomaiset kirjoitusasut hyväksytään molempiin suuntiin ja mikä
+ * tahansa muu on VIRHE — hiljaista arvausta ei tehdä kumpaankaan suuntaan.
+ */
+const BOOL_TRUE = new Set(['true', '1', 'yes', 'y', 'on']);
+const BOOL_FALSE = new Set(['false', '0', 'no', 'n', 'off']);
+function bool(flag, raw) {
+  if (raw === undefined) return undefined;
+  if (raw === true) return true;                 // pelkkä --sfx ilman arvoa
+  const v = String(raw).trim().toLowerCase();
+  if (BOOL_TRUE.has(v)) return true;
+  if (BOOL_FALSE.has(v)) return false;
+  die('--' + flag + ' must be true or false, got "' + raw + '"', 'invalid_boolean');
+}
+
 // ────────────────────────── request body from flags ──────────────────────────
 
 /**
@@ -219,7 +312,12 @@ function buildBody() {
     if (flags.url !== undefined) body.materials.landing_page_url = String(flags.url);
     if (flags.text !== undefined) body.materials.text = String(flags.text);
   }
-  set('duration', num('duration', flags.duration));
+  // §706: kesto on kolme vaihtoehtoa, ei väli. Palvelin hyväksyy joko id:n
+  // ("short"|"medium"|"long") tai sitä vastaavan sekuntiluvun ja hylkää muut
+  // (invalid_duration). Ennen se puristi arvon hiljaa rajoihin ja worker
+  // pudotti sen samoihin kolmeen ämpäriin, joten --duration 45 teki saman
+  // videon kuin --duration 50 eikä siitä kerrottu missään.
+  set('duration', durationValue(flags.duration));
   set('aspect_ratio', flags.aspect !== undefined ? String(flags.aspect) : undefined);
   set('language', flags.language !== undefined ? String(flags.language) : undefined);
   set('style', flags.style !== undefined ? String(flags.style) : undefined);
@@ -241,15 +339,83 @@ function buildBody() {
   set('product_image_url', flags['product-image'] !== undefined ? String(flags['product-image']) : undefined);
   // 1.0.1 (§640): kumpi brändi. Ilman tätä API otti aina tilin oletusbrändin.
   set('brand_kit_id', num('brand-kit', flags['brand-kit']));
-  if (flags.music !== undefined) body.music = flags.music === true || flags.music === 'true';
-  if (flags.sfx !== undefined) body.sfx = flags.sfx === true || flags.sfx === 'true';
-  if (flags.captions !== undefined) body.captions = flags.captions === true || flags.captions === 'true';
+  if (flags.music !== undefined) body.music = bool('music', flags.music);
+  if (flags.sfx !== undefined) body.sfx = bool('sfx', flags.sfx);
+  if (flags.captions !== undefined) body.captions = bool('captions', flags.captions);
+  /**
+   * §724 — `--voice-over` PUUTTUI KOKONAAN. CLI osasi vain kytkeä kertojan
+   * POIS (`--no-voice`), ei päälle. Kolmella työkalulla valinta on olemassa
+   * (`supports.voiceOverToggle`: slideshow, inspiration, product-showcase), ja
+   * Inspiration Reelillä KAIKKI kymmenen tyyliä ovat oletuksena mykkiä — eli
+   * `voice_over: true` on ainoa tapa saada siihen kertoja, eikä sitä voinut
+   * komentoriviltä pyytää lainkaan. HTTP-API ja MCP ovat tukeneet kenttää
+   * alusta asti; vain tämä paketti ei.
+   *
+   * `--no-voice` säilyy ja voittaa, jos molemmat annetaan.
+   */
+  if (flags['voice-over'] !== undefined) body.voice_over = bool('voice-over', flags['voice-over']);
   if (flags['no-voice'] === true) body.voice_over = false;
   // 1.0.1: nämä kaksi puuttuivat kokonaan. facelessad.com/developers tuotti
   // niille lippuja joita tämä tiedosto ei lukenut, joten "älä käytä brand
   // kittiä" -pyyntö meni hiljaa roskiin ja API:n oletus (true) voitti.
   if (flags['no-brand-kit'] === true) body.use_brand_kit = false;
-  if (flags['no-winners'] === true) body.use_winners = false;
+  // 1.2.0: --winners / --no-winners POISTETTU. Voittaja-analyysit ovat
+  // keskeneräinen ominaisuus jota ei tarjota API:n kautta (§705); palvelin ei
+  // enää lue kenttää lainkaan.
+  // 1.2.0: product-showcasen lisäkulmakuvat. API on hyväksynyt kentän §556:sta
+  // asti ja MCP-skeemassa se on ollut alusta, mutta CLI:stä se puuttui.
+  // §711: SaaS UI Ad — kuvakaappaukset pilkulla eroteltuna, kuten
+  // --product-images. Katto on kestokohtainen ja tulee palvelimelta;
+  // `facelessad tools --tool saas-ui-ad` tulostaa sen screenshots-rivillä
+  // (1.2.0 asti rivi puuttui, vaikka tämä kommentti lupasi sen — raja
+  // selvisi vasta palvelimen too_many_screenshots -virheestä).
+  if (flags.screenshots !== undefined) {
+    const urls = String(flags.screenshots).split(',').map((s) => s.trim()).filter(Boolean);
+    if (urls.length) body.screenshot_urls = urls;
+  }
+  if (flags['product-images'] !== undefined) {
+    const urls = String(flags['product-images']).split(',').map((s) => s.trim()).filter(Boolean);
+    if (urls.length) body.product_image_urls = urls;
+  }
+  // 1.2.0: VIDEO BANNER. Kahdeksan kenttää jotka API on hyväksynyt §362/§380:stä
+  // asti ja jotka MCP-skeema on tuntenut — mutta joille ei ollut yhtään lippua,
+  // joten bannerin oma copy oli komentoriviltä täysin saavuttamaton ja
+  // facelessad.com/developers joutui ohjaamaan --file-muotoon.
+  const bannerTexts = {};
+  if (flags.headline !== undefined) bannerTexts.headline = String(flags.headline);
+  if (flags.subline !== undefined) bannerTexts.subline = String(flags.subline);
+  if (flags['cta-text'] !== undefined) bannerTexts.cta_text = String(flags['cta-text']);
+  if (Object.keys(bannerTexts).length) body.texts = { ...(body.texts || {}), ...bannerTexts };
+  set('text_mode', flags['text-mode'] !== undefined ? String(flags['text-mode']) : undefined);
+  set('background_image_url', flags['background-image'] !== undefined ? String(flags['background-image']) : undefined);
+  set('badge_image_url', flags['badge-image'] !== undefined ? String(flags['badge-image']) : undefined);
+  set('badge', flags.badge !== undefined ? String(flags.badge) : undefined);
+  set('photo_query', flags['photo-query'] !== undefined ? String(flags['photo-query']) : undefined);
+  // §708: character. --speakers 2 tekee dialogin; rakenteen on oltava
+  // kahden puhujan poolista (facelessad tools --tool character näyttää
+  // molemmat poolit). --voice-right / --gender-right ohjaa [R]-puhujaa;
+  // jätettynä pois palvelin poimii erottuvan äänen itse.
+  if (flags.speakers !== undefined) {
+    const sp = String(flags.speakers).trim().toLowerCase();
+    const n = { '1': 1, 'one': 1, '2': 2, 'two': 2 }[sp];
+    if (!n) die('--speakers must be 1 (one narrator) or 2 (a dialogue between two characters)', 'invalid_speakers');
+    body.speakers = n;
+  }
+  if (flags['voice-right'] !== undefined || flags['gender-right'] !== undefined) {
+    // §710: toinen ääni on olemassa vain kahden puhujan ajossa. Palvelin
+    // hylkää sen muuten (voice_right_without_two_speakers), mutta virhe
+    // kannattaa antaa tässä: komento pysähtyy ennen verkkokutsua eikä
+    // käyttäjä jää odottamaan vastausta pyyntöön joka ei voi onnistua.
+    // Huom: --file voi tuoda speakersin rungosta, joten tarkistus katsoo
+    // lopullista arvoa eikä pelkkää lippua.
+    if (body.speakers !== 2) {
+      die('--voice-right and --gender-right are the second speaker\'s voice — they need --speakers 2. '
+        + 'With one narrator, use --voice / --gender.', 'voice_right_without_two_speakers');
+    }
+    body.voice_right = {};
+    if (typeof flags['voice-right'] === 'string') body.voice_right.id = flags['voice-right'];
+    if (flags['gender-right'] !== undefined) body.voice_right.gender = String(flags['gender-right']);
+  }
   if (flags.voice !== undefined || flags.gender !== undefined) {
     if (typeof flags.voice === 'string' && flags.gender === undefined) {
       body.voice = flags.voice;
@@ -311,8 +477,72 @@ const commands = {
       if (!t) die('Unknown tool "' + flags.tool + '". Valid: ' + (d.tools || []).map((x) => x.id).join(', '), 'unknown_tool');
       const lines = [bold(t.id) + ' — ' + (t.name || '')];
       if (t.styles?.length) lines.push('  styles: ' + t.styles.map((s) => s.id).join(', '));
-      if (t.adStructures?.length) lines.push('  ad structures: ' + t.adStructures.map((s) => s.id).join(', '));
-      if (t.durations) lines.push('  duration: ' + t.durations.min + '–' + t.durations.max + ' s');
+      // 1.2.0: rekisteri kertoo rakenteet KOLMESSA muodossa (§698). Ennen tämä
+      // tulosti vain adStructures-listan, joka on oletusryhmän pooli — eli
+      // animated-adilla 17 rakennetta 46:sta ja motion-graphicsilla 6 sadasta
+      // yhdeksästätoista. Loput olivat näkyvissä vain --json-tulosteessa.
+      if (t.adStructureGroups?.length) {
+        const total = t.adStructureGroups.reduce((n, g) => n + (g.structures?.length || 0), 0);
+        lines.push('  ad structures: ' + total + ' in ' + t.adStructureGroups.length + ' groups');
+        for (const g of t.adStructureGroups) {
+          lines.push('    ' + dim(g.name || g.id) + ': ' + (g.structures || []).map((s) => s.id).join(', '));
+        }
+      } else if (t.adStructures?.length) {
+        lines.push('  ad structures: ' + t.adStructures.map((s) => s.id).join(', '));
+      }
+      // Tyylit joilla on OMA rakennepooli — valinta riippuu tyylistä, ja
+      // yleisen listan rakenne hylätään niillä (structure_style_mismatch).
+      // §708: characterin rakenteet ovat kaksi poolia puhujamäärän mukaan.
+      // Yhtenä listana ne näyttäisivät vaihtoehdoilta jotka kaikki toimivat
+      // millä tahansa --speakers-arvolla, ja API hylkää ristiriidan.
+      if (t.speakerStructures) {
+        for (const [key, n] of [['one', '--speakers 1'], ['two', '--speakers 2']]) {
+          const pool = t.speakerStructures[key] || [];
+          if (pool.length) lines.push('    ' + dim(n) + ': ' + pool.map((x) => x.id).join(', '));
+        }
+      }
+      for (const [sid, pool] of Object.entries(t.structuresByStyle || {})) {
+        lines.push('    ' + dim('with style ' + sid) + ': ' + (pool || []).map((s) => s.id).join(', '));
+      }
+      // §706: kolme vaihtoehtoa, ei väli. Rivi luki ennen "duration: 10–60 s",
+      // mikä lupasi 51 arvoa joista syntyi kolme videota — ja on nyt suoraan
+      // väärin, koska palvelin hylkää välistä poimitun luvun.
+      if (t.durations?.options?.length) {
+        // Bannerin id:t OVAT sekunnit ("5"/"10"/"15"), joten "5 (5 s)" olisi
+        // kohinaa; muilla id on nimi (short/medium/long) ja kuuluu näkyviin.
+        lines.push('  duration: ' + t.durations.options
+          .map((o) => (String(o.id) === String(o.seconds) ? o.seconds + ' s' : o.id + ' (' + o.seconds + ' s)'))
+          .join(' · '));
+      } else if (t.durations) {
+        lines.push('  duration: ' + t.durations.min + '–' + t.durations.max + ' s');
+      }
+      /**
+       * §711/1.2.0 — KUVAKAAPPAUSTEN KATTO NÄKYVIIN. `--screenshots`in
+       * kommentti lupasi että tämä komento näyttää rajan ("katto on
+       * kestokohtainen ja tulee palvelimelta"), mutta yksikään rivi ei
+       * tulostanut sitä. Käyttäjän ainoa tapa saada raja selville oli lähettää
+       * liikaa kuvia ja lukea `too_many_screenshots` — eli arvata ensin.
+       *
+       * Rekisteri kantaa luvut kestokohtaisesti (`screenshots.max`), ja
+       * järjestys luetaan `durations.options`ista eikä objektin avainten
+       * järjestyksestä, jotta rivi vastaa yllä olevaa duration-riviä.
+       */
+      // §725: kertoo että tämä työkalu komposoi tuotekuvan kohtauksiinsa.
+      if (t.supports?.productInScenes) {
+        lines.push('  product photo: composed into scenes' + dim('   (--product-image <url>)'));
+      }
+      const shotMax = t.screenshots?.max;
+      if (shotMax && Object.keys(shotMax).length) {
+        const order = t.durations?.options?.length
+          ? t.durations.options.map((o) => String(o.id))
+          : Object.keys(shotMax);
+        const parts = order
+          .filter((id) => shotMax[id] !== undefined)
+          .map((id) => id + ' ' + shotMax[id]);
+        if (parts.length) {
+          lines.push('  screenshots: ' + parts.join(' · ') + dim('   (--screenshots url1,url2)'));
+        }
+      }
       out({ ok: true, tool: t }, lines.join('\n'));
       return;
     }
@@ -323,7 +553,7 @@ const commands = {
     const d = await call('GET', '/api/v1/brand-kits');
     out(d, (d.brandKits || []).map((k) =>
       '  ' + String(k.id).padEnd(6) + (k.name || '').padEnd(24)
-      + dim(k.filled + '/32 answered'
+      + dim(k.filled + '/' + (k.questions ?? 31) + ' answered'
         + (k.isDefault ? ' · default' : '')
         + (k.hasColor ? ' · colour' : '')
         + (k.hasLogo ? ' · logo' : ''))
@@ -334,12 +564,18 @@ const commands = {
     const q = new URLSearchParams();
     if (flags.language) q.set('language', String(flags.language));
     if (flags.gender) q.set('gender', String(flags.gender));
-    const d = await call('GET', '/api/v1/voices' + (q.size ? '?' + q : ''));
+    const d = await call('GET', '/api/v1/voices' + qs(q));
     out(d, (d.voices || []).map((v) => '  ' + v.id.padEnd(24) + (v.name || '').padEnd(16) + dim((v.gender || '') + ' ' + (v.language || ''))).join('\n'));
   },
 
   async estimate() {
     const body = buildBody();
+    // §712: sama paikallinen tarkistus kuin `create`illa. Ilman sitä
+    // `facelessad estimate --url …` lähti verkkoon ja palasi palvelimen
+    // `unknown_tool ""` -virheellä, joka kertoo puuttuvasta työkalusta
+    // kiertoteitse. Molemmat komennot ottavat saman rungon, joten niiden on
+    // myös hylättävä sama puute samalla tavalla.
+    if (!body.tool) die('--tool is required. See: facelessad tools', 'missing_tool');
     if (flags['dry-run'] === true) { out({ ok: true, body }, JSON.stringify(body, null, 2)); return; }
     const d = await call('POST', '/api/v1/estimate', body);
     out(d, 'Estimate: up to ~' + d.estimate + ' credits (balance: ' + d.balance + ')\n' + dim(d.note || ''));
@@ -370,7 +606,7 @@ const commands = {
     const lim = num('limit', flags.limit), off = num('offset', flags.offset);
     if (lim !== undefined) q.set('limit', String(lim));
     if (off !== undefined) q.set('offset', String(off));
-    const d = await call('GET', '/api/v1/videos' + (q.size ? '?' + q : ''));
+    const d = await call('GET', '/api/v1/videos' + qs(q));
     out(d, (d.videos || []).map((v) => '  ' + String(v.id).padEnd(8) + v.status.padEnd(10) + (v.tool || '').padEnd(18) + dim(v.name || '')).join('\n') || '  (no videos yet)');
   },
 
@@ -382,8 +618,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() {
@@ -399,18 +645,35 @@ 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
+  --tool --url --text --aspect --language --style --style-hint
+  --duration short|medium|long   (or the seconds for that length; see: facelessad tools --tool <id>)
   --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)
+  --structure --hook --brand-color --brand-name --cta --name
+  --video-mode continuous|cuts     (animated-ad and music-video only)
+  --voice --gender --no-voice --voice-over --music --sfx --captions
+      (leave --voice out and the voice is cast from the finished script;
+       --gender narrows the casting pool, --voice <id> skips casting)
+  --product-image <url>        (product-showcase: required, every clip is animated
+       from it. animated-ad / crude: optional, composed into the scenes where the
+       product appears — see: facelessad tools --tool <id>)
+  --speakers 1|2               (character: one narrator, or a two-character dialogue)
+  --voice-right <id> --gender-right female|male   (character with --speakers 2)
+  --product-images url1,url2   (product-showcase only: extra angles of the product)
+  --screenshots url1,url2      (saas-ui-ad: screenshots of your app; 1/3/4 by duration)
+  --no-brand-kit --brand-kit <id> (see: facelessad brands; not on video-banner)
   --file body.json (base body; flags override)   --dry-run (print, don't send)
 
+Video Banner flags (silent looping banner — no voice, no script):
+  --headline "..." --subline "..." --cta-text "..."
+  --text-mode simple|full   --photo-query "nordic office"
+  --background-image <url>  --badge none|random_face  --badge-image <url>
+  Leave all three texts out and they are written for you from the materials.
+
 --wait stops watching after 6 hours; --timeout <seconds> changes that and
 --timeout 0 waits with no limit. Stopping the wait never cancels the build.
 A video in "draft" is not building and is never waited on. For overnight
@@ -419,7 +682,8 @@ runs a webhook beats leaving a terminal open — see ${API}/developers.
 Accepted spellings: --brand = --brand-name, --color = --brand-color,
 --voice-id = --voice, --voice-gender = --gender, --no-voice-over = --no-voice,
 --no-captions = --captions false, --no-music = --music false, -o = --out.
-An unknown flag is an error, not something quietly ignored.
+An unknown flag is an error, not something quietly ignored — and so is a
+flag that needs a value but was given without one.
 
 Every command accepts --json. FACELESSAD_API_KEY wins over the saved key
 (use it in CI); long builds are better served by a webhook than --wait —
@@ -543,4 +807,11 @@ if (unknownFlags.length && cmd !== 'help' && cmd !== 'version') {
     + unknownFlags.join(' ')
     + '. Run: facelessad help', 'unknown_flag');
 }
+// 1.2.0: sama portti tunnetuille lipuille jotka jäivät ilman arvoa. Ilman
+// tätä arvoksi jää `true` ja siitä tulee merkkijono "true" — tai luku 1.
+if (missingValues.length && cmd !== 'help' && cmd !== 'version') {
+  die('Missing value for ' + missingValues.join(' ')
+    + '. ' + (missingValues.length > 1 ? 'These flags need one' : 'That flag needs one')
+    + ' — without it the value would be the word "true". Run: facelessad help', 'missing_value');
+}
 fn().catch((e) => die(e.message || String(e), 'unexpected'));

package/package.json

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