@adsuploader/cli 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# Ads Uploader CLI
+
+Create and manage Meta ads from the command line. Same pipeline as the web app.
+
+## Install
+
+```bash
+npm install -g @adsuploader/cli
+```
+
+Requires Node.js 18 or later.
+
+## Quick Start
+
+```bash
+ads login                       # authenticate via browser
+ads accounts                    # list ad accounts
+ads account act_123456          # set default account
+
+ads upload hero.jpg banner.mp4  # upload media
+ads create:preview spec.json    # preview what would be created
+ads create spec.json            # create ads
+```
+
+## Documentation
+
+Full documentation including the spec file reference, campaign structure, text configuration, and all available options is at [adsuploader.com/docs/ad-configuration/cli](https://adsuploader.com/docs/ad-configuration/cli).
+
+## Using with AI
+
+This package includes a `SKILL.md` file that describes every command and option for AI agents (Claude Code, Cursor, etc.). Point your AI tool at `node_modules/@adsuploader/cli/SKILL.md` to get started.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `ads login` | Authenticate via browser |
+| `ads accounts` | List ad accounts |
+| `ads account <id>` | Set default account |
+| `ads campaigns` | List campaigns |
+| `ads campaign <id>` | Show ad sets in a campaign |
+| `ads adset <id>` | Show ads in an ad set |
+| `ads ad <id>` | Ad details and creative |
+| `ads presets` | List saved presets |
+| `ads upload <files...>` | Upload images and videos |
+| `ads uploads` | List recent upload batches |
+| `ads create spec.json` | Create ads from spec |
+| `ads create:preview spec.json` | Dry run |
+| `ads create:interactive` | Guided wizard |
+| `ads jobs <id>` | Check job status |

package/SKILL.md

@@ -0,0 +1,517 @@
+---
+name: ads
+description: Create and manage Facebook/Meta ads using the Ads Uploader CLI. Upload media, preview configurations, create ads, browse campaigns and ad sets.
+homepage: https://adsuploader.com
+---
+
+## Setup
+
+```bash
+npm install -g @adsuploader/cli
+```
+
+## Authentication
+
+```bash
+# 1. Login (opens browser OAuth flow)
+ads login
+
+# 2. List ad accounts
+ads accounts
+
+# 3. Set default account
+ads account act_123456789
+```
+
+Credentials are stored at `~/.config/adsuploader/credentials.json`. Check current auth:
+
+```bash
+ads whoami
+ads config
+```
+
+---
+
+## Core Workflow
+
+Every ad creation follows three steps:
+
+### 1. Upload media
+
+```bash
+ads upload hero.jpg banner.mp4
+ads upload ./my-creatives/          # entire directory
+```
+
+Returns a **batch ID** (e.g. `batch_abc123`) — you'll need this for the spec file. Files are uploaded directly to the selected ad account's Facebook media library, so the batch ID is tied to that account.
+
+### 2. Preview (dry run)
+
+```bash
+ads create:preview spec.json
+```
+
+Shows exactly what would be created without touching Facebook. **Always preview first.**
+
+### 3. Create ads
+
+```bash
+ads create spec.json
+```
+
+Ads are created **ACTIVE** by default. Use `--status PAUSED` to create them paused. Returns a job ID for progress tracking.
+
+---
+
+## Command Reference
+
+### Auth
+| Command | Description |
+|---------|-------------|
+| `login` | Authenticate via browser |
+| `logout` | Clear credentials |
+| `whoami` | Show current user |
+| `config` | Show configuration |
+
+### Browsing
+| Command | Description |
+|---------|-------------|
+| `accounts` | List ad accounts |
+| `account <id>` | Set default account |
+| `campaigns` | List active campaigns (`--status all` for all, `--search <text>` to filter) |
+| `campaign <id>` | Show ad sets in a campaign |
+| `adsets --campaign <id>` | List ad sets (supports `--search`, `--status`) |
+| `adset <adSetId>` | Show ads in an ad set |
+| `ad <adId>` | Ad details + creative config |
+| `presets` | List saved API presets (or `presets <id>` for details) |
+| `text-presets` | List saved text presets (or `text-presets <id>` for details) |
+| `uploads` | List recent upload batches (or `uploads <batchId>` for details) |
+
+### Actions
+| Command | Description |
+|---------|-------------|
+| `upload <files...>` | Upload images/videos |
+| `create spec.json` | Create ads from spec |
+| `create:preview spec.json` | Dry run — show what would be created |
+| `create:interactive` | Guided wizard (accepts all create flags) |
+
+### Jobs
+| Command | Description |
+|---------|-------------|
+| `jobs <jobId>` | Check job status |
+| `jobs <jobId> --follow` | Follow progress in real-time |
+| `jobs cancel <jobId>` | Cancel a running job |
+
+### Create Flags
+| Flag | Description |
+|------|-------------|
+| `--account <id>` | Override default ad account |
+| `--preset <id>` | API preset ID (alternative to spec file) |
+| `--text-preset <id>` | Text preset ID |
+| `--copy-from <adId>` | Ad ID to copy settings from |
+| `--upload <batchId>` | Upload batch ID |
+| `--status <PAUSED\|ACTIVE>` | Set ad status (default: ACTIVE) |
+| `--pause-at <level>` | Pause level: `ad` (default), `adSet`, or `campaign` |
+| `--daily-budget <amount>` | Override daily budget (currency units) |
+| `--bid-amount <amount>` | Override bid/cost cap (currency units) |
+| `--text-file <path>` | Load text config from a JSON file |
+
+### Common Flags
+| Flag | Description |
+|------|-------------|
+| `--account <id>` | Override default ad account |
+| `--json` | Raw JSON output (available on most commands) |
+
+### Do not use `--json`
+
+The `--json` flag is for shell scripts piping to `jq`. **Never use it** — the human-readable output already contains all the information you need (batch IDs, job progress, results). For `create`, `--json` replaces the live progress log with raw NDJSON poll dumps which are unreadable.
+
+---
+
+## Spec File Format
+
+The JSON spec controls ad creation. Only `uploadId` and a template source are required.
+
+### Minimal Spec
+
+```json
+{
+  "adPresetId": "preset_id_here",
+  "uploadId": "batch_abc123"
+}
+```
+
+### Template Source (pick one)
+
+| Field | Description |
+|-------|-------------|
+| `adPresetId` | Saved API preset ID (locks campaign, ad set, ad config) |
+| `copyFromAd` | Facebook ad ID to copy settings from |
+
+When using `copyFromAd`, provide the upload batch and optionally campaign/ad set:
+```json
+{
+  "copyFromAd": "120233848667930472",
+  "uploadId": "batch_abc123",
+  "campaign": { "id": "120233848666410472" },
+  "adSet": { "id": "120233848666620472" }
+}
+```
+
+### Campaign Structure
+
+**Single campaign** (default): ads go into the template ad's campaign, or a new campaign if `campaign.name` is provided.
+
+**Multi-campaign modes** — use `campaign.mode` with a `campaigns` array:
+
+```json
+{
+  "campaign": {
+    "mode": "duplicate",
+    "campaigns": [
+      { "name": "Campaign A" },
+      { "name": "Campaign B" }
+    ]
+  }
+}
+```
+
+| Mode | Behavior |
+|------|----------|
+| `"single"` | Default — one campaign |
+| `"duplicate"` | All media duplicated into each campaign |
+| `"split"` | Media split across campaigns |
+
+### Ad Set Modes
+
+**Single ad set** (default):
+```json
+{ "adSet": { "name": "My Ad Set" } }
+```
+
+**Existing ad set:**
+```json
+{ "adSet": { "id": "120233848666620472" } }
+```
+
+**Per upload** (one ad set per file):
+```json
+{ "adSet": { "mode": "perUpload" } }
+```
+
+**Auto group** (split evenly):
+```json
+{ "adSet": { "mode": "autoGroup", "adsPerAdSet": 5 } }
+```
+
+**Custom groups:**
+```json
+{
+  "adSet": {
+    "groups": [
+      { "name": "Images", "media": ["hero.jpg", "banner.jpg"] },
+      { "name": "Video", "media": ["promo.mp4"] }
+    ]
+  }
+}
+```
+
+**Ad set naming pattern** (for multi-ad-set modes):
+```json
+{ "adSet": { "mode": "perUpload", "namePattern": "Ad Set {index:01}" } }
+```
+
+**Variant grouping** (group ads by variation identifier into the same ad set):
+```json
+{ "adSet": { "mode": "autoGroup", "groupVariations": true, "variationIdentifier": "-" } }
+```
+
+### Budget / Bid Override
+
+Values in account currency units (e.g. `50` = $50). Only one at a time.
+
+```json
+{ "adSet": { "dailyBudget": 50 } }
+{ "adSet": { "bidAmount": 5 } }
+```
+
+Also available as CLI flags: `--daily-budget 50` or `--bid-amount 5`.
+
+### Text Configuration
+
+**Common text** (same for all ads):
+```json
+{
+  "texts": {
+    "common": {
+      "headlines": ["Headline 1", "Headline 2"],
+      "bodies": ["Primary text"],
+      "descriptions": ["Description"]
+    },
+    "strategy": "flexible"
+  }
+}
+```
+
+**Per-ad text** (unique per file):
+```json
+{
+  "texts": {
+    "perAd": {
+      "hero.jpg": {
+        "headlines": ["Hero Headline"],
+        "bodies": ["Hero copy"],
+        "descriptions": ["Hero desc"],
+        "cta": "LEARN_MORE",
+        "link": "https://example.com/hero",
+        "urlTags": "utm_content=hero"
+      },
+      "banner.jpg": {
+        "headlines": ["Banner Headline"],
+        "bodies": ["Banner copy"]
+      }
+    }
+  }
+}
+```
+
+Per-ad keys are **filenames** (not full paths). Unspecified fields inherit from the template ad.
+
+**Text preset:**
+```json
+{ "textPresetId": "preset_id_here" }
+```
+
+Cannot combine `textPresetId` with `texts`.
+
+**Strategy options:**
+- `"flexible"` (default) — Meta optimizes across text variations (multiple headlines/bodies become options Facebook mixes)
+- `"separate"` — each text combination becomes a separate ad
+
+Per-ad entries support: `headlines`, `bodies`, `descriptions`, `cta`, `link`, `displayUrl`, `urlTags`. Unspecified fields inherit from the template ad.
+
+### CTA and Links
+
+Top-level CTA applies to all ads (overridden by per-ad CTA):
+```json
+{
+  "cta": {
+    "type": "SHOP_NOW",
+    "link": "https://example.com",
+    "displayUrl": "example.com"
+  },
+  "urlTags": "utm_source=facebook&utm_medium=paid"
+}
+```
+
+**Standard CTA types:** `LEARN_MORE`, `SHOP_NOW`, `SIGN_UP`, `SUBSCRIBE`, `GET_OFFER`, `CONTACT_US`, `DOWNLOAD`, `ORDER_NOW`, `BUY_NOW`, `BOOK_NOW`, `APPLY_NOW`, `GET_QUOTE`, `GET_IN_TOUCH`, `WATCH_MORE`
+
+**Objective-specific CTAs** (inherited from template ad — do not set manually):
+
+| CTA | Required Objective |
+|-----|-------------------|
+| `MESSAGE_PAGE` | Messenger destination |
+| `WHATSAPP_MESSAGE` | WhatsApp destination |
+| `INSTAGRAM_MESSAGE` | Instagram DM destination |
+| `CALL_NOW` | Call campaign |
+
+### Creative Enhancements
+
+```json
+{ "creativeEnhancements": "none" }
+```
+
+| Value | Effect |
+|-------|--------|
+| `"metaDefaults"` | Let Meta decide (default if omitted) |
+| `"all"` | All features on |
+| `"none"` | All features off |
+| `["text_translation", "image_touchups"]` | Listed features on, rest off |
+
+Available features: `text_translation`, `inline_comment`, `enhance_cta`, `text_optimizations`, `reveal_details_over_time`, `image_brightness_and_contrast`, `image_touchups`, `video_auto_crop`, `video_filtering`, `image_animation`, `image_templates`, `adapt_to_placement`, `product_extensions`, `description_automation`, `add_text_overlay`, `music`, `carousel_to_video`, `carousel_dynamic_description`, `multi_share_end_card`, `multi_share_optimized`
+
+When cherry-picking features, only list ones relevant to the media type. `video_auto_crop` and `video_filtering` only apply to video ads. `carousel_to_video`, `carousel_dynamic_description`, `multi_share_end_card`, and `multi_share_optimized` only apply to carousel ads.
+
+### Carousel Ads
+
+Group uploaded files into carousel ads with per-card text:
+
+```json
+{
+  "carousel": [
+    {
+      "name": "My Carousel",
+      "cards": ["slide1.jpg", "slide2.jpg", "slide3.jpg"],
+      "cardTexts": [
+        { "headline": "Slide 1", "description": "First card", "link": "https://example.com/1" },
+        { "headline": "Slide 2", "description": "Second card", "link": "https://example.com/2" }
+      ]
+    }
+  ]
+}
+```
+
+Cards must reference filenames from the upload batch. Minimum 2 cards per carousel. Files claimed by a carousel are removed from the standard ad list.
+
+### Flexible Ads
+
+Group multiple assets into a single flexible ad (Meta picks the best asset per placement):
+
+```json
+{
+  "flexible": [
+    {
+      "name": "Multi-Asset Ad",
+      "assets": ["hero.jpg", "promo.mp4", "banner.jpg"]
+    }
+  ]
+}
+```
+
+Minimum 2 assets per group. Files claimed by a flexible group are removed from the standard ad list.
+
+### Ad Naming
+
+```json
+{ "adNamePattern": "{filename} - {date}" }
+```
+
+Placeholders: `{filename}`, `{index:01}`, `{variation}`, `{campaign}`, `{date}`, `{date:short}`, `{timestamp}`
+
+### Options
+
+```json
+{
+  "options": {
+    "status": "PAUSED",
+    "pauseAt": "ad",
+    "schedule": {
+      "startTime": "2026-04-01T09:00:00",
+      "endTime": "2026-04-30T23:59:59"
+    }
+  }
+}
+```
+
+| Field | Values | Description |
+|-------|--------|-------------|
+| `status` | `"PAUSED"`, `"ACTIVE"` | Ad launch status (default: ACTIVE) |
+| `pauseAt` | `"ad"`, `"adSet"`, `"campaign"` | Which level to pause (default: ad) |
+| `schedule.startTime` | ISO 8601 string | Scheduled start (uses ad account timezone) |
+| `schedule.endTime` | ISO 8601 string | Scheduled end (optional) |
+
+---
+
+## Upload & Variant Detection
+
+Variant groups are detected automatically from filename conventions:
+
+**Ratio suffixes:**
+`hero_4x5.jpg` + `hero_9x16.jpg` + `hero_16x9.jpg` → grouped as one variant ad
+
+**Word suffixes:**
+`hero.jpg` + `hero_vertical.jpg` + `hero_horizontal.jpg` → grouped as one variant ad
+
+Both `_` and `-` delimiters work. A file without a ratio suffix (e.g. `hero.jpg`) only groups with `_vertical`/`_horizontal` variants.
+
+---
+
+## Common Patterns
+
+### Simple upload + create with preset
+
+```bash
+# Upload
+ads upload ./creatives/hero.jpg ./creatives/banner.jpg
+# Note the batchId from output (printed as "Batch: batch_xxx")
+
+# Write spec
+cat > /tmp/spec.json << 'EOF'
+{
+  "adPresetId": "PRESET_ID",
+  "uploadId": "BATCH_ID"
+}
+EOF
+
+# Preview, then create
+ads create:preview /tmp/spec.json
+ads create /tmp/spec.json
+```
+
+### Per-ad text (unique copy per file)
+
+```json
+{
+  "adPresetId": "PRESET_ID",
+  "uploadId": "BATCH_ID",
+  "texts": {
+    "perAd": {
+      "hero.jpg": {
+        "headlines": ["Summer Sale Now On"],
+        "bodies": ["Save up to 50% on all items"],
+        "cta": "SHOP_NOW",
+        "link": "https://example.com/summer"
+      },
+      "banner.jpg": {
+        "headlines": ["New Collection Available"],
+        "bodies": ["Browse our latest styles"],
+        "cta": "LEARN_MORE",
+        "link": "https://example.com/new"
+      }
+    }
+  },
+  "options": { "status": "PAUSED" }
+}
+```
+
+### Auto-group into multiple ad sets
+
+```json
+{
+  "adPresetId": "PRESET_ID",
+  "uploadId": "BATCH_ID",
+  "adSet": { "mode": "autoGroup", "adsPerAdSet": 3 },
+  "options": { "status": "PAUSED" }
+}
+```
+
+### Copy from existing ad
+
+```bash
+# Find the ad to copy from
+ads campaigns
+ads campaign 120233848666410472       # shows ad sets
+ads adset 120233848666620472          # shows ads
+ads ad 120233848667930472             # shows ad details
+```
+
+```json
+{
+  "copyFromAd": "120233848667930472",
+  "campaign": { "id": "120233848666410472" },
+  "uploadId": "BATCH_ID",
+  "options": { "status": "PAUSED" }
+}
+```
+
+### Follow job progress
+
+```bash
+ads create spec.json
+# Shows live progress automatically; to check a job later:
+ads jobs JOB_ID --follow
+```
+
+---
+
+## Critical Gotchas
+
+1. **Always preview first** — `create:preview` catches config errors before touching Facebook
+2. **Ads are ACTIVE by default** — use `--status PAUSED` or `"status": "PAUSED"` in spec to create them paused
+3. **`uploadId` comes from upload output** — it's the batch ID returned by `ads upload`
+4. **Uploads are tied to an ad account** — files are uploaded directly to the selected account's Facebook media library. The batch ID can only be used with the same account
+5. **`copyFromAd` needs `uploadId`** — you must provide the upload batch. Optionally provide `campaign.id` and `adSet.id` to control placement
+6. **Per-ad text keys are filenames** — use `"hero.jpg"`, not `"/path/to/hero.jpg"`
+7. **`textPresetId` and `texts` are mutually exclusive** — use one or the other
+8. **Objective-specific CTAs** (`MESSAGE_PAGE`, `WHATSAPP_MESSAGE`, etc.) are inherited from the template — don't set them manually
+9. **Do not use `--json`** — it's for shell scripts, not interactive use. The human-readable output has everything you need