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

Dateien werden parallel bereitgestellt, und vorübergehende Netzwerkfehler werden automatisch mit Backoff erneut versucht. Du musst diese selten anfassen, aber sie sind verfügbar:

Anzeigenerstellung

Job-Verwaltung

Create-Flags

Diese Flags gelten für ads create, ads create:preview und ads create:interactive. Sie können anstelle einer Spec-Datei oder zusammen mit ihr verwendet werden.

Browse-Flags

Diese Flags sind verfügbar bei campaigns, adsets, adset und campaign:

Detail-Flags

Diese Flags sind verfügbar bei ad:

Allgemeine Flags

Format der Spec-Datei

Die JSON-Spec-Datei steuert jeden Aspekt der Anzeigenerstellung. Nur zwei Felder sind erforderlich: eine Template-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"
  }
}

Template-Quelle

Du brauchst eine davon, um dem CLI mitzuteilen, welche Anzeigenkonfiguration als Basis verwendet werden soll.

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

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

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

Profiloptionen

Standardmäßig erben neue Anzeigen die Facebook-Seite, das Instagram-Konto und das Threads-Profil von der Template-Anzeige oder dem Preset. Das ist dasselbe Profiloptionen-Steuerelement, das über das Standardwerte-Panel in der Web-App verfügbar ist. Überschreibe eines davon mit einem profile-Block (oder den Flags --page / --instagram / --threads, die Vorrang vor der Spec-Datei haben):

{
  "copyFromAd": "120233848667930472",
  "uploadId": "batch_abc123",
  "profile": {
    "pageId": "123456789012345",
    "instagramId": "17841400000000000",
    "threadsId": "987654321098765"
  }
}

Führe ads pages aus, um die Seiten-IDs aufzulisten, die du verwenden kannst, zusammen mit dem verknüpften Instagram-Konto jeder Seite.

Wichtig: Wenn du nur die Seite überschreibst, werden die Instagram- und Threads-Profile zurückgesetzt (sie gehörten zur alten Seite), sie werden nicht übernommen. Um die Seite zu wechseln und ein bestimmtes Instagram- oder Threads-Profil zu behalten, lege diese explizit fest. Du kannst auch nur das Instagram- oder Threads-Profil ändern, ohne die Seite anzufassen, indem du nur diese Felder festlegst.

Profile pro Kampagne für Multi-Kampagnen-Starts werden in CLI-Specs noch nicht unterstützt.

Kampagnenstruktur

Standardmäßig gehen Anzeigen in die Kampagne der Template-Anzeige. Du kannst eine neue Kampagne erstellen, indem du campaign.name angibst.

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

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

Ad-Set-Modi

Standardmäßig gehen Anzeigen in das bestehende Ad Set der Template-Anzeige. Die folgenden Modi geben dir Kontrolle darüber, wie Anzeigen auf Ad Sets verteilt werden.

Ein neues Ad Set erstellen:

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

Ein bestehendes Ad Set per ID verwenden:

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

Ein Ad Set pro hochgeladener Datei:

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

Automatisches Gruppieren in Ad Sets fester Größe:

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

Benutzerdefinierte Gruppen mit voller Kontrolle darüber, welche Dateien wohin gehen:

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

Benennungsmuster für Ad Sets für Multi-Ad-Set-Modi:

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

Variantengruppierung gruppiert Anzeigen nach Variationskennung in dasselbe Ad Set:

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

Budget- und Gebotsüberschreibung

Überschreibe das Tagesbudget und/oder den Gebotsbetrag bei neuen Ad Sets. Die 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 beim Ad Set): Du kannst dailyBudget, bidAmount oder beides festlegen. Gebotsobergrenzen-Strategien wie COST_CAP, LOWEST_COST_WITH_BID_CAP und TARGET_COST erfordern ein bidAmount zusätzlich zum Budget.
• CBO-Kampagnen (Budget liegt bei der Kampagne): Lege dailyBudget nicht beim Ad Set fest, Meta lehnt das ab, weil das Budget bereits von der Kampagne kommt. Für Gebotsobergrenzen-Strategien lege nur bidAmount fest.

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

Textkonfiguration

Gemeinsamer Text wendet denselben Text auf alle Anzeigen an:

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

Text pro Anzeige lässt dich einzigartigen Text für jede Datei festlegen:

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

Schlüssel pro Anzeige sind Dateinamen (keine vollständigen Pfade). Jeder Eintrag unterstützt: headlines, bodies, descriptions, cta, link, displayUrl, urlTags. Felder, die du nicht angibst, werden von der Template-Anzeige geerbt.

Text-Presets lassen dich eine gespeicherte Textkonfiguration laden:

{ "textPresetId": "preset_id_here" }

Du kannst textPresetId nicht mit texts kombinieren.

Strategieoptionen steuern, wie mehrere Textvariationen behandelt werden:

• "flexible" (Standard) lässt Meta über deine Textvariationen optimieren. Mehrere Überschriften und Texte werden zu Optionen, die Facebook frei kombiniert.
• "separate" erstellt eine separate Anzeige für jede Textkombination.

CTA und Links

Eine CTA auf oberster Ebene gilt für alle Anzeigen. CTAs pro Anzeige in texts.perAd überschreiben sie.

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

Zielspezifische CTAs werden von der Template-Anzeige geerbt und sollten nicht manuell festgelegt werden. Sie beim falschen Kampagnentyp festzulegen, verursacht einen Facebook-API-Fehler.

URL-Split-Test (geteiltes Ziel)

Gib 2 bis 5 Ziel-URLs unter texts.urlVariants an, und jedes generierte Ad Set wird einmal pro URL dupliziert, sodass Meta jede Kombination aus Anzeige und Landingpage unabhängig optimiert.

{
  "texts": {
    "common": { "headlines": ["Hero"], "bodies": ["Copy"] },
    "urlVariants": [
      { "link": "https://example.com/homepage", "label": "homepage" },
      { "link": "https://example.com/quiz", "label": "quiz-v2" }
    ]
  }
}

• label ist optional. Wenn weggelassen, wird der letzte Pfad-Slug der URL verwendet (/quiz-v2 → quiz-v2), mit Rückfall auf den Hostnamen bei Root-URLs.
• Im Einzel-Ad-Set-Modus wird das Label jeder Variante zum vollständigen Ad-Set-Namen.
• In den Modi perUpload und autoGroup hängt der Name jedes duplizierten Ad Sets _{label} an das Muster an (oder ersetzt einen {destination}-Token, falls du einen einfügst).
• Der {date}-Token in einem Label wird zum heutigen Datum aufgelöst (z. B. launch-{date} → launch-2026-04-27).
• Jede Ziel-URL muss eindeutig sein. Identische URLs (oder Varianten desselben URL mit/ohne Schrägstrich am Ende oder mit anderer Groß-/Kleinschreibung) werden zu einem Eintrag zusammengefasst, stelle also sicher, dass du mindestens 2 unterschiedliche Ziele hast.
• Dein Ad-Set-Budget wird mit der Anzahl der Varianten multipliziert, da jedes Duplikat ein eigenes Ad Set ist.
• Nicht kompatibel mit Quell-Anzeigen mit Spezialziel (Lead-Formular, Messenger, WhatsApp, Instagram-DM, Anruf). Das CLI lehnt diese Kombination mit einem klaren Fehler ab, diese Formate werden nicht über cta.link geleitet.
• link-Überschreibungen pro Anzeige in texts.perAd verlieren gegen die Varianten-URL, wenn beide festgelegt sind.

Creative Enhancements

Steuere die Advantage+ Creative Enhancements:

{ "creativeEnhancements": "none" }

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

Wenn du einzelne Funktionen auswählst, liste nur die auf, die für den Medientyp relevant sind. Videofunktionen (video_auto_crop, video_filtering) gelten nur für Videoanzeigen. Karussellfunktionen (carousel_to_video, carousel_dynamic_description, multi_share_end_card, multi_share_optimized) gelten nur für Karussellanzeigen.

Karussellanzeigen

Gruppiere hochgeladene Dateien in Karussellanzeigen mit Text pro Karte und optionalem Gesamttext für das Karussell. cardTexts steuert einzelne Karten. Der Gesamttext des Karussells kann am Karussell-Objekt mitgegeben oder in texts.perAd über den name des Karussells festgelegt werden; die am Objekt mitgegebenen Felder gewinnen, wenn beide vorhanden sind.

{
  "carousel": [
    {
      "name": "My Carousel",
      "cards": ["slide1.jpg", "slide2.jpg", "slide3.jpg"],
      "headlines": ["Overall Carousel Headline"],
      "bodies": ["Overall primary text"],
      "descriptions": ["Overall description"],
      "cta": "SHOP_NOW",
      "link": "https://example.com/carousel",
      "urlTags": "utm_content=my_carousel",
      "cardTexts": [
        { "headline": "Slide 1", "description": "First card", "link": "https://example.com/1" },
        { "headline": "Slide 2", "description": "Second card", "link": "https://example.com/2" }
      ]
    }
  ]
}

Alternative Form für den Gesamttext:

{
  "texts": {
    "perAd": {
      "My Carousel": {
        "headlines": ["Overall Carousel Headline"],
        "bodies": ["Overall primary text"],
        "descriptions": ["Overall description"],
        "cta": "SHOP_NOW",
        "link": "https://example.com/carousel",
        "urlTags": "utm_content=my_carousel"
      }
    }
  },
  "carousel": [
    {
      "name": "My Carousel",
      "cards": ["slide1.jpg", "slide2.jpg", "slide3.jpg"]
    }
  ]
}

Karten müssen auf Dateinamen aus dem Upload-Batch verweisen. Mindestens 2 Karten pro Karussell. Dateien, die von einem Karussell beansprucht werden, werden aus der Standard-Anzeigenliste entfernt.

Flexible Anzeigen

Gruppiere mehrere Assets in eine einzige flexible Anzeige, bei der Meta das beste Asset pro Platzierung auswählt:

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

Mindestens 2 Assets pro Gruppe. Dateien, die von einer flexiblen Gruppe beansprucht werden, werden aus der Standard-Anzeigenliste entfernt.

Multi-Media-Anzeigen

Gruppiere 2-10 hochgeladene Bilder oder Videos in eine Meta-Multi-Media-Anzeige:

{
  "multimedia": [
    {
      "name": "Mixed Media Ad",
      "assets": ["hero.jpg", "promo.mp4", "banner.jpg"],
      "assetTexts": [
        {
          "headline": "Hero headline",
          "primaryText": "Hero primary text",
          "description": "Hero description",
          "link": "https://example.com/hero",
          "displayUrl": "example.com/hero"
        }
      ]
    }
  ]
}

Assets müssen auf Dateinamen aus dem Upload-Batch verweisen. assetTexts ist optional und richtet sich nach Index an assets aus; jedes Feld ist eine einzelne Überschreibung für dieses Asset, und leere Felder fallen auf den Haupttext und die URLs der Anzeige zurück. Das primär gerenderte Asset verwendet den Haupttext und die Haupt-URL der Anzeige, und jede Überschreibung des Primärtexts eines Assets wird zur ersten Haupttext-Option. Videos benötigen eine gecachte öffentliche Thumbnail-URL aus der Upload-Verarbeitung. Dateien, die von einer Multi-Media-Gruppe beansprucht werden, werden aus der Standard-Anzeigenliste entfernt.

Anzeigenbenennung

Passe 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

Variantengruppen werden automatisch aus Dateinamenskonventionen erkannt, genau wie in der Webanwendung. Siehe Variationen des Seitenverhältnisses für alle Details zu den Benennungskonventionen.

Verhältnis-Suffixe: hero_1x1.jpg + hero_4x5.jpg + hero_9x16.jpg + hero_16x9.jpg + hero_1.91x1.jpg werden als eine Varianten-Anzeige gruppiert. Bis zu 5 Verhältnisse pro Gruppe.

Token-Position: Der Verhältnis-Token kann am Ende (hero_4x5.jpg), in der Mitte (hero_4x5_v2.jpg) oder am Anfang (4x5_hero.jpg) stehen.

Veraltete Wort-Suffixe: hero.jpg + hero_vertical.jpg + hero_horizontal.jpg funktionieren weiterhin und werden auf 9x16 und 16x9 abgebildet.

Das Standard-Trennzeichen ist _. Du kannst es ändern (oder mehrere zulassen) unter Konto > Standardwerte > Platzierungen > Dateinamen-Trennzeichen.

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 Folgendes enthält:

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

Einstellungen von einer bestehenden Anzeige kopieren

Durchsuche dein Konto, um die Anzeige zu finden:

ads campaigns
ads campaign 120233848666410472
ads adset 120233848666620472
ads ad 120233848667930472

Erstelle dann eine Spec, die darauf verweist:

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

Die Quell-Anzeige muss Inline-Creative-Einstellungen haben. Wenn sie aus einem bestehenden Seitenbeitrag erstellt wurde, lehnt das CLI sie ab, bevor eine Erstellungsanfrage gesendet wird.

Ein API-Preset aus einer bestehenden Anzeige speichern

ads presets:save --from-ad 120233848667930472 --name "Spring Purchase Template"
ads create --preset PRESET_ID --upload BATCH_ID

Das speichert dieselbe API-Preset-Form, die die Web-App verwendet. Die Quell-Anzeige muss Inline-Creative-Einstellungen haben; auf Seitenbeiträgen basierende Anzeigen können nicht als API-Presets gespeichert werden.

Text pro Anzeige mit einzigartigem Text 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 in mehrere Ad Sets

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

Wichtige Hinweise

1. Zeige immer zuerst die Vorschau an. create:preview erkennt Konfigurationsfehler, bevor Facebook angefasst wird.
2. Anzeigen sind standardmäßig aktiv. Verwende --status PAUSED oder "status": "PAUSED" in der Spec, um sie pausiert zu erstellen.
3. uploadId kommt aus der Upload-Ausgabe. Es ist die Batch-ID, die von ads upload zurückgegeben wird.
4. Uploads sind an ein Werbekonto gebunden. Dateien werden direkt in die Facebook-Mediathek des ausgewählten Kontos hochgeladen. Die Batch-ID kann nur mit demselben Konto verwendet werden.
5. copyFromAd braucht uploadId. Du musst den Upload-Batch angeben. Optional kannst du campaign.id und adSet.id angeben, um die Platzierung zu steuern.
6. Textschlüssel pro Anzeige sind Dateinamen. Verwende "hero.jpg", nicht "/path/to/hero.jpg".
7. textPresetId und texts schließen sich gegenseitig aus. Verwende das eine oder das andere, nicht beide.
8. Zielspezifische CTAs werden vom Template geerbt. Lege MESSAGE_PAGE, WHATSAPP_MESSAGE usw. nicht manuell fest.