CLI-Vollständige Referenz

Das ist die vollständige Referenz für das Ads Uploader CLI. Eine Einführung und den Einstiegsleitfaden findest du unter CLI-Konfiguration.

Befehle

Authentifizierung

Durchsuchen

Medien-Upload

Anzeigenerstellung

Job-Verwaltung

Create-Flags

Diese Flags gelten für ads create, ads create:preview und ads create:interactive. Sie können anstelle oder zusätzlich zu einer Spec-Datei verwendet werden.

Browse-Flags

Diese Flags gibt es bei campaigns, adsets, adset und campaign:

Allgemeine Flags

Format der Spec-Datei

Die JSON-Spec-Datei steuert alle Aspekte der Anzeigenerstellung. Nur zwei Felder sind erforderlich: eine Vorlage-Quelle (adPresetId oder copyFromAd) und uploadId.

Minimale Spec

{
  "adPresetId": "your_preset_id",
  "uploadId": "batch_abc123"
}

Vollständiges Beispiel

{
  "adPresetId": "preset_id_here",
  "uploadId": "batch_abc123",
  "adSet": {
    "name": "My New Ad Set",
    "dailyBudget": 50
  },
  "adNamePattern": "{filename}",
  "texts": {
    "perAd": {
      "hero.jpg": {
        "headlines": ["Main Headline"],
        "bodies": ["Ad copy here."],
        "descriptions": ["Short description"],
        "cta": "SHOP_NOW",
        "link": "https://example.com/landing"
      }
    }
  },
  "creativeEnhancements": "none",
  "options": {
    "status": "PAUSED",
    "pauseAt": "adSet"
  }
}

Vorlage-Quelle

Du brauchst eine davon, damit das CLI weiß, welche Anzeigenkonfiguration als Basis dienen soll.

Wenn du copyFromAd nutzt, gib den Upload-Batch an und optional Kampagne und Ad Set:

{
  "copyFromAd": "120233848667930472",
  "uploadId": "batch_abc123",
  "campaign": { "id": "120233848666410472" },
  "adSet": { "id": "120233848666620472" }
}

Um die richtige Anzeigen-ID zu finden, browse durch dein Konto: ads campaigns, dann ads campaign <id>, dann ads adset <id>, dann ads ad <id>.

Kampagnenstruktur

Standardmäßig landen Anzeigen in der Kampagne der Vorlage-Anzeige. Du kannst per campaign.name eine neue Kampagne anlegen.

Für Multi-Kampagnen-Modi nutze campaign.mode mit einem campaigns-Array:

{
  "campaign": {
    "mode": "duplicate",
    "campaigns": [
      { "name": "Campaign A" },
      { "name": "Campaign B" }
    ]
  }
}

Ad-Set-Modi

Standardmäßig landen Anzeigen im bestehenden Ad Set der Vorlage-Anzeige. Mit folgenden Modi steuerst du, wie Anzeigen auf Ad Sets verteilt werden.

Neues Ad Set anlegen:

{ "adSet": { "name": "My Ad Set" } }

Bestehendes Ad Set per ID verwenden:

{ "adSet": { "id": "120233848666620472" } }

Ein Ad Set pro hochgeladener Datei:

{ "adSet": { "mode": "perUpload" } }

Automatisch in Ad Sets fester Größe gruppieren:

{ "adSet": { "mode": "autoGroup", "adsPerAdSet": 5 } }

Benutzerdefinierte Gruppen mit voller Kontrolle über Dateizuordnung:

{
  "adSet": {
    "groups": [
      { "name": "Images - April 10", "media": ["hero.jpg", "banner.jpg"] },
      { "name": "Videos - April 10", "media": ["promo.mp4"] }
    ]
  }
}

Namensmuster für Ad Sets in Multi-Ad-Set-Modi:

{ "adSet": { "mode": "perUpload", "namePattern": "Ad Set {index:01}" } }

Varianten-Gruppierung fasst Anzeigen per Variationskennung in dasselbe Ad Set:

{ "adSet": { "mode": "autoGroup", "groupVariations": true, "variationIdentifier": "-" } }

Budget- und Bid-Override

Überschreibt Tagesbudget und/oder Bid bei neuen Ad Sets. Werte sind in den Währungseinheiten deines Kontos (z. B. 50 für $50 oder 50 Euro).

dailyBudget und bidAmount sind unabhängige Meta-Felder:

• ABO-Kampagnen (Budget liegt auf dem Ad Set): Du kannst dailyBudget, bidAmount oder beide setzen. Bid-Cap-Strategien wie COST_CAP, LOWEST_COST_WITH_BID_CAP und TARGET_COST brauchen zusätzlich zum Budget ein bidAmount.
• CBO-Kampagnen (Budget liegt auf der Kampagne): setze dailyBudget nicht auf dem Ad Set - Meta lehnt das ab, weil das Budget bereits aus der Kampagne kommt. Für Bid-Cap-Strategien nur bidAmount setzen.

{ "adSet": { "dailyBudget": 50 } }
{ "adSet": { "bidAmount": 5 } }
{ "adSet": { "dailyBudget": 50, "bidAmount": 5 } }

Auch als CLI-Flags verfügbar: --daily-budget 50, --bid-amount 5 oder beides.

Text-Konfiguration

Gemeinsamer Text wendet die gleichen Texte auf alle Anzeigen an:

{
  "texts": {
    "common": {
      "headlines": ["Headline 1", "Headline 2"],
      "bodies": ["Primary text"],
      "descriptions": ["Description"]
    },
    "strategy": "flexible"
  }
}

Per-Ad-Text erlaubt eigene Texte pro Datei:

{
  "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-Schlüssel sind Dateinamen (keine vollen Pfade). Jeder Eintrag unterstützt: headlines, bodies, descriptions, cta, link, displayUrl, urlTags. Nicht gesetzte Felder werden von der Vorlage-Anzeige übernommen.

Text-Presets laden eine gespeicherte Textkonfiguration:

{ "textPresetId": "preset_id_here" }

Du kannst textPresetId nicht mit texts kombinieren.

Strategie-Optionen steuern, wie mehrere Text-Varianten gehandhabt werden:

• "flexible" (Standard) lässt Meta zwischen deinen Text-Varianten optimieren. Mehrere Headlines und Bodies werden zu Optionen, die Facebook kombiniert.
• "separate" erstellt pro Textkombination eine eigene Anzeige.

CTA und Links

Ein Top-Level-CTA gilt für alle Anzeigen. Per-Ad-CTAs in texts.perAd überschreiben ihn.

{
  "cta": {
    "type": "SHOP_NOW",
    "link": "https://example.com",
    "displayUrl": "example.com"
  },
  "urlTags": "utm_source=facebook&utm_medium=paid"
}

Standard-CTA-Typen: 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

Ziel-spezifische CTAs werden von der Vorlage-Anzeige übernommen und sollten nicht manuell gesetzt werden. Sie beim falschen Kampagnentyp zu setzen, führt zu einem Facebook-API-Fehler.

Creative Enhancements

Steuere Advantage+ Creative Enhancements:

{ "creativeEnhancements": "none" }

Verfügbare 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

Bei selektiver Auswahl nur Features nennen, die zum Medientyp passen. Video-Features (video_auto_crop, video_filtering) gelten nur für Video-Anzeigen. Carousel-Features (carousel_to_video, carousel_dynamic_description, multi_share_end_card, multi_share_optimized) nur für Carousel Ads.

Carousel Ads

Hochgeladene Dateien zu Carousel Ads mit Karten-eigenem Text gruppieren:

{
  "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" }
      ]
    }
  ]
}

Karten müssen Dateinamen aus dem Upload-Batch referenzieren. Mindestens 2 Karten pro Carousel. Dateien, die einem Carousel zugeordnet sind, verschwinden aus der Standard-Anzeigenliste.

Flexible Ads

Mehrere Assets in einer einzigen Flexible Ad gruppieren, aus der Meta pro Placement das beste Asset wählt:

{
  "flexible": [
    {
      "name": "Multi-Asset Ad",
      "assets": ["hero.jpg", "promo.mp4", "banner.jpg"]
    }
  ]
}

Mindestens 2 Assets pro Gruppe. Dateien, die einer Flexible-Gruppe zugeordnet sind, verschwinden aus der Standard-Anzeigenliste.

Anzeigen-Benennung

So passt du an, wie deine Anzeigen benannt werden:

{ "adNamePattern": "{filename} - {date}" }

Optionen

{
  "options": {
    "status": "PAUSED",
    "pauseAt": "adSet",
    "schedule": {
      "startTime": "2026-04-01T09:00:00",
      "endTime": "2026-04-30T23:59:59"
    }
  }
}

Upload und Varianten-Erkennung

Varianten-Gruppen werden automatisch aus Dateinamen-Konventionen erkannt, genau wie in der Web-App. Alle Details zur Benennung findest du unter Seitenverhältnis-Varianten.

Verhältnis-Suffixe: hero_4x5.jpg + hero_9x16.jpg + hero_16x9.jpg werden zu einer Varianten-Anzeige.

Wort-Suffixe: hero.jpg + hero_vertical.jpg + hero_horizontal.jpg werden zu einer Varianten-Anzeige.

Sowohl _- als auch --Trenner funktionieren. Eine Datei ohne Verhältnis-Suffix (z. B. hero.jpg) wird nur mit _vertical/_horizontal-Varianten gruppiert. Für Verhältnis-basierte Gruppierung brauchen alle Dateien Verhältnis-Suffixe.

Gängige Muster

Hochladen und mit einem Preset erstellen

ads upload ./creatives/hero.jpg ./creatives/banner.jpg
ads create:preview spec.json
ads create spec.json

Wobei spec.json enthält:

{ "adPresetId": "PRESET_ID", "uploadId": "BATCH_ID" }

Einstellungen einer bestehenden Anzeige kopieren

Durchsuche dein Konto, um die Anzeige zu finden:

ads campaigns
ads campaign 120233848666410472
ads adset 120233848666620472
ads ad 120233848667930472

Dann eine Spec erstellen, die sie referenziert:

{
  "copyFromAd": "120233848667930472",
  "uploadId": "BATCH_ID"
}

Per-Ad-Text mit eigenem Copy pro Datei

{
  "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"
      }
    }
  }
}

Automatisches Gruppieren auf mehrere Ad Sets

{
  "adPresetId": "PRESET_ID",
  "uploadId": "BATCH_ID",
  "adSet": { "mode": "autoGroup", "adsPerAdSet": 3 }
}

Wichtige Hinweise

1. Immer zuerst Preview. create:preview erwischt Konfigurationsfehler, bevor Facebook berührt wird.
2. Anzeigen sind standardmäßig aktiv. Mit --status PAUSED oder "status": "PAUSED" in der Spec werden sie pausiert erstellt.
3. uploadId kommt aus der Upload-Ausgabe. Es ist die Batch-ID, die ads upload zurückgibt.
4. Uploads sind an ein Werbekonto gebunden. Dateien werden direkt in die Facebook-Medienbibliothek des gewählten Kontos geladen. Die Batch-ID funktioniert nur mit demselben Konto.
5. copyFromAd braucht uploadId. Du musst den Upload-Batch angeben. Optional campaign.id und adSet.id, um die Platzierung zu steuern.
6. Per-Ad-Text-Schlüssel sind Dateinamen. Verwende "hero.jpg", nicht "/path/to/hero.jpg".
7. textPresetId und texts schließen sich aus. Eines von beidem, nicht beide.
8. Ziel-spezifische CTAs werden von der Vorlage übernommen. Setze MESSAGE_PAGE, WHATSAPP_MESSAGE usw. nicht manuell.