Configuração da CLI

A CLI (interface de linha de comando) do Ads Uploader permite subir mídia e criar anúncios da Meta a partir de um terminal. O acesso à CLI é para planos pagos e não está disponível durante o teste.

A CLI segue a mesma estrutura do app web. Se você já subiu anúncios pelo app web, a CLI vai fazer sentido na hora: você escolhe um anúncio de origem ou um preset, adiciona sua mídia, vê a prévia e depois cria.

Os presets que você monta no app web aparecem na CLI, e você pode salvar novos API presets pela CLI com ads presets:save. A CLI também usa as mesmas referências de builds salvos do uploader web e do MCP, então você pode continuar um build em andamento sem começar de novo.

Por que usar a CLI? Ela oferece o mesmo pipeline de lançamento do Ads Uploader por uma interface feita para agentes de IA. Carregar vários lotes é mais rápido, e você pode deixar um agente escrever os textos dos anúncios e montar os builds para você. Escolha a CLI quando quiser conduzir toda a sua operação por um agente. Para ajudas pequenas e pontuais dentro de um fluxo centrado na web, veja CLI ou MCP? na página do MCP.

A maioria das pessoas usa a CLI por meio de um agente de IA, como o Claude Code ou o Cursor. Veja Usar com IA abaixo.

Instalar e entrar

A CLI precisa do Node.js 18 ou mais recente. Instale pelo npm:

npm install -g @adsuploader/cli

Depois, entre:

ads login

ads login abre seu navegador para você aprovar o login com a sua conta do Ads Uploader. Rode em um computador em que você consiga abrir um navegador e entrar em adsuploader.com. Depois disso, a CLI usa a sua conexão existente com a Meta.

Quanto tempo dura um login. Um token de login dura 30 dias. Depois disso, rode ads login de novo. Você pode ver e revogar suas sessões da CLI em Account > Profile, no card CLI Sessions.

Atualizar. A CLI avisa quando sai uma nova versão. Atualize com:

npm update -g @adsuploader/cli

Rode ads --version para ver qual versão você tem.

Definir sua conta de anúncio

Rode ads accounts para listar as contas de anúncio conectadas à sua conta Meta e depois defina uma padrão:

ads account act_123456789

Isso equivale ao seletor de conta do app web. Se você acabou de receber acesso a uma nova conta de anúncio na Meta, rode ads accounts:refresh para buscar a lista de novo na hora.

Navegar pela sua conta

Antes de criar anúncios, você pode navegar pela sua conta a partir do terminal, do mesmo jeito que faria no app web:

É assim que você encontra o anúncio de onde copiar as configurações, ou o preset ou build a usar.

Subir mídia

Suba imagens e vídeos para a sua conta de anúncio com 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/..."

Cada upload retorna um ID de lote (batch ID). Você usa esse ID quando cria os anúncios. Rode ads uploads para ver seus lotes recentes.

ads upload reconhece links HTTPS sozinho. Você pode misturar arquivos locais e links em um mesmo comando: os arquivos locais sobem primeiro, e depois Ads Uploader baixa cada link no servidor para o mesmo lote. Assim, o agrupamento por proporção e a associação de thumbnails continuam funcionando em tudo. Links públicos de arquivos do Google Drive funcionam como qualquer outro link. Para uma pasta inteira do Drive, use ads upload:drive; a pasta precisa estar compartilhada como Anyone with the link (Viewer).

Nomeie seus arquivos com sufixos de proporção e a CLI agrupa as versões para você, igual ao app web. Veja Variações de proporção.

Se alguns arquivos falharem (por exemplo, por uma queda de rede), rode ads upload --retry-failed para tentar de novo os arquivos que falharam no seu último lote com falha. Adicione um ID de lote para tentar de novo um lote específico.

Criar anúncios

Criar anúncios tem duas etapas: prévia e criação.

O arquivo de especificação

Um arquivo de especificação JSON diz à CLI o que montar. A especificação mais simples aponta para um preset salvo e para o seu lote de upload:

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

Você pode copiar as configurações de um anúncio existente em vez de um preset:

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

Para encontrar o ID do anúncio, navegue com ads campaigns, ads campaign <id>, ads adset <id> e ads ad <id>. Anúncios feitos a partir de uma publicação existente de uma Página não podem ser usados como modelo, porque não têm configurações de criativo que possam ser copiadas.

Você também pode pular o arquivo de especificação e lançar um build salvo com --build <buildId>.

Prévia primeiro

Sempre veja a prévia antes de criar. ads create:preview spec.json mostra exatamente o que seria criado, sem criar nada na Meta. Isso pega erros de configuração antes que qualquer coisa entre no ar.

Criar

Quando a prévia estiver certa, rode ads create spec.json. Os anúncios entram no ar por padrão, igual ao app web. Para criá-los pausados, adicione --status PAUSED ou defina "options": { "status": "PAUSED" } na especificação.

Duplicar anúncios existentes pelo ID da publicação

A CLI também pode rodar o Duplicador, que copia um anúncio existente para outra campanha ou conjunto de anúncios mantendo o engajamento da publicação:

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

Veja antes o mapeamento de origem para destino rodando os mesmos argumentos com ads duplicator:post-id:preview. Veja Flags de duplicação por Post ID para todas as flags e o formato da especificação.

Referência completa

Para todos os comandos e flags, o formato completo da especificação, aprimoramentos criativos, anúncios em carrossel, flexíveis e Multi Media, placeholders de nome e limites da especificação, veja a Referência completa da CLI.

Acompanhar jobs

A criação de anúncios roda em segundo plano. A CLI mostra o progresso enquanto roda, e você pode conferir um job depois:

ads create e --follow acompanham um job por até 30 minutos de cada vez. Em lotes muito grandes, a CLI pode parar de acompanhar com uma mensagem "Still running" antes de o job terminar. Isso não é uma falha: o job continua rodando no servidor. Retome com ads jobs JOB_ID --follow. Nesse caso, o código de saída é 2 (0 significa sucesso e 1 significa erro).

Você pode rodar um job de criação de anúncios por vez por usuário. Se você iniciar outro enquanto um está rodando, a CLI pede que você espere terminar ou cancele.

Limites de requisição

A CLI tem limites de requisição por usuário e por tipo de requisição. O uso normal nunca chega a esses limites, mas um script descontrolado recebe uma resposta 429 Rate Limit Exceeded com um cabeçalho Retry-After. Não coloque comandos da CLI dentro de loops de consulta (como watch ou loops while do shell). Use ads jobs JOB_ID --follow para ver o progresso ao vivo.

Configurações e variáveis de ambiente

Rode ads config para conferir sua configuração. Ele mostra se você está logado, seu email, sua conta de anúncio padrão, a URL da API e a pasta de configuração (~/.config/adsuploader/). Seu login fica salvo em credentials.json nessa pasta, que só você pode ler. ads whoami mostra seu email, sua conta padrão e a URL da API.

Dicas

• Sempre veja a prévia primeiro. create:preview pega erros de configuração antes que qualquer anúncio seja criado na Meta.
• Os anúncios entram no ar por padrão. Use --status PAUSED se quiser conferi-los no Ads Manager antes.
• Uploads pertencem a uma conta de anúncio. Um ID de lote só funciona com a conta de anúncio para a qual você subiu.
• Os presets vêm do app web. Monte presets no app web, ou salve API presets com ads presets:save, e depois use-os pelo ID na CLI.

Usar com IA

A CLI foi feita para ser conduzida por agentes de IA, como o Claude Code ou o Cursor. Depois de instalar e entrar, entregue ao seu agente o arquivo de skill para ele conhecer todos os comandos e opções de especificação.

O arquivo de skill vem dentro do pacote npm. Com a instalação global acima, ele fica em:

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

No Claude Code, instale como uma skill chamada ads:

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

O Claude Code então carrega a skill quando você pede trabalho com anúncios, ou você pode digitar /ads. Em outras ferramentas de IA, como o Cursor, adicione SKILL.md como regra ou arquivo de contexto.

A CLI é uma interface para media buyers e seus agentes. Ela não foi feita para ser embutida em outros aplicativos.

Exemplo de prompt

Depois de configurar, dê ao seu agente instruções como:

Tenho novos criativos de anúncio na minha pasta downloads/ads. Suba esses arquivos e crie anúncios usando as mesmas configurações do meu preset de compra Summer Sale. Agrupe em conjuntos de anúncios de cinco, com o nome contendo a data de hoje e orçamento diário de $25. Escreva um texto único para cada imagem com base no que ela mostra. Pause no nível do conjunto de anúncios e mostre a prévia primeiro.

Acesso à API

A CLI e o servidor MCP conversam com a API v1 do Ads Uploader. Eles usam o token que você recebe com ads login ou ao entrar no servidor MCP. Hoje não existem chaves de API avulsas, então use a CLI ou o MCP quando quiser acesso programático ao Ads Uploader.

Anúncios de parceria

A CLI pode lançar anúncios de parceria de duas formas:

• Com a sua própria mídia. Use uma especificação normal de imagem, vídeo, carrossel, flexível, Multi Media ou variante de proporção e adicione profile.partnership.enabled: true com os IDs do seu parceiro. Você pode definir um parceiro diferente por anúncio ou por conjunto de anúncios, ou escolher No Partner em algumas linhas.
• A partir de publicações existentes do Instagram. Importe uma publicação autorizada do Instagram por URL, shortcode, ID de mídia ou código de anúncio com mediaItems[].kind: "partnershipPost".

Cada parceiro precisa de acesso aprovado para anúncios de parceria, e a aprovação é verificada de novo na prévia e na criação. Para os formatos completos da especificação, as chaves de escopo e os limites, veja Anúncios de parceria com a sua própria mídia e Especificação de parceria com publicação existente do Instagram na Referência completa da CLI.