CLI-Konfiguration

Mit dem Ads Uploader CLI (Command Line Interface) lädst du Medien hoch und erstellst Meta Ads direkt aus dem Terminal. Der CLI-Zugriff ist für zahlende Pläne gedacht und in der Testphase nicht verfügbar.

Das CLI folgt derselben Struktur wie die Web-App. Wenn du schon Anzeigen über die Web-App hochgeladen hast, verstehst du das CLI sofort: Du wählst eine Quellanzeige oder ein Preset, fügst deine Medien hinzu, prüfst die Vorschau und erstellst dann die Anzeigen.

Presets, die du in der Web-App baust, tauchen auch im CLI auf, und mit ads presets:save kannst du neue API-Presets direkt aus dem CLI speichern. Das CLI nutzt außerdem dieselben Build-Referenzen wie der Web-Uploader und das MCP. So kannst du einen angefangenen Build fortsetzen, ohne von vorn zu beginnen.

Warum das CLI nutzen? Du bekommst dieselbe Launch-Pipeline von Ads Uploader, aber über ein Interface, das für KI-Agenten gebaut ist. Mehrere Batches lädst du schneller, und ein Agent kann Anzeigentexte schreiben und Builds für dich zusammenstellen. Nimm das CLI, wenn du deinen kompletten Ablauf über einen Agenten laufen lassen willst. Für kleine, gezielte Hilfe in einem Workflow, der hauptsächlich in der Web-App stattfindet, schau dir CLI or MCP? auf der MCP-Seite an.

Die meisten steuern das CLI über einen KI-Agenten wie Claude Code oder Cursor. Mehr dazu unter Nutzung mit KI weiter unten.

Installieren und anmelden

Das CLI braucht Node.js 18 oder neuer. Installiere es über npm:

npm install -g @adsuploader/cli

Dann meldest du dich an:

ads login

ads login öffnet deinen Browser, damit du die Anmeldung mit deinem Ads Uploader-Konto bestätigen kannst. Führe den Befehl auf einem Rechner aus, auf dem du einen Browser öffnen und dich bei adsuploader.com anmelden kannst. Danach nutzt das CLI deine bestehende Meta-Verbindung.

Wie lange ein Login hält. Ein Login-Token ist 30 Tage gültig. Danach führst du ads login einfach noch einmal aus. Deine CLI-Sitzungen siehst und widerrufst du unter Account > MCP, CLI & API in der Karte MCP and CLI-Connected AI Apps.

Aktualisieren. Das CLI sagt dir Bescheid, wenn eine neue Version da ist. So aktualisierst du:

npm update -g @adsuploader/cli

Mit ads --version siehst du, welche Version du hast.

API-Schlüssel für deine eigenen Agenten und Skripte

Nutze für langfristige Verbindungen deiner eigenen Agenten und Skripte einen API-Schlüssel über ADS_API_KEY oder ads login --api-key. Unter API-Schlüssel erfährst du, wie du ihn erstellst, einrichtest, allein nutzt und widerrufst.

Werbekonto festlegen

Führe ads accounts aus, um die Werbekonten aufzulisten, die mit deinem Meta-Konto verbunden sind. Dann legst du einen Standard fest:

ads account act_123456789

Das entspricht der Kontoauswahl in der Web-App. Wenn du in Meta gerade erst Zugriff auf ein neues Werbekonto bekommen hast, führe ads accounts:refresh aus, um die Liste sofort neu zu laden.

Konto durchsuchen

Bevor du Anzeigen erstellst, kannst du dich im Terminal durch dein Konto klicken, genau wie in der Web-App:

So findest du die Anzeige, deren Einstellungen du kopieren willst, oder das Preset bzw. den Build, den du nutzen willst.

Medien hochladen

Mit ads upload lädst du Bilder und Videos in dein Werbekonto:

ads upload hero.jpg banner.mp4 promo.mp4
ads upload ./my-creatives/
ads upload hero.jpg "https://cdn.example.com/banner.mp4"
ads upload "https://drive.google.com/file/d/.../view"
ads upload:drive "https://drive.google.com/drive/folders/..."

Jeder Upload gibt eine Batch-ID zurück. Die brauchst du, wenn du Anzeigen erstellst. Mit ads uploads siehst du deine letzten Batches.

ads upload erkennt HTTPS-Links von selbst. Du kannst lokale Dateien und Links in einem Befehl mischen: Zuerst kommen die lokalen Dateien, dann lädt Ads Uploader jeden Link auf seinem Server in denselben Batch. So funktionieren Seitenverhältnis-Gruppierung und Thumbnail-Zuordnung weiterhin über alle Dateien hinweg. Öffentliche Google Drive-Dateilinks funktionieren wie jeder andere Link. Für einen ganzen Drive-Ordner nutzt du ads upload:drive. Der Ordner muss dafür als Anyone with the link (Viewer) freigegeben sein.

Benenne deine Dateien mit Seitenverhältnis-Suffixen, dann gruppiert das CLI die Versionen für dich, genau wie die Web-App. Siehe Seitenverhältnis-Varianten.

Wenn einzelne Dateien fehlschlagen (zum Beispiel wegen eines Netzwerkabbruchs), führe ads upload --retry-failed aus. Damit versuchst du die fehlgeschlagenen Dateien aus deinem letzten fehlgeschlagenen Batch erneut. Hängst du eine Batch-ID an, wird genau dieser Batch erneut versucht.

Anzeigen erstellen

Das Erstellen von Anzeigen hat zwei Schritte: Vorschau und Erstellen.

Die Spec-Datei

Eine JSON-Spec-Datei sagt dem CLI, was es bauen soll. Die einfachste Spec verweist auf ein gespeichertes Preset und deinen Upload-Batch:

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

Statt eines Presets kannst du auch die Einstellungen einer bestehenden Anzeige kopieren:

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

Die Anzeigen-ID findest du, indem du mit ads campaigns, ads campaign <id>, ads adset <id> und ads ad <id> durch dein Konto gehst. Auch eine Anzeige, die aus einem bestehenden Page-Beitrag gebaut wurde, kannst du als Vorlage nutzen; die neuen Anzeigen übernehmen den Link des Beitrags. Haben weder die Anzeige noch ihr Beitrag einen Website-Link, setz cta.link in der Spec.

Du kannst die Spec-Datei auch weglassen und mit --build <buildId> einen gespeicherten Build starten.

Zuerst die Vorschau

Prüfe immer erst die Vorschau, bevor du etwas erstellst. ads create:preview spec.json zeigt dir genau, was erstellt würde, ohne etwas in Meta anzulegen. So fallen Setup-Fehler auf, bevor irgendetwas live geht.

Erstellen

Wenn die Vorschau passt, führe ads create spec.json aus. Anzeigen gehen standardmäßig live, genau wie in der Web-App. Willst du sie pausiert anlegen, hänge --status PAUSED an oder setze "options": { "status": "PAUSED" } in der Spec.

Bestehende Anzeigen per Post-ID duplizieren

Duplizierungen durch Agenten über MCP, CLI und die öffentliche API folgen wie Launches der Einstellung Agent Launch des Kontos auf der Seite Account Permissions. Agent Edit gilt für sie nicht. Mit Allowed (Standard) startet die Kopie direkt. Mit Approval werden pending_approval und reviewUrl zurückgegeben, und erst nach der Freigabe auf der Seite Agent Inbox wird dupliziert. Teile den Link; wiederhole die Anfrage nicht und frage keinen Job ab, da vor der Freigabe keiner existiert. Mit Off wird die Anfrage mit AGENT_LAUNCH_DISABLED abgelehnt. Reguläre ACTIVE-Kopien können eine ausdrückliche Bestätigung mit confirmSpend: true erfordern (--confirm-spend in der CLI); bei Post-ID-Kopien ist sie nie nötig. Uploads neuer Medien und der von Menschen bediente Web-Duplicator bleiben unverändert.

Das CLI kann auch den Duplicator ausführen. Er kopiert eine bestehende Anzeige in eine andere Kampagne oder ein anderes Ad Set und behält dabei ihr Post-Engagement:

ads duplicator:post-id --account act_123 --post 1234567890_9876543210 --campaign 120200000000000000 --new-adset "Winners {AdName}" --paused

Prüfe vorher die Zuordnung von Quelle zu Ziel, indem du dieselben Argumente mit ads duplicator:post-id:preview ausführst. Alle Flags und das Spec-Format findest du unter Post-ID-Duplizierungs-Flags.

Vollständige Referenz

Alle Befehle und Flags, das komplette Spec-Format, Creative-Verbesserungen, Karussell-, Flexible und Multi Media-Anzeigen, Namens-Platzhalter und Spec-Limits findest du in der CLI-Referenz.

Jobs verfolgen

Das Erstellen der Anzeigen läuft im Hintergrund. Das CLI zeigt dir den Fortschritt live an, und du kannst einen Job auch später noch prüfen:

ads create und --follow beobachten einen Job jeweils bis zu 30 Minuten lang. Bei sehr großen Batches kann das CLI mit der Meldung „Still running" aufhören zu beobachten, bevor der Job fertig ist. Das ist kein Fehler: Der Job läuft auf dem Server weiter. Mit ads jobs JOB_ID --follow klinkst du dich wieder ein. In diesem Fall ist der Exit-Code 2 (0 bedeutet Erfolg, 1 bedeutet Fehler).

Du kannst pro Nutzer immer nur einen Job zur Anzeigenerstellung gleichzeitig laufen lassen. Startest du einen weiteren, während noch einer läuft, sagt dir das CLI, dass du warten oder den laufenden Job abbrechen sollst.

Rate Limits

Das CLI ist pro Nutzer und pro Art von Anfrage limitiert. Bei normaler Nutzung erreichst du die Limits nie, aber ein außer Kontrolle geratenes Skript bekommt eine 429 Rate Limit Exceeded-Antwort mit einem Retry-After-Header. Pack CLI-Befehle nicht in Polling-Schleifen (etwa watch oder while-Schleifen in der Shell). Nutze stattdessen ads jobs JOB_ID --follow für den Live-Fortschritt.

Einstellungen und Umgebungsvariablen

Mit ads config prüfst du dein Setup. Der Befehl zeigt, ob du angemeldet bist, deine E-Mail, dein Standard-Werbekonto, die API-URL und den Konfigurationsordner (~/.config/adsuploader/). Dein Login wird in diesem Ordner in credentials.json gespeichert und ist nur für dich lesbar. ads whoami zeigt deine E-Mail, dein Standardkonto und die API-URL.

Tipps

• Immer zuerst die Vorschau. create:preview findet Setup-Fehler, bevor Meta Ads erstellt werden.
• Anzeigen gehen standardmäßig live. Nutze --status PAUSED, wenn du sie vorher im Ads Manager prüfen willst.
• Uploads gehören zu einem Werbekonto. Eine Batch-ID funktioniert nur mit dem Werbekonto, in das du hochgeladen hast.
• Presets kommen aus der Web-App mit. Baue Presets in der Web-App oder speichere API-Presets mit ads presets:save und nutze sie dann per ID im CLI.

Nutzung mit KI

Das CLI ist dafür gebaut, von KI-Agenten wie Claude Code oder Cursor gesteuert zu werden. Nach dem Installieren und Anmelden gibst du deinem Agenten die Skill-Datei, damit er alle Befehle und Spec-Optionen kennt.

Die Skill-Datei steckt im npm-Paket. Bei der globalen Installation von oben liegt sie hier:

"$(npm root -g)/@adsuploader/cli/SKILL.md"

In Claude Code installierst du sie als Skill mit dem Namen ads:

mkdir -p .claude/skills/ads
cp "$(npm root -g)/@adsuploader/cli/SKILL.md" .claude/skills/ads/SKILL.md

Claude Code lädt sie dann, sobald du nach Anzeigenarbeit fragst, oder du tippst /ads. In anderen KI-Tools wie Cursor fügst du SKILL.md als Regel- oder Kontextdatei hinzu.

Das CLI ist ein Interface für Media Buyer und ihre Agenten. Es ist nicht dafür gedacht, in andere Anwendungen eingebaut zu werden.

Beispiel-Prompt

Sobald alles eingerichtet ist, kannst du deinem Agenten Anweisungen wie diese geben:

Ich habe neue Anzeigen-Creatives in meinem Ordner downloads/ads. Lade sie hoch und erstelle Anzeigen mit denselben Einstellungen wie mein Summer Sale Purchase-Preset. Gruppiere sie in Ad Sets zu je fünf Anzeigen, benannt mit dem heutigen Datum, mit einem Tagesbudget von 25 $. Schreib für jedes Bild einen eigenen Text, passend zu dem, was es zeigt. Pausiere auf Ad-Set-Ebene und zeig mir zuerst die Vorschau.

API-Zugriff

Das CLI und der MCP-Server sprechen beide mit der Ads Uploader v1 API. Sie nutzen das Token, das du über ads login oder beim Anmelden am MCP-Server bekommst. Für deine eigenen Agenten, Skripte und direkte API-Anfragen kannst du unter Account > MCP, CLI & API einen API-Schlüssel erstellen und als Authorization: Bearer adk_... senden. Das CLI kann denselben Schlüssel über ADS_API_KEY nutzen. Er funktioniert auch mit dem MCP-Server. Siehe API-Schlüssel.

Partnership Ads

Das CLI kann Partnership Ads auf zwei Wegen starten:

• Mit deinen eigenen Medien. Nutze eine normale Bild-, Video-, Karussell-, Flexible-, Multi Media- oder Seitenverhältnis-Spec und füge profile.partnership.enabled: true mit den IDs deines Partners hinzu. Du kannst pro Anzeige oder pro Ad Set einen anderen Partner festlegen oder für manche Zeilen No Partner wählen.
• Aus bestehenden Instagram-Beiträgen. Importiere einen autorisierten Instagram-Beitrag per URL, Shortcode, Media-ID oder Ad Code mit mediaItems[].kind: "partnershipPost".

Die Genehmigung wird bei der Vorschau und beim Erstellen erneut geprüft. Ein Partner mit ausstehender oder noch nicht erteilter Genehmigung blockiert den Launch nicht: Du bekommst eine Warnung PARTNERSHIP_APPROVAL_PENDING, und Meta kann die Auslieferung zurückhalten, bis der Partner zustimmt. Die vollständigen Spec-Strukturen, Scoping-Keys und Limits findest du in der CLI-Referenz unter Partnership Ads mit eigenen Medien und Spec für Partnerschaften mit bestehenden Instagram-Beiträgen.

Product Showcase

Product Showcase zeigt Produkte aus einem Katalog unter einer einzelnen Bild- oder Videoanzeige. Vollständige Kataloganzeigen (dynamisch/DPA) werden noch nicht unterstützt.

IDs müssen Zeichenfolgen aus Ziffern sein. Empfehlungen erfordern Sales-Kampagnen (OUTCOME_SALES); manuelle Katalog-/Set-Auswahl ist auch bei anderen Zielen möglich. Karussell-, flexible, Multi-Media-, bestehende Beitrags- und Partnership-Anzeigen können Product Showcase nicht aktivieren.

Kataloge und Sets suchen, dann eine Empfehlung abrufen:

ads catalogs list --account act_123
ads catalogs product-sets 3390205374500501 --product-set 29588799347389253 --json
ads catalogs recommend --url https://www.asphaltgold.com/collections/nike-sneaker --page 1234 --pixel 5678
ads create:preview spec.json --product-showcase recommended
ads create spec.json --product-showcase on --catalog 3390205374500501 --product-set 29588799347389253
ads create:preview spec.json --product-showcase off

Create und Preview akzeptieren productShowcase: { enabled?, catalogId?, productSetId?, useRecommendation? }; enabled ist standardmäßig true. Ohne das Feld wird die Quellanzeige übernommen. RECOMMENDED verwendet Metas Standard (choiceSource: "DEFAULT"); MUST_PICK erfordert eine Kandidaten-ID als productSetId ("MANUAL"). Bei MANUAL sind Katalog und Set erforderlich. Abweichende geprüfte IDs verwenden "MANUAL".

CLI-Flags für Create und Preview: --product-showcase <on|off|recommended>, --catalog <id>, --product-set <id>. Nur IDs bedeuten on; recommended setzt useRecommendation: true. Off setzt { enabled: false }, darf keine IDs enthalten und behält das Set der Quellanzeige bei.

Preview liefert productShowcase mit enabled, Katalog-/Set-IDs, optionalem Set-Namen, choiceSource und source (recommendation, manual, source_ad), sonst null. Empfehlungen sind schreibgeschützt. Test Mode benötigt bei Aktivierung IDs, ruft keine Katalog-API auf und weist auf die fehlende Prüfung hin. Gespeicherte UI-Auswahlen werden übernommen; Standards werden vor dem Start erneut geprüft.