@facelessad/cli 1.0.0

package/README.md

@@ -0,0 +1,26 @@
+# @facelessad/cli
+
+Create faceless video ads from your terminal or build scripts.
+
+```bash
+npm install -g @facelessad/cli
+facelessad login                # paste an API key from facelessad.com/developers
+facelessad tools                # what can be made
+facelessad create --tool motion-graphics --url https://your-product.com --wait
+```
+
+Nine commands: `login`, `create`, `status`, `list`, `download`, `estimate`,
+`tools`, `voices`, `balance`. Every command accepts `--json` for scripting;
+`create`/`estimate` accept `--dry-run` (print the request body without
+sending) and `--file body.json` (a base body that flags override).
+
+The key is stored in `~/.facelessad/config.json` with mode 0600. The
+environment variable `FACELESSAD_API_KEY` always wins — that is the way CI
+should authenticate. `FACELESSAD_API_URL` overrides the API base.
+
+`--wait` polls and prints phase + elapsed time; for long-running builds a
+webhook is the better tool — a stuck shell is a stuck CI job. See
+https://facelessad.com/developers → Webhooks.
+
+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

@@ -0,0 +1,334 @@
+#!/usr/bin/env node
+/**
+ * @facelessad/cli — FacelessAd from the terminal.
+ *
+ * Nine commands, each one /api/v1 call. Zero dependencies: Node 18 ships
+ * fetch, and a tool that stores an API key is a bad place for a dependency
+ * tree.
+ *
+ * The key lives in ~/.facelessad/config.json (mode 0600). The environment
+ * variable FACELESSAD_API_KEY wins over the file — that is how CI should
+ * use this. FACELESSAD_API_URL overrides the API base (testing).
+ *
+ * Errors surface with the API's own wording and exit code 1, so a pipeline
+ * stops where it should. The machine code (e.g. unknown_style) is printed
+ * dimmed after the message — readable for a human, greppable for a script.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import readline from 'node:readline';
+
+const API = (process.env.FACELESSAD_API_URL || 'https://facelessad.com').replace(/\/+$/, '');
+const CONFIG_DIR = path.join(os.homedir(), '.facelessad');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+const isTTY = process.stdout.isTTY;
+const dim = (s) => (isTTY ? `\x1b[2m${s}\x1b[0m` : s);
+const bold = (s) => (isTTY ? `\x1b[1m${s}\x1b[0m` : s);
+
+// ────────────────────────── arg parsing ──────────────────────────
+
+const rawArgs = process.argv.slice(2);
+const cmd = rawArgs[0] && !rawArgs[0].startsWith('-') ? rawArgs[0] : (rawArgs.includes('--version') || rawArgs.includes('-v') ? 'version' : 'help');
+const flags = {};
+const positional = [];
+for (let i = cmd === 'help' || cmd === 'version' ? 0 : 1; i < rawArgs.length; i++) {
+  const a = rawArgs[i];
+  if (a.startsWith('--')) {
+    const eq = a.indexOf('=');
+    if (eq !== -1) {
+      flags[a.slice(2, eq)] = a.slice(eq + 1);
+    } else if (i + 1 < rawArgs.length && !rawArgs[i + 1].startsWith('--')) {
+      flags[a.slice(2)] = rawArgs[++i];
+    } else {
+      flags[a.slice(2)] = true;
+    }
+  } else {
+    positional.push(a);
+  }
+}
+const asJson = flags.json === true || flags.json === 'true';
+
+// ────────────────────────── config / auth ──────────────────────────
+
+function readConfig() {
+  try { return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8')); } catch { return {}; }
+}
+function writeConfig(cfg) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2) + '\n', { mode: 0o600 });
+  try { fs.chmodSync(CONFIG_FILE, 0o600); } catch { /* windows */ }
+}
+function apiKey() {
+  const k = process.env.FACELESSAD_API_KEY || readConfig().apiKey || '';
+  if (!k) {
+    die('No API key. Run `facelessad login` or set FACELESSAD_API_KEY. Keys are created at ' + API + '/developers', 'missing_key');
+  }
+  return k;
+}
+
+function die(message, code) {
+  if (asJson) {
+    process.stdout.write(JSON.stringify({ ok: false, error: message, code: code || 'error' }) + '\n');
+  } else {
+    process.stderr.write('Error: ' + message + (code ? ' ' + dim('(' + code + ')') : '') + '\n');
+  }
+  process.exit(1);
+}
+
+// ────────────────────────── HTTP ──────────────────────────
+
+async function call(method, p, body) {
+  let res;
+  try {
+    res = await fetch(API + p, {
+      method,
+      headers: {
+        'Authorization': 'Bearer ' + apiKey(),
+        ...(body ? { 'Content-Type': 'application/json' } : {}),
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+  } catch (e) {
+    die('Could not reach ' + API + ' — ' + (e.cause?.code || e.message), 'network');
+  }
+  let data = null;
+  try { data = await res.json(); } catch { /* non-JSON */ }
+  if (!data || data.ok !== true) {
+    const msg = data?.error || ('HTTP ' + res.status);
+    die(msg, data?.code || 'http_' + res.status);
+  }
+  return data;
+}
+
+function out(data, human) {
+  if (asJson) {
+    process.stdout.write(JSON.stringify(data) + '\n');
+  } else {
+    process.stdout.write(human + '\n');
+  }
+}
+
+// ────────────────────────── request body from flags ──────────────────────────
+
+/**
+ * --file body.json gives the base; flags override it. This is the same body
+ * POST /api/v1/videos takes — the web generator's CLI output maps 1:1 here.
+ */
+function buildBody() {
+  let body = {};
+  if (flags.file) {
+    try { body = JSON.parse(fs.readFileSync(String(flags.file), 'utf8')); }
+    catch (e) { die('Could not read --file ' + flags.file + ': ' + e.message, 'bad_file'); }
+  }
+  const set = (k, v) => { if (v !== undefined) body[k] = v; };
+  set('tool', flags.tool !== undefined ? String(flags.tool) : undefined);
+  if (flags.url !== undefined || flags.text !== undefined) {
+    body.materials = body.materials || {};
+    if (flags.url !== undefined) body.materials.landing_page_url = String(flags.url);
+    if (flags.text !== undefined) body.materials.text = String(flags.text);
+  }
+  set('duration', flags.duration !== undefined ? parseInt(flags.duration, 10) : undefined);
+  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);
+  set('style_hint', flags['style-hint'] !== undefined ? String(flags['style-hint']) : undefined);
+  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);
+  set('brand_color', flags['brand-color'] !== undefined ? String(flags['brand-color']) : undefined);
+  set('brand_name', flags['brand-name'] !== undefined ? String(flags['brand-name']) : undefined);
+  set('cta', flags.cta !== undefined ? String(flags.cta) : undefined);
+  set('name', flags.name !== undefined ? String(flags.name) : undefined);
+  set('product_image_url', flags['product-image'] !== undefined ? String(flags['product-image']) : undefined);
+  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['no-voice'] === true) body.voice_over = false;
+  if (flags.voice !== undefined || flags.gender !== undefined) {
+    if (typeof flags.voice === 'string' && flags.gender === undefined) {
+      body.voice = flags.voice;
+    } else {
+      body.voice = {};
+      if (typeof flags.voice === 'string') body.voice.id = flags.voice;
+      if (flags.gender !== undefined) body.voice.gender = String(flags.gender);
+    }
+  }
+  return body;
+}
+
+// ────────────────────────── commands ──────────────────────────
+
+const commands = {
+
+  async version() {
+    const pkg = JSON.parse(fs.readFileSync(new URL('./package.json', import.meta.url), 'utf8'));
+    out({ ok: true, version: pkg.version }, pkg.version);
+  },
+
+  async login() {
+    let key = process.env.FACELESSAD_API_KEY || '';
+    if (!key) {
+      key = await new Promise((resolve) => {
+        const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+        rl.question('Paste your API key (' + API + '/developers): ', (a) => { rl.close(); resolve(a.trim()); });
+      });
+    }
+    if (!key) die('No key given', 'missing_key');
+    // Verify immediately — a key that silently does not work is worse than
+    // no key at all.
+    let res;
+    try {
+      res = await fetch(API + '/api/v1/balance', { headers: { Authorization: 'Bearer ' + key } });
+    } catch (e) {
+      die('Could not reach ' + API + ' — ' + (e.cause?.code || e.message), 'network');
+    }
+    const data = await res.json().catch(() => null);
+    if (!data || data.ok !== true) {
+      die(data?.error || 'That key was rejected (HTTP ' + res.status + ')', data?.code || 'invalid_key');
+    }
+    writeConfig({ ...readConfig(), apiKey: key });
+    out(
+      { ok: true, plan: data.plan ?? null, balance: data.balance ?? null },
+      'Logged in. Plan: ' + (data.plan ?? '—') + ', balance: ' + (data.balance ?? '—') + ' credits.\nKey saved to ' + CONFIG_FILE + ' (0600).'
+    );
+  },
+
+  async balance() {
+    const d = await call('GET', '/api/v1/balance');
+    out(d, 'Plan: ' + (d.plan ?? '—') + '\nBalance: ' + (d.balance ?? '—') + ' credits');
+  },
+
+  async tools() {
+    const d = await call('GET', '/api/v1/tools');
+    if (flags.tool) {
+      const t = (d.tools || []).find((x) => x.id === flags.tool);
+      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');
+      out({ ok: true, tool: t }, lines.join('\n'));
+      return;
+    }
+    out(d, (d.tools || []).map((t) => '  ' + t.id.padEnd(18) + dim(t.name || '')).join('\n') + '\n\nDetails: facelessad tools --tool <id>');
+  },
+
+  async voices() {
+    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 : ''));
+    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();
+    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 || ''));
+  },
+
+  async create() {
+    const body = buildBody();
+    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/videos', body);
+    if (!(flags.wait === true)) {
+      out(d, 'Queued. id=' + d.id + ' (estimate: up to ~' + d.estimate + ' credits)\nFollow it: facelessad status ' + d.id + ' --wait');
+      return;
+    }
+    await waitFor(d.id);
+  },
+
+  async status() {
+    const id = positional[0];
+    if (!id) die('Usage: facelessad status <id> [--wait]', 'missing_id');
+    if (flags.wait === true) { await waitFor(id); return; }
+    const d = await call('GET', '/api/v1/videos/' + encodeURIComponent(id));
+    out(d, statusLine(d));
+  },
+
+  async list() {
+    const q = new URLSearchParams();
+    if (flags.limit) q.set('limit', String(flags.limit));
+    if (flags.offset) q.set('offset', String(flags.offset));
+    const d = await call('GET', '/api/v1/videos' + (q.size ? '?' + 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)');
+  },
+
+  async download() {
+    const id = positional[0];
+    if (!id) die('Usage: facelessad download <id> [--out file.mp4]', 'missing_id');
+    const d = await call('GET', '/api/v1/videos/' + encodeURIComponent(id));
+    if (!d.url) die('Video ' + id + ' has no downloadable render yet (status: ' + d.status + ')', 'not_ready');
+    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);
+  },
+
+  async help() {
+    process.stdout.write(`${bold('facelessad')} — faceless video ads from the terminal
+
+Commands:
+  login                       Save and verify your API key (~/.facelessad, 0600)
+  balance                     Plan and credit balance
+  tools [--tool <id>]         Tool registry — styles, structures, durations
+  voices [--language --gender]Curated voice pool
+  estimate <create-flags>     Upper-bound credit cost, without creating
+  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
+
+Create flags:
+  --tool --url --text --duration --aspect --language --style --style-hint
+  --structure --hook --video-mode --brand-color --brand-name --cta --name
+  --voice --gender --no-voice --music --sfx --captions --product-image
+  --file body.json (base body; flags override)   --dry-run (print, don't send)
+
+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 —
+see ${API}/developers.
+`);
+  },
+};
+
+function statusLine(d) {
+  let s = 'Video ' + d.id + ': ' + bold(d.status);
+  if (d.phase) s += ' ' + dim('(' + d.phase + ')');
+  if (d.url) s += '\nURL (valid ~1 h): ' + d.url;
+  if (d.error) s += '\n' + d.error;
+  return s;
+}
+
+async function waitFor(id) {
+  const started = Date.now();
+  let last = '';
+  for (;;) {
+    const d = await call('GET', '/api/v1/videos/' + encodeURIComponent(id));
+    const mark = d.status + '|' + (d.phase || '');
+    const elapsed = Math.round((Date.now() - started) / 1000);
+    if (!asJson && mark !== last) {
+      process.stderr.write('[' + elapsed + 's] ' + d.status + (d.phase ? ' — ' + d.phase : '') + '\n');
+      last = mark;
+    }
+    if (d.status === 'done') { out(d, statusLine(d)); return; }
+    if (d.status === 'failed') {
+      if (asJson) { process.stdout.write(JSON.stringify(d) + '\n'); }
+      else { process.stderr.write('Error: video ' + id + ' failed' + (d.error ? ': ' + d.error : '') + '\n'); }
+      process.exit(1);
+    }
+    await new Promise((r) => setTimeout(r, 5000));
+  }
+}
+
+// ────────────────────────── run ──────────────────────────
+
+const fn = commands[cmd];
+if (!fn) die('Unknown command "' + cmd + '". Run: facelessad help', 'unknown_command');
+fn().catch((e) => die(e.message || String(e), 'unexpected'));

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@facelessad/cli",
+  "version": "1.0.0",
+  "description": "Create faceless video ads from your terminal or build scripts — the FacelessAd command line.",
+  "license": "MIT",
+  "type": "module",
+  "bin": { "facelessad": "index.js" },
+  "files": ["index.js", "README.md"],
+  "engines": { "node": ">=18" },
+  "keywords": ["facelessad", "video", "ads", "ai", "cli"],
+  "homepage": "https://facelessad.com/developers"
+}