faceless-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Faceless.so
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# Faceless CLI
+
+Command line client for the [Faceless.so](https://faceless.so) public API: create AI faceless videos from a script, run automated series and publish to YouTube, TikTok, Instagram, X, Facebook, LinkedIn and Threads. Also ships a local MCP server so agents can use Faceless as tools.
+
+API reference: https://faceless.so/api/v1/openapi.json
+
+## Install
+
+```bash
+npm install -g faceless-cli
+```
+
+Requires Node 18 or newer. The package installs two equivalent commands: `faceless` and `fcl`.
+
+## Authentication
+
+Create an API key in your team settings at https://faceless.so/team, then either log in once:
+
+```bash
+faceless login
+```
+
+This verifies the key against `GET /me` and saves it to `~/.faceless/config.json` (file mode 600). Or use an environment variable instead:
+
+```bash
+export FACELESS_API_KEY=fl_live_...
+faceless whoami
+```
+
+Key precedence: `--api-key` flag, then `FACELESS_API_KEY`, then the config file. The base URL can be overridden with `--api-url` or `FACELESS_API_URL`. Use `faceless logout` to remove the saved key.
+
+## Commands
+
+| Command                        | Description                                                           |
+| ------------------------------ | --------------------------------------------------------------------- |
+| `faceless login`               | Save an API key to `~/.faceless/config.json` (verified against `/me`) |
+| `faceless logout`              | Remove the saved API key                                              |
+| `faceless whoami`              | Identify the caller (team, plan, scopes)                              |
+| `faceless credits`             | Credit balance and history                                            |
+| `faceless videos create`       | Create a faceless video from a script (charges credits)               |
+| `faceless videos captions`     | Caption an existing video or audio URL                                |
+| `faceless videos list`         | List the team's videos                                                |
+| `faceless videos get <id>`     | Get one video                                                         |
+| `faceless videos update <id>`  | Update a video's name or per-platform post metadata                   |
+| `faceless videos status <id>`  | Poll video generation progress (`--wait`)                             |
+| `faceless videos render <id>`  | Render a generated video to MP4 (`--wait`)                            |
+| `faceless videos delete <id>`  | Delete a video                                                        |
+| `faceless renders get <id>`    | Poll render progress (`--wait`)                                       |
+| `faceless series create`       | Create an automated video series                                      |
+| `faceless series list`         | List the team's series                                                |
+| `faceless series get <id>`     | Get one series                                                        |
+| `faceless series update <id>`  | Update a series (`--paused` / `--no-paused` to pause or resume)       |
+| `faceless series delete <id>`  | Delete a series                                                       |
+| `faceless series generate <id>`| Generate the next episode now (`--wait`)                              |
+| `faceless series episodes <id>`| List a series' episodes                                               |
+| `faceless posts publish`       | Publish a rendered video to a platform now                            |
+| `faceless posts schedule`      | Schedule a video to one or more platforms                             |
+| `faceless posts cancel <videoId>` | Cancel a scheduled post                                            |
+| `faceless calendar`            | Posting calendar for a date range                                     |
+| `faceless accounts`            | List connected social accounts                                        |
+| `faceless voices`              | List TTS voices                                                       |
+| `faceless options`             | List option catalogs (styles, niches, models, ...)                    |
+| `faceless assets create`       | Register a media asset by URL                                         |
+| `faceless analytics`           | Cross-platform posting analytics                                      |
+| `faceless mcp`                 | Start the local MCP server over stdio                                 |
+
+Global options: `--json`, `--api-key <key>`, `--api-url <url>`. Run any command with `--help` for its flags.
+
+## Quickstart: create, render, publish
+
+```bash
+# Pick a voice and see what everything costs
+faceless voices
+faceless options --kind models
+
+# 1. Create a video from a script and wait for generation to finish
+#    (storyboard 20 credits, motion_lite 50, motion_pro 100)
+faceless videos create \
+  --script "Did you know the ocean has lakes and rivers of its own? ..." \
+  --voice-id EXAVITQu4vr4xnSDxMaL \
+  --model storyboard --wait
+
+# 2. Render it to MP4 and wait for the download URL
+faceless videos render 665f1b2a9c31a2b3c4d5e801 --wait
+
+# 3a. Publish it to YouTube right now
+faceless accounts
+faceless posts publish --video-id 665f1b2a9c31a2b3c4d5e801 \
+  --platform youtube --title "The ocean has rivers underwater"
+
+# 3b. Or set per-platform metadata and schedule it for later
+faceless videos update 665f1b2a9c31a2b3c4d5e801 \
+  --youtube-title "The ocean has rivers underwater" \
+  --tiktok-title "underwater rivers are real #ocean"
+faceless posts schedule --video-id 665f1b2a9c31a2b3c4d5e801 \
+  --platforms youtube,tiktok --scheduled-time 2026-08-01T18:00:00Z
+
+# What is queued this week?
+faceless calendar --start-date 2026-08-01 --end-date 2026-08-07
+```
+
+More flows:
+
+```bash
+# Caption footage you already have
+faceless videos captions --video-url https://example.com/clip.mp4 --wait
+
+# A set-and-forget channel: one episode per day at 6pm
+faceless series create --name "Deep sea facts" \
+  --source "Facts & stories" --niche "Ocean facts" \
+  --voice EXAVITQu4vr4xnSDxMaL --duration 60 \
+  --auto-post-time 18:00 --timezone America/New_York
+faceless series generate 665f1b2a9c31a2b3c4d5e901 --wait
+faceless series episodes 665f1b2a9c31a2b3c4d5e901
+```
+
+## JSON output and exit codes
+
+Pass `--json` to print the raw API envelope (`{ "success": true, "data": ... }`). When stdout is not a TTY (pipes, scripts, CI), JSON is printed automatically, so `faceless videos list | jq` just works.
+
+Errors are written to stderr as `error (<type>): <message>` with these exit codes:
+
+| Exit code | Meaning                                                                |
+| --------- | ---------------------------------------------------------------------- |
+| `0`       | Success                                                                |
+| `1`       | Any other error (invalid input, not found, conflict, network, timeout) |
+| `2`       | `unauthorized` or `forbidden_scope`                                    |
+| `3`       | `insufficient_credits`                                                 |
+| `4`       | `rate_limited`                                                         |
+
+On HTTP 429 the client retries once after the `Retry-After` interval (capped at 30 seconds). Every mutating request carries an auto-generated `Idempotency-Key` (override with `--idempotency-key`), so retries can never double-charge credits.
+
+## Waiting for async work
+
+Generation and rendering are asynchronous. `--wait` (with `--timeout <sec>`, default 600) polls every 5 seconds until a terminal state:
+
+- `videos create --wait` and `videos captions --wait` poll `videos status` until the video is `completed` or `failed`
+- `videos render <id> --wait` polls `renders get` with the returned renderId until `done` or `error`
+- `series generate <id> --wait` polls the created episode's video status
+- `videos status <id> --wait` and `renders get <id> --wait` do the same for something already in flight
+
+`posts publish` is synchronous and returns the post URL directly.
+
+## MCP server
+
+The CLI doubles as a local MCP server over stdio, exposing the Faceless API as tools (`faceless_create_video`, `faceless_render_video`, `faceless_publish_post`, and more). Add it to Claude Code:
+
+```bash
+claude mcp add faceless -- npx -y faceless-cli mcp
+```
+
+Make sure `FACELESS_API_KEY` is set in the environment (or run `faceless login` first).
+
+Prefer a hosted option? Faceless also serves a remote MCP endpoint at `https://faceless.so/api/v1/mcp` (Authorization: `Bearer fl_live_...`), no local install needed.
+
+## Links
+
+- Faceless.so: https://faceless.so
+- API keys: https://faceless.so/team
+- OpenAPI spec: https://faceless.so/api/v1/openapi.json

package/bin/faceless.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../src/index.mjs";

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "faceless-cli",
+  "version": "1.0.0",
+  "description": "CLI for Faceless.so: create AI faceless videos, run automated series and publish to YouTube, TikTok, Instagram and more.",
+  "type": "module",
+  "bin": {
+    "faceless": "bin/faceless.js",
+    "fcl": "bin/faceless.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "homepage": "https://faceless.so",
+  "keywords": [
+    "faceless",
+    "cli",
+    "mcp",
+    "ai",
+    "video",
+    "faceless-video",
+    "youtube",
+    "tiktok",
+    "social-media",
+    "scheduling"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "commander": "^13.0.0"
+  }
+}

package/src/client.mjs

@@ -0,0 +1,129 @@
+import { randomUUID } from "node:crypto";
+
+export class CliError extends Error {
+  constructor(type, message, status) {
+    super(message);
+    this.name = "CliError";
+    this.type = type || "internal_error";
+    this.status = status;
+  }
+}
+
+export function exitCodeFor(err) {
+  const type = err && err.type;
+  if (type === "unauthorized" || type === "forbidden_scope") return 2;
+  if (type === "insufficient_credits") return 3;
+  if (type === "rate_limited") return 4;
+  return 1;
+}
+
+function typeForStatus(status) {
+  switch (status) {
+    case 400:
+      return "invalid_input";
+    case 401:
+      return "unauthorized";
+    case 402:
+      return "insufficient_credits";
+    case 403:
+      return "forbidden_scope";
+    case 404:
+      return "not_found";
+    case 409:
+      return "conflict";
+    case 429:
+      return "rate_limited";
+    default:
+      return "internal_error";
+  }
+}
+
+function buildUrl(baseUrl, path, query) {
+  const url = new URL(baseUrl + path);
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value === undefined || value === null || value === "") continue;
+      url.searchParams.set(key, String(value));
+    }
+  }
+  return url;
+}
+
+export function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function retryAfterMs(res) {
+  const header = res.headers.get("retry-after");
+  let seconds = Number(header);
+  if (!Number.isFinite(seconds) || seconds < 0) seconds = 1;
+  return Math.min(seconds, 30) * 1000;
+}
+
+export async function request({ method, path, query, body, apiKey, baseUrl, idempotencyKey }) {
+  if (!apiKey) {
+    throw new CliError(
+      "unauthorized",
+      'No API key configured. Run "faceless login" or set FACELESS_API_KEY.'
+    );
+  }
+
+  const url = buildUrl(baseUrl, path, query);
+  const headers = { Authorization: `Bearer ${apiKey}` };
+  const httpMethod = method.toUpperCase();
+  const init = { method: httpMethod, headers };
+  if (body !== undefined && body !== null) {
+    headers["Content-Type"] = "application/json";
+    init.body = JSON.stringify(body);
+  }
+  // Every mutating request carries an Idempotency-Key so a retry can never be
+  // applied (or charge credits) twice. Ops without server-side idempotency
+  // simply ignore the header. A user-provided --idempotency-key wins.
+  const isMutating = httpMethod !== "GET" && httpMethod !== "HEAD";
+  if (isMutating && !idempotencyKey) idempotencyKey = randomUUID();
+  if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
+
+  let res;
+  try {
+    res = await fetch(url, init);
+    // Retry a rate-limited request once. Insufficient credits is 402 (never
+    // retried); mutating retries are safe because of the Idempotency-Key.
+    if (res.status === 429) {
+      await sleep(retryAfterMs(res));
+      res = await fetch(url, init);
+    }
+  } catch (err) {
+    throw new CliError("internal_error", `Network error calling ${url.origin}: ${err.message}`);
+  }
+
+  const text = await res.text();
+  let parsed = null;
+  if (text) {
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      throw new CliError(
+        typeForStatus(res.status),
+        `Unexpected non-JSON response (HTTP ${res.status})`,
+        res.status
+      );
+    }
+  }
+
+  if (parsed && parsed.success === false) {
+    const e = parsed.error || {};
+    throw new CliError(
+      e.type || typeForStatus(res.status),
+      e.message || `Request failed (HTTP ${res.status})`,
+      res.status
+    );
+  }
+  if (!res.ok) {
+    throw new CliError(
+      typeForStatus(res.status),
+      `Request failed (HTTP ${res.status})`,
+      res.status
+    );
+  }
+  return parsed;
+}

package/src/config.mjs

@@ -0,0 +1,47 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const DEFAULT_BASE_URL = "https://faceless.so/api/v1";
+export const CONFIG_DIR = path.join(os.homedir(), ".faceless");
+export const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
+
+export function loadConfig() {
+  try {
+    const raw = fs.readFileSync(CONFIG_PATH, "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+export function saveConfig(partial) {
+  const config = { ...loadConfig(), ...partial };
+  for (const key of Object.keys(config)) {
+    if (config[key] === undefined || config[key] === null) delete config[key];
+  }
+  fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + "\n", {
+    mode: 0o600,
+  });
+  try {
+    fs.chmodSync(CONFIG_PATH, 0o600);
+  } catch {
+    /* best effort on platforms without chmod */
+  }
+  return config;
+}
+
+export function resolveApiKey(flags = {}) {
+  if (flags.apiKey) return flags.apiKey;
+  if (process.env.FACELESS_API_KEY) return process.env.FACELESS_API_KEY;
+  const config = loadConfig();
+  return config.apiKey || null;
+}
+
+export function resolveBaseUrl(flags = {}) {
+  const url =
+    flags.apiUrl || process.env.FACELESS_API_URL || loadConfig().baseUrl || DEFAULT_BASE_URL;
+  return String(url).replace(/\/+$/, "");
+}