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 > Profile in der Karte CLI Sessions.

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.

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. Anzeigen, die aus einem bestehenden Page-Beitrag gebaut wurden, kannst du nicht als Vorlage nutzen, weil sie keine kopierbaren Creative-Einstellungen haben.

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

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. Eigenständige API-Keys gibt es derzeit nicht. Nutze also das CLI oder MCP, wenn du programmatisch auf Ads Uploader zugreifen willst.

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

Jeder Partner braucht einen genehmigten Zugang für Partnership-Werbung, und die Genehmigung wird bei der Vorschau und beim Erstellen erneut geprüft. 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.