Come Configurare la Meta Ads CLI: Tutorial Passo-Passo per il 2026

Per configurare la Meta Ads CLI, devi creare un System User nel Business Manager, generare un token che non scade mai con i permessi ads_management, ads_read e business_management, collegare il tuo Ad Account e la Page come asset, e poi puntare la CLI a quel token tramite un file di configurazione. L'intero processo richiede circa 45 minuti se hai accesso admin a un Business Manager, una Pagina Facebook e un metodo di pagamento verificato sull'Ad Account.

Questo è l'approfondimento che accompagna la nostra panoramica su come gestire Facebook Ads con agenti AI. Quel pezzo spiega perché una configurazione guidata da CLI batte i click su Ads Manager per chiunque gestisca più di una manciata di campagne. Questo è la guida pratica: ogni passo, ogni messaggio di errore in cui siamo incappati mentre costruivamo il nostro stack, e una vera prima campagna alla fine.

Cosa Fa Veramente la Meta Ads CLI

La "Meta Ads CLI" non è un singolo binario ufficiale. È un sottile strato di automazione lato server che si trova tra i tuoi script e la Meta Marketing API. Tu scrivi codice Python o Node, la CLI gestisce l'autenticazione, la firma delle richieste e il token System User a lunga durata, e le tue campagne vanno online attraverso graph.facebook.com/v23.0/ senza che nessuno clicchi in Ads Manager.

La parte difficile non è il codice del wrapper — sono cento righe. La parte difficile è il rituale di configurazione in 7 passaggi all'interno del Business Manager che produce un token che Meta accetterà davvero per il traffico di produzione. Quel rituale rimuove il balletto del refresh OAuth e il dolore della scadenza del token che prima o poi rompe ogni automazione basata sul browser.

Il ritorno è reale. Una volta che lo stack CLI è in funzione, puoi lanciare una campagna con 6 varianti di annunci in meno di 90 secondi, estrarre le performance di ieri in un report giornaliero alle 7:00 del mattino via cron e mettere automaticamente in pausa gli annunci che vanno male — senza mai accedere ad Ads Manager.

Prerequisiti

Prima di iniziare, assicurati di avere tutto questo a posto. Saltare uno qualsiasi di questi punti ti manda in un tunnel di 2 ore più tardi.

Ti serve un account Meta Business Manager con diritti di admin — gli account Facebook personali non funzioneranno per i token System User. Ti serve una Pagina Facebook dove sei elencato come admin, non solo come editor. Ti serve un Meta Ad Account all'interno di quel Business Manager con un metodo di pagamento verificato e almeno un Paese approvato per la fatturazione. Ti serve un Pixel (o "Dataset" nella nuova terminologia) configurato per qualsiasi sito web verso cui stai indirizzando il traffico. E ti serve Python 3.10+ o Node 18+ installato localmente con la possibilità di installare pacchetti.

Se non hai ancora un Pixel, creane uno prima di continuare. Anche se hai intenzione di usare solo la Conversions API (CAPI) — come facciamo noi — hai comunque bisogno dell'ID Pixel come indirizzo di routing per gli eventi lato server.

La Configurazione in 7 Passi

Questi passaggi sono sequenziali. Ognuno sblocca il successivo. Saltare avanti rompe la catena in modi difficili da debuggare perché i messaggi di errore di Meta sono spesso fuorvianti.

Passo 1: Crea un System User nel Business Manager

Vai su Impostazioni Business → Utenti → System User. Clicca su "Aggiungi" e crea un nuovo System User. Il nome non conta per l'API ma conta per la tua futura sanità mentale — chiamalo qualcosa come your-brand-agent così tra sei mesi ricordi cosa sta facendo. Scegli il ruolo "Admin" (non "Dipendente") perché i System User senza diritti di admin non possono gestire le Custom Conversions o gli eventi Pixel.

Quando abbiamo costruito il nostro stack, abbiamo creato emaxstudioagent. L'ID del System User viene assegnato automaticamente (numero a 15 cifre). Annotalo.

Passo 2: Crea una Developer App con Use Case Marketing API

Vai su developers.facebook.com → Le Mie App → Crea App. Scegli use case "Marketing API" se lo vedi nel menu a tendina. Se vedi solo "Altro", va bene comunque — i token System User funzionano in entrambi i modi. L'interfaccia tedesca lo etichetta "Werbeanzeigen mit Marketing API" mentre quella inglese lo chiama solo "Marketing API" o "Other". Entrambi producono token identici.

Imposta l'app come tipo Business, non Consumer. Aggiungi il prodotto Marketing API all'app dalla sidebar a sinistra. L'app parte in Development Mode. Devi spostarla in Live Mode (vedi sotto) prima che il token System User funzioni per annunci reali.

Per passare a Live Mode, Meta richiede un URL pubblico della privacy policy e un'icona dell'app (1024×1024 PNG). Entrambi sono non negoziabili. L'icona dell'app non deve essere rifinita — basta un placeholder — ma l'URL deve effettivamente risolversi in una pagina di privacy policy. Noi ospitiamo la nostra su /legal nel nostro dominio principale.

Passo 3: Genera un Token System User che Non Scade Mai

Torna in Impostazioni Business → System User → [il tuo System User] → clicca "Genera Nuovo Token". Seleziona l'app che hai appena creato al Passo 2. Poi seleziona i permessi:

• ads_management — necessario per creare, modificare e mettere in pausa le campagne
• ads_read — necessario per estrarre insights e dati di reporting
• business_management — necessario per gestire asset e custom conversions

Imposta la scadenza su "Mai". I token System User sono gli unici token Meta che genuinamente non scadono mai — gli User Access Token arrivano al massimo a 60 giorni, i Page Token dipendono dall'User Token da cui sono derivati. Questo è l'intero punto di usare un System User invece di OAuth per l'automazione backend.

Copia il token immediatamente. Meta lo mostra una sola volta. Conservalo in un gestore di segreti o in un file .env con chmod 600. Non committarlo mai su git.

Passo 4: Collega l'Ad Account e la Page come Asset

Il System User esiste ma non ha ancora accesso a niente. Devi assegnare esplicitamente gli asset. In Impostazioni Business → System User → [il tuo System User] → clicca "Aggiungi Asset".

Assegna il tuo Ad Account con i permessi completi ("Gestisci Campagne" + "Gestisci Performance"). Assegna la tua Page con i permessi completi. Assegna il tuo Pixel/Dataset con i permessi completi. Se hai più Ad Account e vuoi che la CLI li gestisca tutti, assegnali tutti.

Quando abbiamo configurato il nostro, abbiamo assegnato act_975780295197610 (il nostro Ad Account) e la Page 1113585798495892 (la nostra pagina EMAX Studio) più il Pixel 1464075091373537. Il prefisso act_ sugli ID degli Ad Account è obbligatorio quando chiami l'API — è parte dell'ID effettivo, non una convenzione di formattazione.

Passo 5: Assegna il Permesso "Page verwalten" / "Gestisci Pagina"

Questo è il passo che frega quasi tutti la prima volta. Il Passo 4 ha assegnato la Page come asset, ma il livello di permesso di default è "Anzeigen erstellen" / "Crea Annunci" — che non basta. Il System User ha bisogno di "Page verwalten" / "Gestisci Pagina" per pubblicare creatività pubblicitarie che fanno riferimento alla Page.

Se salti questo passaggio, ogni chiamata API per la creazione di annunci restituirà un generico errore "permission denied" che non menziona la Page. Passerai ore a controllare gli scope del tuo token e i permessi dell'Ad Account mentre il problema vero è un click di profondità nelle impostazioni dell'asset Page.

Clicca sulla Page nell'elenco degli asset, scorri fino ai permessi e attiva "Gestisci Pagina" per il System User. Salva.

Passo 6: Installa la CLI e Crea un File di Configurazione

Per Python, installa l'SDK ufficiale:

pip install facebook-business

Per Node, usa il client mantenuto dalla community:

npm install facebook-nodejs-business-sdk

Crea un file di configurazione in ~/.meta-ads/config.json (o ovunque il tuo stack memorizzi i segreti):

{
  "access_token": "EAA...your-system-user-token",
  "app_id": "910292175368026",
  "app_secret": "your-app-secret",
  "ad_account_id": "act_975780295197610",
  "page_id": "1113585798495892",
  "pixel_id": "1464075091373537",
  "api_version": "v23.0"
}

Imposta i permessi: chmod 600 ~/.meta-ads/config.json. L'app_secret è opzionale per i token System User ma abilita la firma appsecret_proof, che Meta raccomanda per la produzione.

Passo 7: Esegui il Primo Comando di Test

Verifica che tutto funzioni elencando le tue campagne. In Python:

from facebook_business.api import FacebookAdsApi
from facebook_business.adobjects.adaccount import AdAccount
import json

cfg = json.load(open("/path/to/config.json"))
FacebookAdsApi.init(access_token=cfg["access_token"])
account = AdAccount(cfg["ad_account_id"])
campaigns = account.get_campaigns(fields=["name", "status", "objective"])
for c in campaigns:
    print(c["name"], c["status"], c["objective"])

Se restituisce una lista (anche vuota, se non hai ancora campagne), hai finito. Se solleva OAuthException o Permission denied, torna alla tabella degli errori qui sotto.

Errori di Configurazione Comuni e Come Risolverli

Questi sono gli 8 errori che ci hanno morso durante la costruzione. Ognuno di loro è costato ore reali. Risparmiati il dolore.

Quello della Custom Conversion è il più cattivo perché il messaggio di errore tecnicamente ti dice cosa c'è di sbagliato ma la soluzione non è ovvia. Una Custom Conversion nuova di zecca ha zero eventi nel sistema di Meta. Meta rifiuta di ottimizzare una campagna per qualcosa su cui non ha dati storici. Il trucco è lanciare la campagna ottimizzata per Landing Page Views prima, lasciare che 50+ conversioni si attivino tramite CAPI, poi passare il promoted_object dell'Ad Set a OFFSITE_CONVERSIONS con il tuo ID Custom Conversion. Dopo di che, l'ottimizzazione funziona davvero.

Una Vera Prima Campagna Passo-Passo

Ecco cosa abbiamo lanciato come nostro primo test live. Valori reali, flusso reale, risultati reali.

Crea la Campagna. Obiettivo: OUTCOME_TRAFFIC (poi passato a OUTCOME_SALES una volta ottenuti dati di conversione). Stato: PAUSED inizialmente così l'Ad Set e gli Ad possono essere creati sotto prima di portare tutto ad ACTIVE in un colpo solo. Il budget vive a livello di Ad Set nella nostra configurazione.

Crea l'Ad Set. Budget giornaliero: 1000 (centesimi = $10/giorno). Ottimizzazione: LANDING_PAGE_VIEWS. Strategia di offerta: LOWEST_COST_WITHOUT_CAP. Targeting: Paesi ["US", "GB", "CA"], età da 25 a 55, lingua inglese. Placement: feed, instagram_reels, stories, marketplace. Automazione del targeting: {"advantage_audience": 1}.

Costruisci le Creatività. Tre creatività immagine e tre creatività video — sei annunci in totale. Per le immagini abbiamo usato l'output del nostro EMAX Studio (eat your own dogfood): tre hook, tre sfondi nei colori del brand, tutti 1080×1080. Per i video, tre reel verticali di 15 secondi con sottotitoli parola per parola e voce AI, generati attraverso la nostra pipeline (descritta in How to Create an AI Marketing Campaign Step-by-Step). Ogni creatività video ha bisogno di un image_hash per il thumbnail — estrai un frame a 1.5 secondi con ffmpeg, caricalo su /adimages e usa l'hash restituito all'interno del blocco video_data.

Attiva. Porta Campagna, poi Ad Set, poi tutti i sei Ad a ACTIVE. La revisione di Meta di solito si conclude in 15-30 minuti. Gli annunci rifiutati emergono per singolo annuncio via ad.get('effective_status').

Report Giornaliero. Uno script meta_daily_report.py gira alle 7:00 ora di Berlino via cron. Estrae insights, formatta spesa / CTR / CPM / conversioni in un messaggio Telegram e mette automaticamente in pausa qualsiasi annuncio con CTR sotto lo 0.5% dopo 100+ impression. Le prime 48 ore hanno prodotto 4.200 impression, 78 click (CTR 1.86%) e 12 completamenti del Quick Scan a $1.67 per conversione — segnale sufficiente per passare l'ottimizzazione da Landing Page Views a OFFSITE_CONVERSIONS rispetto alla Custom Conversion QuickScanComplete al terzo giorno.

Trappole da Evitare

Alcune cose ti bruceranno. Ognuna l'abbiamo imparata a nostre spese.

Non hardcodare i token nel git. Anche nei repo privati. I token trapelano attraverso i log CI, i fork pubblici per sbaglio e i commit fatti prima che cambiasse la visibilità di un repo. Leggi sempre da variabili d'ambiente o da un file di configurazione con chmod-600 fuori dal repo.

Non saltare il permesso Gestisci Pagina del Passo 5. Gli errori che ottieni sembrano riguardare l'Ad Account o il token. Non è così. Ricontrolla prima il permesso dell'asset Page ogni volta che vedi un vago "permission denied" sulla creazione di creatività.

Non fare il deploy con l'app developer ancora in Development Mode. Il token funziona per l'utente che l'ha creato ma fallisce silenziosamente per qualsiasi altro contesto System User. Passa a Live Mode prima di far girare qualsiasi cosa su un server.

Non dimenticare l'image_hash per le creatività video. Senza, l'intera creazione dell'Ad fallisce con un errore fuorviante su video_data.

Non saltare CAPI se hai intenzione di scalare. I pixel del browser perdono dal 30 al 50% degli eventi a causa di iOS ATT, ad blocker e prevenzione del tracking. La Conversions API lato server ne riacquisisce la maggior parte — un weekend di lavoro che si ripaga la prima settimana che scali la spesa pubblicitaria.

Domande Frequenti

Quanto costa configurare la Meta Ads CLI?

La configurazione in sé è gratuita. La Marketing API, i token System User, il Business Manager e tutti gli strumenti per sviluppatori sono a costo zero — paghi solo per gli annunci che effettivamente fai girare. Conta su 4-6 ore di tempo di configurazione la prima volta e 30 minuti ogni volta dopo.

Posso gestire più ad account attraverso una singola installazione CLI?

Sì, ed è uno dei motivi principali per cui le agenzie usano i token System User. Aggiungi ogni Ad Account come asset in Impostazioni Business e puoi puntare a uno qualsiasi cambiando l'ad_account_id nella configurazione o passandolo come parametro. Un singolo token System User può gestire centinaia di Ad Account attraverso più Business Manager se i permessi sono a posto.

E una Google Ads CLI — la configurazione è simile?

Il concetto è simile ma la configurazione di Google è più ruvida. Google richiede un'approvazione del developer token che può richiedere dai 7 ai 21 giorni, refresh token OAuth2 che scadono periodicamente e un ulteriore strato di permessi MCC (Manager Account). Il token System User di Meta è genuinamente il più semplice dei due sistemi. Se gestisci entrambe le piattaforme, configura prima Meta per imparare i pattern.

Come ruoto i token in sicurezza se uno viene compromesso?

Genera un nuovo token System User (stessi permessi, stessa scadenza "Mai"), aggiorna la tua configurazione, testa che il nuovo token funzioni, poi revoca quello vecchio. Meta ti permette di mantenere più token attivi simultaneamente per lo stesso System User, così puoi ruotare senza downtime. Se un token trapela, revocalo immediatamente e audita la spesa pubblicitaria recente attraverso l'API per campagne non autorizzate.

Come si inserisce la Conversions API (CAPI) in questa configurazione?

CAPI è un sistema separato ma complementare. La Meta Ads CLI gestisce campagne, ad set e annunci. CAPI invia eventi di conversione lato server contro cui quegli annunci si ottimizzano. Entrambi usano lo stesso ID Pixel. Gli eventi CAPI scorrono indipendentemente da qualsiasi pixel del browser — sono la base del tracking GDPR-clean perché non sono coinvolti cookie e le PII vengono hashate prima della trasmissione. La panoramica su AI Facebook Ads con AI agents copre come CAPI si inserisce nello stack di automazione più grande.

La Verità Onesta

La Meta Ads CLI non è magia. È un modo disciplinato per rimuovere tre cose dal tuo workflow: i refresh dei token OAuth, gli accessi manuali ad Ads Manager e il costo dell'errore umano nel cliccare attraverso 14 impostazioni ogni volta che lanci un annuncio. Una volta in funzione, fai in 90 secondi quello che prima richiedeva 30 minuti.

La configurazione è laboriosa perché la strumentazione di Meta è laboriosa. Ma i passaggi sono deterministici. Segui esattamente la configurazione in 7 passi, fai attenzione agli 8 errori nella tabella e avrai uno stack pubblicitario di livello produzione entro la fine del pomeriggio. Per il quadro più ampio di come la CLI si lega alle creatività AI e al reporting giornaliero, vedi la nostra panoramica su Facebook Ads con agenti AI e AI news settimana 18, 2026 per ciò che sta cambiando nell'ecosistema pubblicitario quest'anno.

Una volta che la CLI è live, la domanda diventa quali creatività darle in pasto. Fai girare la tua landing page attraverso una scansione gratuita di 90 secondi su AI-readiness su emax.studio — ottieni un punteggio, una lista di gap di conversione e un brief di campagna pronto da lanciare in meno di due minuti.

Segui EMAX Studio: Instagram | YouTube | Facebook