Referência completa da CLI

Esta é a referência completa da Ads Uploader CLI. Para uma introdução e guia de primeiros passos, veja Configuração da CLI.

Comandos

Autenticação

Navegação

Upload de mídia

Arquivos são enviados para staging em paralelo, e falhas transitórias de rede são tentadas novamente automaticamente com backoff. Você raramente precisa mexer nisso, mas as opções estão disponíveis:

Criação de anúncios

Gestão de jobs

Flags de criação

Estas flags se aplicam a ads create, ads create:preview e ads create:interactive. Elas podem ser usadas no lugar de um arquivo de especificação ou junto com ele.

Flags de navegação

Estas flags estão disponíveis em campaigns, adsets, adset e campaign:

Flags de detalhe

Estas flags estão disponíveis em ad:

Flags comuns

Formato do arquivo de especificação

O arquivo JSON de especificação controla todos os aspectos da criação de anúncios. Apenas dois campos são obrigatórios: uma fonte de template (adPresetId ou copyFromAd) e uploadId.

Especificação mínima

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

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

Fonte do template

Você precisa de um destes campos para informar à CLI qual configuração de anúncio usar como base.

Ao usar copyFromAd, forneça o lote de upload e, opcionalmente, a campanha e o conjunto de anúncios:

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

Para encontrar o ad ID certo, navegue pela sua conta: ads campaigns, depois ads campaign <id>, depois ads adset <id>, depois ads ad <id>.

Opções de perfil

Por padrão, novos anúncios herdam a Página Facebook, conta Instagram e perfil Threads do anúncio template ou preset. Este é o mesmo controle Profile Options disponível pelo painel Defaults no app web. Sobrescreva qualquer um deles com um bloco profile (ou as flags --page / --instagram / --threads, que têm precedência sobre o arquivo de especificação):

{
  "copyFromAd": "120233848667930472",
  "uploadId": "batch_abc123",
  "profile": {
    "pageId": "123456789012345",
    "instagramId": "17841400000000000",
    "threadsId": "987654321098765"
  }
}

Rode ads pages para listar os Page IDs que você pode usar, junto com a conta Instagram vinculada a cada Página.

Importante: se você sobrescrever apenas a página, os perfis Instagram e Threads são redefinidos (eles pertenciam à página antiga), não são carregados junto. Para trocar a página e manter um perfil específico de Instagram ou Threads, defina-os explicitamente. Você também pode alterar apenas o perfil Instagram ou Threads sem tocar na página, definindo somente esses campos.

Perfis por campanha para lançamentos multicampanha ainda não são suportados em especificações da CLI.

Estrutura da campanha

Por padrão, os anúncios vão para a campanha do anúncio template. Você pode criar uma nova campanha fornecendo campaign.name.

Para modos multicampanha, use campaign.mode com um array campaigns:

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

Modos de conjunto de anúncios

Por padrão, os anúncios vão para o conjunto de anúncios existente do anúncio template. Os modos abaixo dão controle sobre como os anúncios são distribuídos entre conjuntos.

Criar um novo conjunto de anúncios:

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

Usar um conjunto de anúncios existente por ID:

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

Um conjunto de anúncios por arquivo enviado:

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

Autoagrupar em conjuntos de tamanho fixo:

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

Grupos personalizados com controle total sobre quais arquivos vão para onde:

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

Padrão de nome de conjunto de anúncios para modos com múltiplos conjuntos:

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

Agrupamento de variantes agrupa anúncios pelo identificador de variação no mesmo conjunto:

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

Sobrescrita de orçamento e lance

Sobrescreva o orçamento diário e/ou valor de lance em novos conjuntos de anúncios. Os valores ficam nas unidades da moeda da sua conta (por exemplo, 50 para $50 ou 50 euros).

dailyBudget e bidAmount são campos independentes da Meta:

• Campanhas ABO (orçamento fica no conjunto de anúncios): você pode definir dailyBudget, bidAmount ou ambos. Estratégias de bid cap como COST_CAP, LOWEST_COST_WITH_BID_CAP e TARGET_COST exigem um bidAmount junto com o orçamento.
• Campanhas CBO (orçamento fica na campanha): não defina dailyBudget no conjunto de anúncios, a Meta rejeita isso porque o orçamento já vem da campanha. Para estratégias de bid cap, defina apenas bidAmount.

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

Também disponível como flags da CLI: --daily-budget 50, --bid-amount 5, ou ambos.

Configuração de texto

Texto comum aplica o mesmo copy a todos os anúncios:

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

Texto por anúncio permite definir copy único para cada arquivo:

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

As chaves por anúncio são nomes de arquivo (não caminhos completos). Cada entrada suporta: headlines, bodies, descriptions, cta, link, displayUrl, urlTags. Campos que você não especificar são herdados do anúncio template.

Presets de texto permitem carregar uma configuração de texto salva:

{ "textPresetId": "preset_id_here" }

Você não pode combinar textPresetId com texts.

Opções de estratégia controlam como múltiplas variações de texto são tratadas:

• "flexible" (padrão) permite que a Meta otimize entre suas variações de texto. Múltiplos títulos e corpos viram opções que o Facebook combina.
• "separate" cria um anúncio separado para cada combinação de texto.

CTA e links

Um CTA de nível superior se aplica a todos os anúncios. CTAs por anúncio em texts.perAd o sobrescrevem.

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

Tipos padrão de CTA: 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

CTAs específicos de objetivo são herdados do anúncio template e não devem ser definidos manualmente. Definir esses CTAs no tipo errado de campanha causará erro da API do Facebook.

Teste de URL (Split Destination)

Forneça 2-5 URLs de destino em texts.urlVariants e cada conjunto de anúncios gerado é duplicado uma vez por URL para que a Meta otimize cada combinação de anúncio e landing page de forma independente.

{
  "texts": {
    "common": { "headlines": ["Hero"], "bodies": ["Copy"] },
    "urlVariants": [
      { "link": "https://example.com/homepage", "label": "homepage" },
      { "link": "https://example.com/quiz", "label": "quiz-v2" }
    ]
  }
}

• label é opcional. Quando omitido, o último slug do caminho da URL é usado (/quiz-v2 → quiz-v2), com fallback para o hostname em URLs raiz.
• No modo de conjunto único, o rótulo de cada variante vira o nome completo do conjunto de anúncios.
• Nos modos perUpload e autoGroup, o nome de cada conjunto duplicado acrescenta _{label} ao padrão (ou substitui um token {destination} se você incluir um).
• O token {date} em um rótulo resolve para a data de hoje (por exemplo, launch-{date} → launch-2026-04-27).
• Cada URL de destino precisa ser única. URLs idênticas (ou variantes da mesma URL com barra final / caixa diferente) se juntam em uma entrada, então garanta pelo menos 2 destinos distintos.
• O orçamento do seu conjunto de anúncios é multiplicado pelo número de variantes, pois cada duplicata é seu próprio conjunto.
• Não é compatível com anúncios de origem com destino especial (lead form, Messenger, WhatsApp, Instagram DM, Call). A CLI rejeita essa combinação com um erro claro, pois esses formatos não roteiam por cta.link.
• Sobrescritas de link por anúncio em texts.perAd perdem para a URL da variante quando ambos estão definidos.

Aprimoramentos criativos

Controle aprimoramentos criativos Advantage+:

{ "creativeEnhancements": "none" }

Recursos disponíveis: 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

Ao escolher recursos manualmente, liste apenas os relevantes ao tipo de mídia. Recursos de vídeo (video_auto_crop, video_filtering) só se aplicam a anúncios em vídeo. Recursos de carrossel (carousel_to_video, carousel_dynamic_description, multi_share_end_card, multi_share_optimized) só se aplicam a anúncios em carrossel.

Carousel Ads

Agrupe arquivos enviados em anúncios em carrossel com texto por card e texto geral opcional do carrossel. cardTexts controla cards individuais. O texto geral do carrossel pode ficar no objeto do carrossel ou em texts.perAd usando o name do carrossel; campos no objeto do carrossel vencem quando ambos existem.

{
  "carousel": [
    {
      "name": "My Carousel",
      "cards": ["slide1.jpg", "slide2.jpg", "slide3.jpg"],
      "headlines": ["Overall Carousel Headline"],
      "bodies": ["Overall primary text"],
      "descriptions": ["Overall description"],
      "cta": "SHOP_NOW",
      "link": "https://example.com/carousel",
      "urlTags": "utm_content=my_carousel",
      "cardTexts": [
        { "headline": "Slide 1", "description": "First card", "link": "https://example.com/1" },
        { "headline": "Slide 2", "description": "Second card", "link": "https://example.com/2" }
      ]
    }
  ]
}

Formato alternativo para texto geral:

{
  "texts": {
    "perAd": {
      "My Carousel": {
        "headlines": ["Overall Carousel Headline"],
        "bodies": ["Overall primary text"],
        "descriptions": ["Overall description"],
        "cta": "SHOP_NOW",
        "link": "https://example.com/carousel",
        "urlTags": "utm_content=my_carousel"
      }
    }
  },
  "carousel": [
    {
      "name": "My Carousel",
      "cards": ["slide1.jpg", "slide2.jpg", "slide3.jpg"]
    }
  ]
}

Cards precisam referenciar nomes de arquivo do lote de upload. Mínimo de 2 cards por carrossel. Arquivos usados por um carrossel são removidos da lista de anúncios padrão.

Flexible Ads

Agrupe múltiplos ativos em um único anúncio flexível em que a Meta escolhe o melhor ativo por posicionamento:

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

Mínimo de 2 ativos por grupo. Arquivos usados por um grupo flexível são removidos da lista de anúncios padrão.

Multi Media Ads

Agrupe 2-10 imagens ou vídeos enviados em um anúncio Meta Multi Media:

{
  "multimedia": [
    {
      "name": "Mixed Media Ad",
      "assets": ["hero.jpg", "promo.mp4", "banner.jpg"],
      "assetTexts": [
        {
          "headline": "Hero headline",
          "primaryText": "Hero primary text",
          "description": "Hero description",
          "link": "https://example.com/hero",
          "displayUrl": "example.com/hero"
        }
      ]
    }
  ]
}

Ativos precisam referenciar nomes de arquivo do lote de upload. assetTexts é opcional e se alinha com assets por índice; cada campo é uma única sobrescrita para aquele ativo, e campos vazios usam o texto principal e URLs do anúncio como fallback. O ativo principal renderizado usa o texto e a URL principais do anúncio, e qualquer sobrescrita de texto do ativo principal vira a primeira opção de texto principal. Vídeos precisam de uma URL pública de thumbnail em cache do processamento de upload. Arquivos usados por um grupo Multi Media são removidos da lista de anúncios padrão.

Nome de anúncios

Personalize como seus anúncios são nomeados:

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

Opções

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

Upload e detecção de variantes

Grupos de variantes são detectados automaticamente a partir de convenções de nomes de arquivo, exatamente como no aplicativo web. Veja Variações de proporção para detalhes completos sobre convenções de nomenclatura.

Sufixos de proporção: hero_1x1.jpg + hero_4x5.jpg + hero_9x16.jpg + hero_16x9.jpg + hero_1.91x1.jpg são agrupados como um anúncio variante. Até 5 proporções por grupo.

Posição do token: o token de proporção pode aparecer no fim (hero_4x5.jpg), no meio (hero_4x5_v2.jpg) ou no início (4x5_hero.jpg).

Sufixos legados por palavra: hero.jpg + hero_vertical.jpg + hero_horizontal.jpg ainda funcionam e mapeiam para 9x16 e 16x9.

O delimitador padrão é _. Você pode alterá-lo (ou aceitar múltiplos) em Account > Defaults > Placements > Filename Separator.

Padrões comuns

Subir e criar com um preset

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

Onde spec.json contém:

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

Copiar configurações de um anúncio existente

Navegue pela conta para encontrar o anúncio:

ads campaigns
ads campaign 120233848666410472
ads adset 120233848666620472
ads ad 120233848667930472

Depois crie uma especificação referenciando-o:

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

O anúncio de origem precisa ter configurações criativas inline. Se ele foi criado a partir de um Page post existente, a CLI o rejeitará antes de enviar uma solicitação de criação.

Salvar um preset API de um anúncio existente

ads presets:save --from-ad 120233848667930472 --name "Spring Purchase Template"
ads create --preset PRESET_ID --upload BATCH_ID

Isso salva o mesmo formato de preset API usado pelo app web. O anúncio de origem precisa ter configurações criativas inline; anúncios baseados em Page post não podem ser salvos como presets API.

Texto por anúncio com copy único por arquivo

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

Autoagrupar em múltiplos conjuntos de anúncios

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

Observações importantes

1. Sempre faça prévia primeiro. create:preview captura erros de configuração antes de tocar no Facebook.
2. Anúncios ficam ativos por padrão. Use --status PAUSED ou "status": "PAUSED" na especificação para criá-los pausados.
3. uploadId vem da saída do upload. É o batch ID retornado por ads upload.
4. Uploads ficam vinculados a uma conta de anúncio. Arquivos são enviados diretamente para a biblioteca de mídia do Facebook da conta selecionada. O batch ID só pode ser usado com a mesma conta.
5. copyFromAd precisa de uploadId. Você precisa fornecer o lote de upload. Opcionalmente, forneça campaign.id e adSet.id para controlar o posicionamento.
6. Chaves de texto por anúncio são nomes de arquivo. Use "hero.jpg", não "/path/to/hero.jpg".
7. textPresetId e texts são mutuamente exclusivos. Use um ou outro, não ambos.
8. CTAs específicos de objetivo são herdados do template. Não defina MESSAGE_PAGE, WHATSAPP_MESSAGE etc. manualmente.