faceless-cli 1.1.17 → 1.1.19

package/README.md

@@ -37,6 +37,7 @@ Key precedence: `--api-key` flag, then `FACELESS_API_KEY`, then the config file.
 | `faceless logout`              | Remove the saved API key                                              |
 | `faceless whoami`              | Identify the caller (team, plan, scopes)                              |
 | `faceless credits`             | Credit balance and history                                            |
+| `faceless buy-credits`         | Buy a credit pack with an agent payment token (`--pack`, `--token`)   |
 | `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                                                |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "faceless-cli",
-	"version": "1.1.17",
+	"version": "1.1.19",
 	"description": "CLI for Faceless.so: create AI faceless videos, run automated series and publish to YouTube, TikTok, Instagram and more.",
 	"type": "module",
 	"bin": {

package/src/generated/operations.json

@@ -1,6 +1,6 @@
 {
   "generatedFrom": "src/backend/api/v1/spec/registry.mjs",
-  "version": "1.1.17",
+  "version": "1.1.19",
   "baseUrl": "https://faceless.so/api/v1",
   "operations": [
     {
@@ -105,6 +105,67 @@
         }
       }
     },
+    {
+      "operationId": "buyCredits",
+      "method": "post",
+      "path": "/credits",
+      "resource": "credits",
+      "summary": "Buy a credit pack with an agent payment token",
+      "description": "Buys a credit pack and adds the credits to the team immediately, paid with a Stripe Shared Payment Token (spt_...) that the customer approved in their Link agent wallet. Packs: pack_10 ($10, 100 credits), pack_25 ($25, 275), pack_50 ($50, 600); active subscribers get more credits per pack at their plan rate. Request the token for the Faceless.so Stripe profile (profile_61UDMKC11wsLfeXaMA6UDMKCL0SQKAF3aHKCFz33IPL6) with a USD max_amount of at least the pack price. Tokens are single use: retrying with the same token never charges twice. A declined, expired or already used token returns 402 payment_failed.",
+      "scopes": [
+        "credits:write"
+      ],
+      "status": 201,
+      "idempotent": true,
+      "terminalStates": null,
+      "creditCost": "none (adds credits; charges the payment token the pack price in USD)",
+      "cli": {
+        "command": "buy-credits"
+      },
+      "mcp": {
+        "name": "faceless_buy_credits",
+        "enabled": false
+      },
+      "querySchema": null,
+      "requestSchema": {
+        "type": "object",
+        "properties": {
+          "packId": {
+            "type": "string",
+            "enum": [
+              "pack_10",
+              "pack_25",
+              "pack_50"
+            ],
+            "description": "Credit pack to buy: pack_10 ($10), pack_25 ($25) or pack_50 ($50)"
+          },
+          "paymentToken": {
+            "type": "string",
+            "pattern": "^spt_[A-Za-z0-9_]+$",
+            "description": "Stripe Shared Payment Token granted to Faceless.so by the customer's agent wallet"
+          }
+        },
+        "required": [
+          "packId",
+          "paymentToken"
+        ],
+        "additionalProperties": false
+      },
+      "requestExample": {
+        "packId": "pack_10",
+        "paymentToken": "spt_1Rx2abc"
+      },
+      "responseExample": {
+        "success": true,
+        "data": {
+          "packId": "pack_10",
+          "amountUsd": 10,
+          "creditsAdded": 100,
+          "balance": 440,
+          "paymentIntentId": "pi_3Rx2abc"
+        }
+      }
+    },
     {
       "operationId": "createVideo",
       "method": "post",
@@ -1926,6 +1987,423 @@
           "timeseriesReady": true
         }
       }
+    },
+    {
+      "operationId": "searchAds",
+      "method": "get",
+      "path": "/ads/search",
+      "resource": "ads",
+      "summary": "Search Meta ads shown in the EU and UK",
+      "description": "Searches the official Meta Ad Library by keywords in the ad text or by one advertiser's exact Facebook Page ID. Meta only returns commercial ads delivered in the EU and UK, so the country is one of those or EU_UK for all of them. Returns up to 25 ads (copy variants, delivery dates, platforms, a public Meta link), a resultToken to save or brief any of them within 15 minutes, and an opaque nextCursor. Free; each team has a daily search allowance and cached repeats do not count against it. No media files are returned.",
+      "scopes": [
+        "ads:read"
+      ],
+      "status": 200,
+      "idempotent": false,
+      "terminalStates": null,
+      "creditCost": "none",
+      "cli": {
+        "command": "ads search"
+      },
+      "mcp": {
+        "name": "faceless_search_ads",
+        "enabled": false
+      },
+      "querySchema": {
+        "type": "object",
+        "properties": {
+          "q": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100,
+            "description": "Words in the ad text. Send q or pageId, not both."
+          },
+          "pageId": {
+            "type": "string",
+            "pattern": "^[1-9]\\d{0,29}$",
+            "description": "One advertiser's exact Facebook Page ID (from its Ad Library link, view_all_page_id)."
+          },
+          "country": {
+            "type": "string",
+            "enum": [
+              "EU_UK",
+              "AT",
+              "BE",
+              "BG",
+              "HR",
+              "CY",
+              "CZ",
+              "DK",
+              "EE",
+              "FI",
+              "FR",
+              "DE",
+              "GR",
+              "HU",
+              "IE",
+              "IT",
+              "LV",
+              "LT",
+              "LU",
+              "MT",
+              "NL",
+              "PL",
+              "PT",
+              "RO",
+              "SK",
+              "SI",
+              "ES",
+              "SE",
+              "GB"
+            ],
+            "default": "EU_UK",
+            "description": "Where the ad was shown"
+          },
+          "mediaType": {
+            "type": "string",
+            "enum": [
+              "ALL",
+              "IMAGE",
+              "VIDEO"
+            ],
+            "default": "ALL"
+          },
+          "platform": {
+            "type": "string",
+            "enum": [
+              "ALL",
+              "FACEBOOK",
+              "INSTAGRAM",
+              "MESSENGER",
+              "AUDIENCE_NETWORK",
+              "THREADS",
+              "WHATSAPP"
+            ],
+            "default": "ALL"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "ACTIVE",
+              "INACTIVE",
+              "ALL"
+            ],
+            "default": "ACTIVE",
+            "description": "ACTIVE: running now"
+          },
+          "cursor": {
+            "type": "string",
+            "format": "uuid",
+            "description": "nextCursor from the previous page of the same search; keep every other parameter unchanged."
+          }
+        },
+        "additionalProperties": false
+      },
+      "requestSchema": null,
+      "requestExample": null,
+      "responseExample": {
+        "success": true,
+        "data": {
+          "items": [
+            {
+              "adId": "2716161098763684",
+              "pageId": "123456789",
+              "pageName": "Example brand",
+              "bodies": [
+                "Turn one idea into a week of videos."
+              ],
+              "titles": [
+                "Videos on autopilot"
+              ],
+              "captions": [],
+              "descriptions": [],
+              "startedAt": "2026-08-01T00:00:00.000Z",
+              "stoppedAt": null,
+              "platforms": [
+                "FACEBOOK",
+                "INSTAGRAM"
+              ],
+              "mediaType": null,
+              "observedStatus": "ACTIVE",
+              "sourceUrl": "https://www.facebook.com/ads/library/?id=2716161098763684",
+              "fetchedAt": "2026-09-26T10:00:00.000Z",
+              "savedId": null
+            }
+          ],
+          "resultToken": "22df1b25-533f-4bd7-862a-aedc4a4ea0cc",
+          "expiresAt": "2026-09-26T10:15:00.000Z",
+          "nextCursor": "0b6f3c1e-8f4a-4c55-9e0b-7d2a1c9e4f10"
+        }
+      }
+    },
+    {
+      "operationId": "listSavedAds",
+      "method": "get",
+      "path": "/saved-ads",
+      "resource": "ads",
+      "summary": "List the team's saved ads",
+      "description": "Returns the ads the team saved from Meta Ad Library searches, newest first, 24 per page, with each ad's details as Meta showed them when it was saved. Filter by one advertiser with pageId. Works even when fresh search is paused.",
+      "scopes": [
+        "ads:read"
+      ],
+      "status": 200,
+      "idempotent": false,
+      "terminalStates": null,
+      "creditCost": "none",
+      "cli": {
+        "command": "ads saved"
+      },
+      "mcp": {
+        "name": "faceless_list_saved_ads",
+        "enabled": false
+      },
+      "querySchema": {
+        "type": "object",
+        "properties": {
+          "pageId": {
+            "type": "string",
+            "pattern": "^[1-9]\\d{0,29}$",
+            "description": "Only this advertiser's ads"
+          },
+          "page": {
+            "type": "integer",
+            "minimum": 1,
+            "default": 1
+          }
+        },
+        "additionalProperties": false
+      },
+      "requestSchema": null,
+      "requestExample": null,
+      "responseExample": {
+        "success": true,
+        "data": {
+          "items": [
+            {
+              "id": "665f1b2a9c31a2b3c4d5f001",
+              "ad": {
+                "adId": "2716161098763684",
+                "pageName": "Example brand"
+              },
+              "savedAt": "2026-09-26T10:01:00.000Z"
+            }
+          ],
+          "advertisers": [
+            {
+              "pageId": "123456789",
+              "pageName": "Example brand"
+            }
+          ],
+          "savedCount": 1,
+          "savedLimit": 500,
+          "page": 1,
+          "pages": 1
+        }
+      }
+    },
+    {
+      "operationId": "saveAd",
+      "method": "post",
+      "path": "/saved-ads",
+      "resource": "ads",
+      "summary": "Save an ad from a search",
+      "description": "Saves one ad from a searchAds result to the team's saved ads, using that search's resultToken (valid 15 minutes; search again after that). Saving the same ad twice returns the first save. A team can keep 500 saved ads.",
+      "scopes": [
+        "ads:write"
+      ],
+      "status": 200,
+      "idempotent": false,
+      "terminalStates": null,
+      "creditCost": "none",
+      "cli": {
+        "command": "ads save"
+      },
+      "mcp": {
+        "name": "faceless_save_ad",
+        "enabled": false
+      },
+      "querySchema": null,
+      "requestSchema": {
+        "type": "object",
+        "properties": {
+          "adId": {
+            "type": "string",
+            "pattern": "^[1-9]\\d{0,29}$",
+            "description": "adId from searchAds"
+          },
+          "resultToken": {
+            "type": "string",
+            "format": "uuid",
+            "description": "resultToken of the search page that returned the ad"
+          }
+        },
+        "required": [
+          "adId",
+          "resultToken"
+        ],
+        "additionalProperties": false
+      },
+      "requestExample": {
+        "adId": "2716161098763684",
+        "resultToken": "22df1b25-533f-4bd7-862a-aedc4a4ea0cc"
+      },
+      "responseExample": {
+        "success": true,
+        "data": {
+          "id": "665f1b2a9c31a2b3c4d5f001",
+          "ad": {
+            "adId": "2716161098763684",
+            "pageName": "Example brand"
+          },
+          "savedAt": "2026-09-26T10:01:00.000Z"
+        }
+      }
+    },
+    {
+      "operationId": "deleteSavedAd",
+      "method": "delete",
+      "path": "/saved-ads/{id}",
+      "resource": "ads",
+      "summary": "Remove a saved ad",
+      "description": "Removes one of the team's saved ads. An id the team does not have answers 404.",
+      "scopes": [
+        "ads:write"
+      ],
+      "status": 200,
+      "idempotent": false,
+      "terminalStates": null,
+      "creditCost": "none",
+      "cli": {
+        "command": "ads unsave"
+      },
+      "mcp": {
+        "name": "faceless_delete_saved_ad",
+        "enabled": false
+      },
+      "querySchema": null,
+      "requestSchema": null,
+      "requestExample": null,
+      "responseExample": {
+        "success": true,
+        "data": {
+          "deleted": true
+        }
+      }
+    },
+    {
+      "operationId": "createAdBrief",
+      "method": "post",
+      "path": "/ads/briefs",
+      "resource": "ads",
+      "summary": "Write an ad brief for your brand from a competitor's ad",
+      "description": "Writes an original ad brief (hook, promise, script, visual direction, call to action) for the team's brand, inspired by one ad from searchAds or the saved ads. Only the ad's approach carries over: every claim comes from the brand description you send, and the advertiser's name, offers, prices and results never appear. target sizes the script: motion (20 s motion-graphics ad), product-video (30 s narrated video), ugc (20 s creator talking to camera) or image (one static ad). Free; use the brief with createVideo or any other operation. 30 briefs per hour.",
+      "scopes": [
+        "ads:write"
+      ],
+      "status": 200,
+      "idempotent": false,
+      "terminalStates": null,
+      "creditCost": "none",
+      "cli": {
+        "command": "ads brief"
+      },
+      "mcp": {
+        "name": "faceless_create_ad_brief",
+        "enabled": false
+      },
+      "querySchema": null,
+      "requestSchema": {
+        "type": "object",
+        "properties": {
+          "adId": {
+            "type": "string",
+            "pattern": "^[1-9]\\d{0,29}$"
+          },
+          "resultToken": {
+            "type": "string",
+            "format": "uuid",
+            "description": "From searchAds; send this or savedId"
+          },
+          "savedId": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "A saved ad's id; send this or resultToken"
+          },
+          "target": {
+            "type": "string",
+            "enum": [
+              "motion",
+              "product-video",
+              "ugc",
+              "image"
+            ],
+            "description": "What the brief is for"
+          },
+          "brand": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 120
+              },
+              "description": {
+                "type": "string",
+                "minLength": 20,
+                "maxLength": 1500,
+                "description": "What you sell and who it is for. The only source of claims."
+              },
+              "website": {
+                "type": "string",
+                "maxLength": 300
+              }
+            },
+            "required": [
+              "name",
+              "description"
+            ],
+            "additionalProperties": false,
+            "description": "Your brand"
+          },
+          "notes": {
+            "type": "string",
+            "maxLength": 600,
+            "description": "A real offer, a feature to lead with, a tone"
+          }
+        },
+        "required": [
+          "adId",
+          "target",
+          "brand"
+        ],
+        "additionalProperties": false
+      },
+      "requestExample": {
+        "adId": "2716161098763684",
+        "resultToken": "22df1b25-533f-4bd7-862a-aedc4a4ea0cc",
+        "target": "product-video",
+        "brand": {
+          "name": "Acme Coffee",
+          "description": "Small-batch coffee beans roasted to order and shipped within two days."
+        }
+      },
+      "responseExample": {
+        "success": true,
+        "data": {
+          "brief": {
+            "hook": "Your coffee was roasted months ago",
+            "benefit": "Beans roasted the day you order them, at your door two days later.",
+            "script": "Your coffee was roasted months ago. Ours is roasted when you order. It reaches you two days later. Taste the difference.",
+            "visualDirection": "Close-ups of beans leaving the roaster, a kraft bag being sealed, a morning pour.",
+            "cta": "Order a fresh bag"
+          },
+          "source": {
+            "adId": "2716161098763684",
+            "pageName": "Example brand",
+            "sourceUrl": "https://www.facebook.com/ads/library/?id=2716161098763684"
+          }
+        }
+      }
     }
   ]
 }

package/src/index.mjs

@@ -286,6 +286,16 @@ program
 		print(result, { json: cmd.optsWithGlobals().json });
 	});
 
+program
+	.command("buy-credits")
+	.description(getOp("buyCredits").summary)
+	.requiredOption("--pack <id>", "credit pack: pack_10, pack_25 or pack_50")
+	.requiredOption("--token <spt>", "Stripe Shared Payment Token (spt_...) from your agent wallet")
+	.action(async (opts, cmd) => {
+		const result = await execute("buyCredits", { body: { packId: opts.pack, paymentToken: opts.token } }, cmd);
+		print(result, { json: cmd.optsWithGlobals().json });
+	});
+
 const videos = program.command("videos").description("Faceless video projects");
 
 withWaitFlags(
@@ -669,6 +679,76 @@ program
 		print(result, { json: cmd.optsWithGlobals().json });
 	});
 
+const ads = program.command("ads").description("Meta Ad Library: search competitor ads, keep the good ones, brief your own");
+
+ads.command("search [keywords]")
+	.description(getOp("searchAds").summary)
+	.option("--page-id <id>", "one advertiser's Facebook Page ID instead of keywords")
+	.option("--country <code>", "EU_UK (default) or one EU/UK country code, e.g. DE")
+	.addOption(new Option("--media <type>", "media type").choices(["ALL", "IMAGE", "VIDEO"]))
+	.option("--platform <name>", "ALL (default), FACEBOOK, INSTAGRAM, MESSENGER, AUDIENCE_NETWORK, THREADS or WHATSAPP")
+	.addOption(new Option("--status <status>", "delivery status").choices(["ACTIVE", "INACTIVE", "ALL"]))
+	.option("--cursor <cursor>", "nextCursor from the previous page of the same search")
+	.action(async (keywords, opts, cmd) => {
+		const query = {
+			q: keywords,
+			pageId: opts.pageId,
+			country: opts.country,
+			mediaType: opts.media,
+			platform: opts.platform,
+			status: opts.status,
+			cursor: opts.cursor,
+		};
+		const result = await execute("searchAds", { query }, cmd);
+		print(result, { json: cmd.optsWithGlobals().json });
+	});
+
+ads.command("saved")
+	.description(getOp("listSavedAds").summary)
+	.option("--page-id <id>", "only this advertiser's ads")
+	.option("--page <n>", "page number", toInt)
+	.action(async (opts, cmd) => {
+		const result = await execute("listSavedAds", { query: { pageId: opts.pageId, page: opts.page } }, cmd);
+		print(result, { json: cmd.optsWithGlobals().json });
+	});
+
+ads.command("save <adId>")
+	.description(getOp("saveAd").summary)
+	.requiredOption("--result-token <token>", "resultToken from the search that returned the ad")
+	.action(async (adId, opts, cmd) => {
+		const result = await execute("saveAd", { body: { adId, resultToken: opts.resultToken } }, cmd);
+		print(result, { json: cmd.optsWithGlobals().json });
+	});
+
+ads.command("unsave <savedId>")
+	.description(getOp("deleteSavedAd").summary)
+	.action(async (id, _opts, cmd) => {
+		const result = await execute("deleteSavedAd", { pathParams: { id } }, cmd);
+		print(result, { json: cmd.optsWithGlobals().json });
+	});
+
+ads.command("brief <adId>")
+	.description(getOp("createAdBrief").summary)
+	.addOption(new Option("--target <target>", "what the brief is for").choices(["motion", "product-video", "ugc", "image"]).makeOptionMandatory())
+	.requiredOption("--brand <name>", "your brand or product name")
+	.requiredOption("--about <text>", "what you sell and who it is for (the only source of claims)")
+	.option("--website <url>", "your website")
+	.option("--result-token <token>", "resultToken from searchAds (or use --saved-id)")
+	.option("--saved-id <id>", "a saved ad's id (or use --result-token)")
+	.option("--notes <text>", "a real offer, a feature to lead with, a tone")
+	.action(async (adId, opts, cmd) => {
+		const body = {
+			adId,
+			resultToken: opts.resultToken,
+			savedId: opts.savedId,
+			target: opts.target,
+			brand: compact({ name: opts.brand, description: opts.about, website: opts.website }),
+			notes: opts.notes,
+		};
+		const result = await execute("createAdBrief", { body }, cmd);
+		print(result, { json: cmd.optsWithGlobals().json });
+	});
+
 program
 	.command("mcp")
 	.description("Start the local Faceless MCP server over stdio")