Configuration par CLI

Le CLI d'Ads Uploader (interface en ligne de commande) te permet de téléverser des médias et de créer des annonces Meta depuis un terminal. L'accès au CLI est réservé aux forfaits payants et n'est pas disponible pendant l'essai.

Le CLI suit la même structure que l'application web. Si tu as déjà téléversé des annonces avec l'application web, le CLI te paraîtra logique tout de suite : tu choisis une annonce source ou un préréglage, tu ajoutes tes médias, tu prévisualises, puis tu crées.

Les préréglages que tu crées dans l'application web apparaissent dans le CLI, et tu peux enregistrer de nouveaux préréglages API depuis le CLI avec ads presets:save. Le CLI utilise aussi les mêmes références de builds enregistrés que l'uploader web et le MCP, tu peux donc reprendre un build en cours sans tout recommencer.

Pourquoi utiliser le CLI ? Il te donne le même pipeline de lancement Ads Uploader, via une interface pensée pour les agents IA. Charger plusieurs lots est plus rapide, et tu peux laisser un agent rédiger le texte des annonces et assembler les builds pour toi. Choisis le CLI quand tu veux faire tourner toute ton activité via un agent. Pour une aide ponctuelle et ciblée dans un flux de travail centré sur le web, consulte CLI ou MCP ? sur la page MCP.

La plupart des gens pilotent le CLI via un agent IA comme Claude Code ou Cursor. Consulte Utilisation avec l'IA plus bas.

Installation et connexion

Le CLI nécessite Node.js 18 ou plus récent. Installe-le depuis npm :

npm install -g @adsuploader/cli

Puis connecte-toi :

ads login

ads login ouvre ton navigateur pour que tu approuves la connexion avec ton compte Ads Uploader. Lance-le sur un ordinateur où tu peux ouvrir un navigateur et te connecter à adsuploader.com. Le CLI utilise ensuite ta connexion Meta existante.

Durée d'une connexion. Un jeton de connexion dure 30 jours. Ensuite, relance ads login. Tu peux voir et révoquer tes sessions CLI sous Account > Profile, dans la carte CLI Sessions.

Mises à jour. Le CLI te prévient quand une nouvelle version sort. Mets-le à jour avec :

npm update -g @adsuploader/cli

Lance ads --version pour voir quelle version tu as.

Définir ton compte publicitaire

Lance ads accounts pour lister les comptes publicitaires liés à ton compte Meta, puis définis un compte par défaut :

ads account act_123456789

C'est l'équivalent du sélecteur de compte de l'application web. Si on vient de te donner accès à un nouveau compte publicitaire dans Meta, lance ads accounts:refresh pour récupérer la liste à nouveau tout de suite.

Explorer ton compte

Avant de créer des annonces, tu peux parcourir ton compte depuis le terminal, comme tu le ferais dans l'application web :

C'est ainsi que tu trouves l'annonce dont copier les paramètres, ou le préréglage ou le build à utiliser.

Téléverser des médias

Téléverse des images et des vidéos dans ton compte publicitaire avec ads upload :

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

Chaque téléversement renvoie un ID de lot. Tu l'utilises au moment de créer les annonces. Lance ads uploads pour voir tes lots récents.

ads upload repère tout seul les liens HTTPS. Tu peux mélanger fichiers locaux et liens dans une même commande : les fichiers locaux passent en premier, puis Ads Uploader télécharge chaque lien sur son serveur dans le même lot. Ainsi, le regroupement par ratio et l'association des miniatures fonctionnent toujours sur l'ensemble. Les liens publics vers des fichiers Google Drive fonctionnent comme n'importe quel autre lien. Pour un dossier Drive entier, utilise ads upload:drive ; le dossier doit être partagé en Anyone with the link (Viewer).

Nomme tes fichiers avec des suffixes de ratio et le CLI regroupe les versions pour toi, comme dans l'application web. Consulte Variantes de format d'image.

Si certains fichiers échouent (par exemple à cause d'une coupure réseau), lance ads upload --retry-failed pour relancer les fichiers en échec de ton dernier lot en échec. Ajoute un ID de lot pour relancer un lot précis.

Créer des annonces

La création d'annonces se fait en deux étapes : preview (aperçu) et create (création).

Le fichier de spécification

Un fichier de spécification JSON indique au CLI ce qu'il doit construire. La spécification la plus simple pointe vers un préréglage enregistré et ton lot de téléversement :

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

Tu peux aussi copier les paramètres d'une annonce existante au lieu d'un préréglage :

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

Pour trouver l'ID de l'annonce, explore avec ads campaigns, ads campaign <id>, ads adset <id> et ads ad <id>. Les annonces créées à partir d'une publication de Page existante ne peuvent pas servir de modèles, car elles n'ont pas de paramètres créatifs copiables.

Tu peux aussi te passer du fichier de spécification et lancer un build enregistré avec --build <buildId>.

Toujours prévisualiser d'abord

Prévisualise toujours avant de créer. ads create:preview spec.json montre exactement ce qui serait créé, sans rien créer dans Meta. Ça permet de repérer les erreurs de configuration avant que quoi que ce soit ne soit mis en ligne.

Créer

Quand l'aperçu te convient, lance ads create spec.json. Les annonces sont mises en ligne par défaut, comme dans l'application web. Pour les créer en pause, ajoute --status PAUSED ou définis "options": { "status": "PAUSED" } dans la spécification.

Dupliquer des annonces existantes par ID de publication

Le CLI peut aussi lancer le Duplicator, qui copie une annonce existante dans une autre campagne ou un autre ensemble de publicités en conservant l'engagement de sa publication :

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

Prévisualise d'abord la correspondance entre source et destination en lançant les mêmes arguments avec ads duplicator:post-id:preview. Consulte Options de duplication par Post ID pour chaque option et le format de spécification.

Référence complète

Pour chaque commande et option, le format complet de spécification, les améliorations créatives, les annonces carrousel, flexibles et Multi Media, les variables de nommage et les limites des spécifications, consulte la Référence complète du CLI.

Suivre les tâches

La création d'annonces tourne en arrière-plan. Le CLI affiche la progression en direct pendant l'exécution, et tu peux vérifier une tâche plus tard :

ads create et --follow suivent une tâche pendant 30 minutes maximum à la fois. Sur de très gros lots, le CLI peut arrêter de suivre avec un message "Still running" avant la fin de la tâche. Ce n'est pas un échec : la tâche continue de tourner sur le serveur. Reprends le suivi avec ads jobs JOB_ID --follow. Dans ce cas, le code de sortie est 2 (0 signifie un succès et 1 une erreur).

Tu peux lancer une seule tâche de création d'annonces à la fois par utilisateur. Si tu en lances une autre pendant qu'une tourne, le CLI te demande d'attendre qu'elle se termine ou de l'annuler.

Limites de requêtes

Le CLI est limité en nombre de requêtes, par utilisateur et par type de requête. Un usage normal n'atteint jamais ces limites, mais un script qui s'emballe reçoit une réponse 429 Rate Limit Exceeded avec un en-tête Retry-After. N'enveloppe pas les commandes du CLI dans des boucles d'interrogation (comme watch ou des boucles shell while). Utilise plutôt ads jobs JOB_ID --follow pour suivre la progression en direct.

Paramètres et variables d'environnement

Lance ads config pour vérifier ta configuration. Il indique si tu es connecté, ton e-mail, ton compte publicitaire par défaut, l'URL de l'API et le dossier de configuration (~/.config/adsuploader/). Ta connexion est enregistrée dans credentials.json dans ce dossier, lisible par toi seul. ads whoami affiche ton e-mail, ton compte par défaut et l'URL de l'API.

Conseils

• Prévisualise toujours d'abord. create:preview repère les erreurs de configuration avant la création de toute annonce Meta.
• Les annonces sont en ligne par défaut. Utilise --status PAUSED si tu veux d'abord les vérifier dans Ads Manager.
• Les téléversements appartiennent à un seul compte publicitaire. Un ID de lot ne fonctionne qu'avec le compte publicitaire dans lequel tu as téléversé.
• Les préréglages viennent de l'application web. Crée tes préréglages dans l'application web, ou enregistre des préréglages API avec ads presets:save, puis utilise-les par ID dans le CLI.

Utilisation avec l'IA

Le CLI est conçu pour être piloté par des agents IA comme Claude Code ou Cursor. Après l'installation et la connexion, donne à ton agent le fichier de skill pour qu'il connaisse chaque commande et chaque option de spécification.

Le fichier de skill est fourni dans le paquet npm. Avec l'installation globale ci-dessus, il se trouve ici :

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

Dans Claude Code, installe-le comme un skill nommé ads :

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

Claude Code le charge ensuite quand tu demandes du travail sur tes annonces, ou tu peux taper /ads. Dans d'autres outils IA comme Cursor, ajoute SKILL.md comme règle ou fichier de contexte.

Le CLI est une interface pour les media buyers et leurs agents. Il n'est pas prévu pour être intégré à d'autres applications.

Exemple de prompt

Une fois tout configuré, donne à ton agent des instructions comme celle-ci :

J'ai de nouvelles créas dans mon dossier downloads/ads. Téléverse-les et crée des annonces avec les mêmes paramètres que mon préréglage d'achat Summer Sale. Regroupe-les en ensembles de publicités de cinq, nommés avec la date du jour, avec un budget quotidien de 25 $. Rédige un texte unique pour chaque image selon ce qu'elle montre. Mets en pause au niveau de l'ensemble de publicités et prévisualise d'abord.

Accès à l'API

Le CLI et le serveur MCP communiquent tous les deux avec l'API v1 d'Ads Uploader. Ils utilisent le jeton que tu obtiens avec ads login ou en te connectant au serveur MCP. Il n'existe pas de clés API autonomes pour l'instant, alors utilise le CLI ou le MCP quand tu veux un accès programmatique à Ads Uploader.

Annonces de partenariat

Le CLI peut lancer des annonces de partenariat de deux façons :

• Avec tes propres médias. Utilise une spécification normale (image, vidéo, carrousel, flexible, Multi Media ou variantes de ratio) et ajoute profile.partnership.enabled: true avec les ID de ton partenaire. Tu peux définir un partenaire différent par annonce ou par ensemble de publicités, ou choisir No Partner pour certaines lignes.
• À partir de publications Instagram existantes. Importe une publication Instagram autorisée par URL, shortcode, ID de média ou code d'annonce avec mediaItems[].kind: "partnershipPost".

Chaque partenaire doit avoir un accès approuvé aux annonces de partenariat, et cette approbation est revérifiée à l'aperçu et à la création. Pour les formats de spécification complets, les clés de portée et les limites, consulte Annonces de partenariat avec tes propres médias et Spécification de partenariat à partir d'une publication Instagram existante dans la Référence complète du CLI.