Configurazione via CLI

Il CLI di Ads Uploader (interfaccia a riga di comando) ti permette di caricare media e creare annunci Meta da un terminale. L'accesso al CLI è riservato ai piani a pagamento e non è disponibile durante la prova.

Il CLI segue la stessa struttura dell'applicazione web. Se hai già caricato annunci dall'applicazione web, il CLI ti sarà subito chiaro: scegli un annuncio di origine o un preset, aggiungi i media, controlli l'anteprima e poi crei.

I preset che crei nell'applicazione web compaiono nel CLI, e puoi salvare nuovi preset API dal CLI con ads presets:save. Il CLI usa anche gli stessi riferimenti ai build salvati dell'uploader web e dell'MCP, così puoi continuare un build in corso senza ripartire da zero.

Perché usare il CLI? Ti offre la stessa pipeline di lancio di Ads Uploader tramite un'interfaccia pensata per gli agenti IA. Caricare più batch è più veloce, e puoi lasciare che un agente scriva il copy degli annunci e assembli i build per te. Scegli il CLI quando vuoi gestire tutto il tuo lavoro tramite un agente. Per un aiuto mirato all'interno di un flusso di lavoro basato soprattutto sull'applicazione web, vedi CLI o MCP? nella pagina dell'MCP.

La maggior parte delle persone usa il CLI tramite un agente IA come Claude Code o Cursor. Vedi Uso con l'IA più avanti.

Installazione e accesso

Il CLI richiede Node.js 18 o successivo. Installalo da npm:

npm install -g @adsuploader/cli

Poi accedi:

ads login

ads login apre il browser così puoi approvare l'accesso con il tuo account Ads Uploader. Eseguilo su un computer dove puoi aprire un browser e accedere a adsuploader.com. Il CLI usa poi la tua connessione Meta esistente.

Quanto dura un accesso. Un token di accesso dura 30 giorni. Dopo, esegui di nuovo ads login. Puoi vedere e revocare le tue sessioni CLI in Account > Profile, nella scheda CLI Sessions.

Aggiornamenti. Il CLI ti avvisa quando esce una nuova versione. Aggiorna con:

npm update -g @adsuploader/cli

Esegui ads --version per vedere quale versione hai.

Imposta il tuo account pubblicitario

Esegui ads accounts per elencare gli account pubblicitari collegati al tuo account Meta, poi imposta quello predefinito:

ads account act_123456789

È lo stesso del selettore di account nell'applicazione web. Se ti hanno appena dato accesso a un nuovo account pubblicitario in Meta, esegui ads accounts:refresh per recuperare subito di nuovo l'elenco.

Esplora il tuo account

Prima di creare annunci, puoi esplorare il tuo account dal terminale, proprio come faresti nell'applicazione web:

È così che trovi l'annuncio da cui copiare le impostazioni, oppure il preset o il build da usare.

Carica i media

Carica immagini e video nel tuo account pubblicitario con 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/..."

Ogni caricamento restituisce un ID batch. Lo usi quando crei gli annunci. Esegui ads uploads per vedere i tuoi batch recenti.

ads upload riconosce da solo i link HTTPS. Puoi combinare file locali e link in un unico comando: i file locali vengono caricati per primi, poi Ads Uploader scarica ogni link sul proprio server nello stesso batch. In questo modo il raggruppamento per formato e l'abbinamento delle miniature funzionano comunque su tutto. I link pubblici ai file di Google Drive funzionano come qualsiasi altro link. Per un'intera cartella di Drive, usa ads upload:drive; la cartella deve essere condivisa come Anyone with the link (Viewer).

Dai ai tuoi file un nome con i suffissi di formato e il CLI raggruppa le versioni per te, proprio come l'applicazione web. Vedi Varianti di formato immagine.

Se alcuni file non vengono caricati (per esempio per un calo della rete), esegui ads upload --retry-failed per riprovare i file non riusciti del tuo ultimo batch fallito. Aggiungi un ID batch per riprovare un batch specifico.

Crea gli annunci

La creazione degli annunci ha due passi: anteprima e creazione.

Il file di specifica

Un file di specifica JSON dice al CLI cosa costruire. La specifica più semplice indica un preset salvato e il tuo batch di caricamento:

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

Invece di un preset, puoi copiare le impostazioni da un annuncio esistente:

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

Per trovare l'ID dell'annuncio, esplora con ads campaigns, ads campaign <id>, ads adset <id> e ads ad <id>. Gli annunci creati da un post esistente di una Pagina non si possono usare come modelli, perché non hanno impostazioni creative copiabili.

Puoi anche saltare il file di specifica e lanciare un build salvato con --build <buildId>.

Prima l'anteprima

Controlla sempre l'anteprima prima di creare. ads create:preview spec.json mostra esattamente cosa verrebbe creato, senza creare nulla in Meta. Intercetta gli errori di configurazione prima che qualcosa vada online.

Creazione

Quando l'anteprima è corretta, esegui ads create spec.json. Gli annunci vanno online per impostazione predefinita, proprio come nell'applicazione web. Per crearli in pausa, aggiungi --status PAUSED oppure imposta "options": { "status": "PAUSED" } nella specifica.

Duplica annunci esistenti tramite ID del post

Il CLI può anche eseguire il Duplicator, che copia un annuncio esistente in un'altra campagna o in un altro gruppo di inserzioni mantenendo l'engagement del post:

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

Controlla prima la corrispondenza tra origine e destinazione eseguendo gli stessi argomenti con ads duplicator:post-id:preview. Vedi Flag per la duplicazione tramite Post ID per tutti i flag e il formato della specifica.

Riferimento completo

Per tutti i comandi e i flag, il formato completo della specifica, i miglioramenti creativi, gli annunci carosello, flessibili e Multi Media, i segnaposto di denominazione e i limiti della specifica, vedi il Riferimento completo del CLI.

Monitora i job

La creazione degli annunci avviene in background. Il CLI mostra l'avanzamento mentre il job è in corso, e puoi controllare un job anche in seguito:

ads create e --follow seguono un job per un massimo di 30 minuti alla volta. Con batch molto grandi il CLI può smettere di seguirlo con un messaggio "Still running" prima che il job finisca. Non è un errore: il job continua a girare sul server. Riprendilo con ads jobs JOB_ID --follow. In questo caso il codice di uscita è 2 (0 significa successo e 1 significa errore).

Puoi eseguire un solo job di creazione annunci alla volta per utente. Se ne avvii un altro mentre uno è in corso, il CLI ti dice di aspettare che finisca o di annullarlo.

Limiti di frequenza

Il CLI ha limiti di frequenza per utente e per tipo di richiesta. Un uso normale non li raggiunge mai, ma uno script fuori controllo riceve una risposta 429 Rate Limit Exceeded con un header Retry-After. Non inserire i comandi del CLI in cicli di polling (come watch o cicli while della shell). Usa invece ads jobs JOB_ID --follow per l'avanzamento in tempo reale.

Impostazioni e variabili d'ambiente

Esegui ads config per controllare la tua configurazione. Mostra se hai effettuato l'accesso, la tua email, il tuo account pubblicitario predefinito, l'URL dell'API e la cartella di configurazione (~/.config/adsuploader/). Il tuo accesso è salvato in credentials.json in quella cartella, leggibile solo da te. ads whoami mostra la tua email, l'account predefinito e l'URL dell'API.

Suggerimenti

• Controlla sempre prima l'anteprima. create:preview intercetta gli errori di configurazione prima che venga creato qualsiasi annuncio Meta.
• Gli annunci vanno online per impostazione predefinita. Usa --status PAUSED se vuoi controllarli prima in Ads Manager.
• I caricamenti appartengono a un solo account pubblicitario. Un ID batch funziona solo con l'account pubblicitario su cui hai caricato.
• I preset arrivano dall'applicazione web. Crea i preset nell'applicazione web, oppure salva preset API con ads presets:save, poi usali tramite ID nel CLI.

Uso con l'IA

Il CLI è pensato per essere usato da agenti IA come Claude Code o Cursor. Dopo l'installazione e l'accesso, dai al tuo agente il file della skill così conosce tutti i comandi e le opzioni della specifica.

Il file della skill è incluso nel pacchetto npm. Con l'installazione globale descritta sopra, si trova in:

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

In Claude Code, installalo come skill chiamata ads:

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

Claude Code lo carica quando chiedi un lavoro sugli annunci, oppure puoi digitare /ads. In altri strumenti IA come Cursor, aggiungi SKILL.md come regola o file di contesto.

Il CLI è un'interfaccia per i media buyer e i loro agenti. Non è pensato per essere integrato in altre applicazioni.

Prompt di esempio

Una volta configurato, dai al tuo agente istruzioni come:

Ho nuovi creativi nella cartella downloads/ads. Caricali e crea annunci con le stesse impostazioni del mio preset di acquisto Summer Sale. Raggruppali in gruppi di inserzioni da cinque con la data di oggi nel nome e un budget giornaliero di 25 $. Scrivi un copy unico per ogni immagine in base a ciò che mostra. Metti in pausa a livello di gruppo di inserzioni e mostrami prima l'anteprima.

Accesso API

Il CLI e il server MCP comunicano entrambi con l'API v1 di Ads Uploader. Usano il token che ottieni con ads login o accedendo al server MCP. Al momento non esistono chiavi API autonome, quindi usa il CLI o l'MCP quando vuoi un accesso programmatico ad Ads Uploader.

Annunci di partnership

Il CLI può lanciare annunci di partnership in due modi:

• Con i tuoi media. Usa una normale specifica per immagine, video, carosello, flessibile, Multi Media o varianti di formato e aggiungi profile.partnership.enabled: true con gli ID del tuo partner. Puoi impostare un partner diverso per ogni annuncio o per ogni gruppo di inserzioni, oppure scegliere No Partner per alcune righe.
• Da post Instagram esistenti. Importa un post Instagram autorizzato tramite URL, shortcode, ID media o codice annuncio con mediaItems[].kind: "partnershipPost".

Ogni partner deve avere un accesso approvato alla pubblicità di partnership, e l'approvazione viene verificata di nuovo in anteprima e in creazione. Per le strutture complete della specifica, le chiavi di ambito e i limiti, vedi Annunci di partnership con i tuoi media e Specifica per annunci di partnership da post Instagram esistenti nel Riferimento completo del CLI.