Riferimento completo del CLI

Questo è il riferimento completo del CLI di Ads Uploader. Per un'introduzione e una guida per iniziare, consulta Configurazione tramite CLI.

Comandi

Autenticazione

Esplorazione

Caricamento dei media

Creazione delle inserzioni

Gestione dei job

Flag di create

Questi flag si applicano a ads create, ads create:preview e ads create:interactive. Possono essere usati al posto o insieme a un file di specifica.

Flag di esplorazione

Questi flag sono disponibili su campaigns, adsets, adset e campaign:

Flag comuni

Formato del file di specifica

Il file JSON di specifica controlla tutti gli aspetti della creazione delle inserzioni. Sono richiesti solo due campi: una sorgente del template (adPresetId o copyFromAd) e uploadId.

Specifica minima

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

Esempio completo

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

Sorgente del template

Ne serve una per indicare al CLI quale configurazione di inserzione usare come base.

Quando usi copyFromAd, fornisci il batch di caricamento e, opzionalmente, la campagna e il gruppo di inserzioni:

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

Per trovare l'ID di inserzione giusto, esplora il tuo account: ads campaigns, poi ads campaign <id>, poi ads adset <id>, poi ads ad <id>.

Struttura della campagna

Per impostazione predefinita, le inserzioni vanno nella campagna dell'inserzione di template. Puoi creare una nuova campagna indicando campaign.name.

Per le modalità multi-campagna, usa campaign.mode con un array campaigns:

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

Modalità di gruppo di inserzioni

Per impostazione predefinita, le inserzioni vanno nel gruppo di inserzioni esistente dell'inserzione di template. Le seguenti modalità ti danno il controllo su come le inserzioni vengono distribuite tra i gruppi.

Creare un nuovo gruppo di inserzioni:

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

Usare un gruppo esistente tramite ID:

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

Un gruppo di inserzioni per ogni file caricato:

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

Raggruppare automaticamente in gruppi di dimensione fissa:

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

Gruppi personalizzati con controllo totale su quali file vanno dove:

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

Pattern di nome del gruppo di inserzioni per le modalità multi-gruppo:

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

Il raggruppamento per variante raggruppa le inserzioni per identificatore di variazione nello stesso gruppo:

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

Override di budget e offerta

Sovrascrivi il budget giornaliero e/o l'importo dell'offerta nei nuovi gruppi di inserzioni. I valori sono nelle unità monetarie del tuo account (ad esempio 50 per 50 $ o 50 euro).

dailyBudget e bidAmount sono campi Meta indipendenti:

• Campagne ABO (il budget è sul gruppo di inserzioni): puoi impostare dailyBudget, bidAmount o entrambi. Le strategie con bid cap come COST_CAP, LOWEST_COST_WITH_BID_CAP e TARGET_COST richiedono un bidAmount insieme al budget.
• Campagne CBO (il budget è sulla campagna): non impostare dailyBudget sul gruppo di inserzioni, Meta lo rifiuta perché il budget arriva già dalla campagna. Per le strategie con bid cap, imposta solo bidAmount.

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

Disponibili anche come flag del CLI: --daily-budget 50, --bid-amount 5 o entrambi.

Configurazione del testo

Testo comune applica lo stesso testo a tutte le inserzioni:

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

Testo per inserzione ti consente di impostare un testo unico per ogni file:

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

Le chiavi per inserzione sono nomi di file (non percorsi completi). Ogni voce supporta: headlines, bodies, descriptions, cta, link, displayUrl, urlTags. I campi non specificati vengono ereditati dall'inserzione di template.

I preset di testo ti permettono di caricare una configurazione di testo salvata:

{ "textPresetId": "preset_id_here" }

Non puoi combinare textPresetId con texts.

Le opzioni di strategia controllano come vengono gestite le variazioni multiple di testo:

• "flexible" (predefinita) lascia che Meta ottimizzi tra le tue variazioni di testo. Più titoli e corpi diventano opzioni che Facebook mescola e combina.
• "separate" crea un'inserzione separata per ogni combinazione di testo.

CTA e link

Un CTA a livello superiore si applica a tutte le inserzioni. I CTA per inserzione in texts.perAd lo sovrascrivono.

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

Tipi di 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

I CTA specifici per obiettivo vengono ereditati dall'inserzione di template e non devono essere impostati manualmente. Impostarli sul tipo di campagna sbagliato provocherà un errore dell'API di Facebook.

Miglioramenti creativi

Controlla i miglioramenti creativi Advantage+:

{ "creativeEnhancements": "none" }

Funzioni disponibili: 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

Nella selezione mirata, elenca solo le funzioni rilevanti per il tipo di media. Le funzioni video (video_auto_crop, video_filtering) si applicano solo alle inserzioni video. Le funzioni carousel (carousel_to_video, carousel_dynamic_description, multi_share_end_card, multi_share_optimized) si applicano solo ai Carousel Ads.

Carousel Ads

Raggruppa i file caricati in Carousel Ads con testo per scheda:

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

Le schede devono fare riferimento a nomi di file del batch di caricamento. Minimo 2 schede per carosello. I file assegnati a un carosello vengono rimossi dall'elenco standard delle inserzioni.

Flexible Ads

Raggruppa più asset in una singola Flexible Ad in cui Meta sceglie il miglior asset per posizionamento:

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

Minimo 2 asset per gruppo. I file assegnati a un gruppo flexible vengono rimossi dall'elenco standard delle inserzioni.

Denominazione delle inserzioni

Personalizza il modo in cui vengono nominate le tue inserzioni:

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

Opzioni

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

Caricamento e rilevamento delle varianti

I gruppi di varianti vengono rilevati automaticamente dalle convenzioni dei nomi di file, proprio come nell'applicazione web. Consulta Varianti di proporzioni per tutti i dettagli sulle convenzioni di denominazione.

Suffissi di proporzione: hero_4x5.jpg + hero_9x16.jpg + hero_16x9.jpg vengono raggruppati in un'unica inserzione di variante.

Suffissi con parole: hero.jpg + hero_vertical.jpg + hero_horizontal.jpg vengono raggruppati in un'unica inserzione di variante.

Funzionano sia i delimitatori _ che -. Un file senza suffisso di proporzione (ad esempio hero.jpg) si raggruppa solo con le varianti _vertical/_horizontal. Per il raggruppamento basato sulle proporzioni, tutti i file devono avere suffissi di proporzione.

Pattern comuni

Caricare e creare con un preset

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

Dove spec.json contiene:

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

Copiare le impostazioni da un'inserzione esistente

Esplora il tuo account per trovare l'inserzione:

ads campaigns
ads campaign 120233848666410472
ads adset 120233848666620472
ads ad 120233848667930472

Poi crea una specifica che la referenzi:

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

Testo per inserzione con copy unico per file

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

Raggruppare automaticamente in più gruppi di inserzioni

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

Note importanti

1. Fai sempre prima l'anteprima. create:preview intercetta gli errori di configurazione prima di toccare Facebook.
2. Le inserzioni sono attive per impostazione predefinita. Usa --status PAUSED o "status": "PAUSED" nella specifica per crearle in pausa.
3. uploadId proviene dall'output del caricamento. È l'ID del batch restituito da ads upload.
4. I caricamenti sono legati a un account pubblicitario. I file vengono caricati direttamente nella libreria multimediale Facebook dell'account selezionato. L'ID del batch può essere usato solo con lo stesso account.
5. copyFromAd richiede uploadId. Devi fornire il batch di caricamento. Opzionalmente fornisci campaign.id e adSet.id per controllare il posizionamento.
6. Le chiavi di testo per inserzione sono nomi di file. Usa "hero.jpg", non "/path/to/hero.jpg".
7. textPresetId e texts si escludono a vicenda. Usa uno o l'altro, non entrambi.
8. I CTA specifici per obiettivo vengono ereditati dal template. Non impostare MESSAGE_PAGE, WHATSAPP_MESSAGE, ecc. manualmente.