Configuração da CLI

O acesso à CLI é reservado para usuários pagos e não está disponível em testes grátis.

A melhor forma de começar com a CLI (interface de linha de comando) é entender como Ads Uploader funciona. A CLI segue exatamente a mesma estrutura do aplicativo web. Se você entende o app web e já subiu anúncios por ele, usar a CLI fará sentido imediatamente.

Qualquer preset criado na interface web é levado para a CLI e fica acessível por ela. Você também pode salvar presets API pela CLI com ads presets:save --from-ad <adId> --name <name>. Alguns usuários podem achar mais fácil configurar seus presets no aplicativo e depois mudar para a CLI para o trabalho diário de campanhas. Tudo continua totalmente personalizável dentro da CLI.

Por que usar a CLI? Ela oferece uma interface diferente, com foco agentic, para trabalhar sobre a mesma infraestrutura testada e comprovada do Ads Uploader. Carregar vários lotes é mais rápido, e você pode usar IA para escrever copy de anúncios e montar builds. É outra forma de usar Ads Uploader.

A maioria dos usuários opera a CLI por meio de um agente de IA como Claude Code ou Cursor. Veja Usar com IA no final desta página para saber como entregar a CLI a um agente depois da configuração.

Instalar e autenticar

Instale a CLI globalmente com npm install -g @adsuploader/cli (requer Node.js 18+) e depois rode ads login para autenticar pelo navegador. Isso usa sua conta Ads Uploader existente e sua conexão Facebook.

Rode o comando de login no mesmo dispositivo em que você já está conectado a adsuploader.com, pois o fluxo de autenticação abre uma janela do navegador para verificar sua identidade.

Configurar sua conta

Depois de fazer login, rode ads accounts para ver todas as contas de anúncio conectadas à sua conta Meta, depois ads account act_123456789 para definir a padrão. É o mesmo seletor de conta que você vê no app web.

Navegar pela sua conta

Antes de criar anúncios, você pode navegar por toda a estrutura da conta pela CLI, assim como clicaria por campanhas, conjuntos de anúncios e anúncios no app web.

É assim que você encontra o anúncio de onde quer copiar configurações ou confirma qual preset usar no arquivo de especificação.

Subir mídia

Suba imagens e vídeos para a biblioteca de mídia da sua conta de anúncio com ads upload:

ads upload hero.jpg banner.mp4 promo.mp4
ads upload ./my-creatives/

Isso retorna um batch ID que você referenciará ao criar anúncios. Rode ads uploads para ver seus lotes recentes.

O agrupamento de variantes funciona automaticamente se você nomear arquivos com sufixos de proporção, exatamente como no aplicativo web. Veja Variações de proporção para saber como nomear seus arquivos corretamente.

Criar anúncios

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

O arquivo de especificação

Um arquivo JSON de especificação informa à CLI o que construir. A especificação mais simples referencia um preset salvo e seu lote de upload:

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

Você também pode copiar configurações de um anúncio existente em vez de usar um preset:

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

Para encontrar o ad ID certo, navegue pela conta com ads campaigns, ads campaign <id>, ads adset <id> e ads ad <id>. Anúncios criados a partir de Page posts existentes não podem ser copiados como templates, e a CLI os rejeitará antes de enviar uma solicitação de criação.

Prévia primeiro

Sempre gere uma prévia antes de criar. Rode ads create:preview spec.json para ver exatamente o que seria criado sem tocar no Facebook. Isso captura erros de configuração antes de qualquer coisa entrar no ar.

Criar

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

Referência completa

Para o formato completo do arquivo de especificação, todos os comandos, flags, aprimoramentos criativos, configuração de carrossel e flexible ads, placeholders de nome de anúncio e padrões comuns, veja a Referência completa da CLI.

Acompanhamento de jobs

A criação de anúncios roda em background. A CLI transmite o progresso automaticamente, mas você também pode verificar um job depois:

ads create e --follow acompanham por até 30 minutos por vez. Em lotes muito grandes, a CLI pode sair com uma mensagem "Still running" antes do job terminar, isso não é falha. Retome com ads jobs JOB_ID --follow. O job no backend continua rodando independentemente de você estar acompanhando. O código de saída é 2 nesse caso (vs 0 sucesso, 1 erro).

Rate limits

A CLI tem rate limit por usuário e por endpoint. O uso típico nunca atinge os limites, mas um script descontrolado acionará uma resposta 429 Rate Limit Exceeded com header Retry-After. Não envolva comandos da CLI em loops de polling (watch, loops shell while); use ads jobs JOB_ID --follow para progresso ao vivo.

Dicas

• Sempre faça prévia primeiro. create:preview captura erros de configuração antes de tocar no Facebook.
• Anúncios entram no ar por padrão. Use --status PAUSED se quiser revisá-los primeiro no Ads Manager.
• Uploads ficam vinculados a uma conta. O batch ID só funciona com a conta em que você fez o upload.
• Presets vêm do app web. Crie seus presets na UI web ou salve presets API com ads presets:save, depois referencie-os por ID na CLI.
• Rode ads config para verificar seu setup. Mostra sua conta atual, URL da API e caminho das credenciais.

Usar com IA

A CLI foi projetada para ser controlada por agentes de IA como Claude Code ou Cursor. Depois de instalar e autenticar, registre o arquivo de skill para que seu agente entenda todos os comandos e opções de especificação desta página.

O arquivo de skill vem dentro do pacote npm em node_modules/@adsuploader/cli/SKILL.md. No Claude Code, configure-o como um comando slash personalizado (por exemplo, /ads):

mkdir -p .claude/commands
cp node_modules/@adsuploader/cli/SKILL.md .claude/commands/ads.md

Depois digite /ads no Claude Code para carregar a skill antes de dar instruções. Para outras ferramentas de IA como Cursor, adicione SKILL.md como regra ou arquivo de contexto.

Segurança. A autenticação da CLI é vinculada ao seu endereço IP, e apenas um job de criação de anúncios pode rodar por vez por conta. A CLI não foi feita para ser conectada a outros aplicativos. Ela é uma interface alternativa para media buyers avançados.

Exemplo de prompt

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

Tenho vários novos criativos de anúncios na minha pasta downloads/ads. Faça upload deles e crie anúncios usando as mesmas configurações do meu preset de campanha Sales purchase. Agrupe-os em conjuntos de anúncios de cinco, nomeados com a data de hoje, com orçamento diário de $25. Escreva copy única para cada imagem com base no conteúdo da imagem. Pause no nível do conjunto de anúncios e faça prévia primeiro.