Référence complète du CLI

Voici la référence complète du CLI d'Ads Uploader. Pour une introduction et un guide de démarrage, consulte Configuration par CLI.

Commandes

Authentification

Exploration

Envoi de médias

Création d'annonces

Gestion des tâches

Flags de create

Ces flags s'appliquent à ads create, ads create:preview et ads create:interactive. Ils peuvent être utilisés à la place ou en complément d'un fichier de spécification.

Flags d'exploration

Ces flags sont disponibles sur campaigns, adsets, adset et campaign :

Flags communs

Format du fichier de spécification

Le fichier JSON de spécification contrôle tous les aspects de la création d'annonces. Seuls deux champs sont obligatoires : une source de modèle (adPresetId ou copyFromAd) et uploadId.

Spécification minimale

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

Exemple complet

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

Source de modèle

Tu as besoin de l'un de ces champs pour indiquer au CLI quelle configuration d'annonce utiliser comme base.

Lorsque tu utilises copyFromAd, fournis le lot d'envoi et, en option, la campagne et l'ensemble d'annonces :

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

Pour trouver le bon ID d'annonce, explore ton compte : ads campaigns, puis ads campaign <id>, puis ads adset <id>, puis ads ad <id>.

Structure de campagne

Par défaut, les annonces vont dans la campagne de l'annonce modèle. Tu peux créer une nouvelle campagne en indiquant campaign.name.

Pour les modes multi-campagnes, utilise campaign.mode avec un tableau campaigns :

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

Modes d'ensemble d'annonces

Par défaut, les annonces vont dans l'ensemble d'annonces existant de l'annonce modèle. Les modes suivants te donnent le contrôle sur la façon dont les annonces sont réparties entre les ensembles.

Créer un nouvel ensemble d'annonces :

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

Utiliser un ensemble existant par ID :

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

Un ensemble d'annonces par fichier envoyé :

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

Regrouper automatiquement en ensembles d'une taille fixe :

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

Groupes personnalisés avec contrôle total sur la répartition des fichiers :

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

Motif de nommage de l'ensemble d'annonces pour les modes multi-ensembles :

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

Regroupement par variante regroupe les annonces par identifiant de variation dans le même ensemble :

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

Remplacement du budget et de l'enchère

Remplace le budget quotidien et/ou le bid sur les nouveaux ensembles d'annonces. Les valeurs sont dans les unités monétaires de ton compte (par exemple, 50 pour 50 $ ou 50 euros).

dailyBudget et bidAmount sont des champs Meta indépendants :

• Campagnes ABO (le budget est sur l'ensemble d'annonces) : tu peux définir dailyBudget, bidAmount ou les deux. Les stratégies avec bid cap comme COST_CAP, LOWEST_COST_WITH_BID_CAP et TARGET_COST nécessitent un bidAmount en plus du budget.
• Campagnes CBO (le budget est sur la campagne) : ne définis pas dailyBudget sur l'ensemble d'annonces ; Meta le rejette car le budget vient déjà de la campagne. Pour les stratégies avec bid cap, définis uniquement bidAmount.

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

Aussi disponibles en flags du CLI : --daily-budget 50, --bid-amount 5, ou les deux.

Configuration de texte

Texte commun applique le même texte à toutes les annonces :

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

Texte par annonce te permet de définir un texte unique pour chaque fichier :

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

Les clés par annonce sont des noms de fichier (pas des chemins complets). Chaque entrée prend en charge : headlines, bodies, descriptions, cta, link, displayUrl, urlTags. Les champs que tu ne spécifies pas sont hérités de l'annonce modèle.

Les préréglages de texte te permettent de charger une configuration de texte enregistrée :

{ "textPresetId": "preset_id_here" }

Tu ne peux pas combiner textPresetId avec texts.

Les options de stratégie contrôlent la gestion des multiples variations de texte :

• "flexible" (par défaut) laisse Meta optimiser entre tes variations de texte. Plusieurs titres et corps deviennent des options que Facebook mélange et combine.
• "separate" crée une annonce distincte pour chaque combinaison de texte.

CTA et liens

Un CTA au niveau supérieur s'applique à toutes les annonces. Les CTA par annonce dans texts.perAd le remplacent.

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

Types de CTA standard : 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

Les CTA spécifiques à un objectif sont hérités de l'annonce modèle et ne doivent pas être définis manuellement. Les définir sur le mauvais type de campagne provoquera une erreur de l'API Facebook.

Améliorations créatives

Contrôle les améliorations créatives Advantage+ :

{ "creativeEnhancements": "none" }

Fonctions disponibles : 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

Lors d'une sélection ciblée, ne liste que les fonctions pertinentes pour le type de média. Les fonctions vidéo (video_auto_crop, video_filtering) ne s'appliquent qu'aux annonces vidéo. Les fonctions carrousel (carousel_to_video, carousel_dynamic_description, multi_share_end_card, multi_share_optimized) ne s'appliquent qu'aux Carousel Ads.

Carousel Ads

Regroupe les fichiers envoyés dans des Carousel Ads avec texte par carte :

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

Les cartes doivent référencer des noms de fichier du lot d'envoi. Minimum 2 cartes par carrousel. Les fichiers affectés à un carrousel sont retirés de la liste standard des annonces.

Flexible Ads

Regroupe plusieurs ressources dans une seule Flexible Ad où Meta choisit la meilleure ressource par emplacement :

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

Minimum 2 ressources par groupe. Les fichiers affectés à un groupe flexible sont retirés de la liste standard des annonces.

Nommage des annonces

Personnalise la façon dont tes annonces sont nommées :

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

Options

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

Envoi et détection de variantes

Les groupes de variantes sont détectés automatiquement à partir des conventions de nom de fichier, tout comme dans l'application web. Consulte Variantes de rapport d'aspect pour tous les détails sur les conventions de nommage.

Suffixes de rapport : hero_4x5.jpg + hero_9x16.jpg + hero_16x9.jpg sont regroupés dans une même annonce de variante.

Suffixes en mots : hero.jpg + hero_vertical.jpg + hero_horizontal.jpg sont regroupés dans une même annonce de variante.

Les délimiteurs _ et - fonctionnent tous deux. Un fichier sans suffixe de rapport (par exemple hero.jpg) ne se regroupe qu'avec les variantes _vertical/_horizontal. Pour un regroupement par rapport, tous les fichiers ont besoin de suffixes de rapport.

Modèles courants

Envoyer et créer avec un préréglage

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

Où spec.json contient :

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

Copier les paramètres d'une annonce existante

Explore ton compte pour trouver l'annonce :

ads campaigns
ads campaign 120233848666410472
ads adset 120233848666620472
ads ad 120233848667930472

Puis crée une spécification qui la référence :

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

Texte par annonce avec copy unique par fichier

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

Regrouper automatiquement en plusieurs ensembles d'annonces

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

Notes importantes

1. Toujours prévisualiser d'abord. create:preview détecte les erreurs de configuration avant de toucher Facebook.
2. Les annonces sont actives par défaut. Utilise --status PAUSED ou "status": "PAUSED" dans la spécification pour les créer en pause.
3. uploadId provient de la sortie d'envoi. C'est l'ID de lot renvoyé par ads upload.
4. Les envois sont liés à un compte publicitaire. Les fichiers sont envoyés directement dans la bibliothèque de médias Facebook du compte sélectionné. L'ID de lot ne peut être utilisé qu'avec le même compte.
5. copyFromAd a besoin de uploadId. Tu dois fournir le lot d'envoi. Optionnellement, fournis campaign.id et adSet.id pour contrôler l'emplacement.
6. Les clés de texte par annonce sont des noms de fichier. Utilise "hero.jpg", pas "/path/to/hero.jpg".
7. textPresetId et texts sont mutuellement exclusifs. Utilise l'un ou l'autre, pas les deux.
8. Les CTA spécifiques à un objectif sont hérités du modèle. Ne définis pas MESSAGE_PAGE, WHATSAPP_MESSAGE, etc. manuellement.