Referencia completa del CLI

Esta es la referencia completa del CLI de Ads Uploader. Para una introducción y una guía para empezar, consulta Configuración por CLI.

Comandos

Autenticación

Navegación

Subida de medios

Los archivos se preparan en paralelo, y los fallos de red transitorios se reintentan automáticamente con backoff. Rara vez necesitas tocar esto, pero está disponible:

Creación de anuncios

Gestión de trabajos

Flags de creación

Estos flags se aplican a ads create, ads create:preview y ads create:interactive. Se pueden usar en lugar de un archivo de especificación o junto con él.

Flags de navegación

Estos flags están disponibles en campaigns, adsets, adset y campaign:

Flags de detalle

Estos flags están disponibles en ad:

Flags comunes

Formato del archivo de especificación

El archivo de especificación JSON controla cada aspecto de la creación de anuncios. Solo dos campos son obligatorios: una fuente de plantilla (adPresetId o copyFromAd) y uploadId.

Especificación mínima

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

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

Fuente de plantilla

Necesitas una de estas para indicarle al CLI qué configuración de anuncio usar como base.

Cuando uses copyFromAd, proporciona la subida y, opcionalmente, la campaña y el conjunto de anuncios:

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

Para encontrar el ID de anuncio correcto, navega por tu cuenta: ads campaigns luego ads campaign <id> luego ads adset <id> luego ads ad <id>.

Opciones de perfil

De forma predeterminada, los nuevos anuncios heredan la página de Facebook, la cuenta de Instagram y el perfil de Threads del anuncio de plantilla o del preajuste. Es el mismo control de Opciones de perfil disponible mediante el panel de Valores predeterminados en la aplicación web. Sustituye cualquiera de ellos con un bloque profile (o con los flags --page / --instagram / --threads, que tienen prioridad sobre el archivo de especificación):

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

Ejecuta ads pages para listar los IDs de página que puedes usar, junto con la cuenta de Instagram vinculada de cada página.

Importante: si sustituyes solo la página, los perfiles de Instagram y Threads se restablecen (pertenecían a la página antigua), no se trasladan. Para cambiar la página y conservar un perfil específico de Instagram o Threads, establécelos explícitamente. También puedes cambiar solo el perfil de Instagram o Threads sin tocar la página, estableciendo solo esos campos.

Los perfiles por campaña para lanzamientos multicampaña aún no se admiten en las especificaciones del CLI.

Estructura de la campaña

De forma predeterminada, los anuncios van a la campaña del anuncio de plantilla. Puedes crear una nueva campaña proporcionando campaign.name.

Para los modos multicampaña, usa campaign.mode con un array campaigns:

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

Modos de conjunto de anuncios

De forma predeterminada, los anuncios van al conjunto de anuncios existente del anuncio de plantilla. Los siguientes modos te dan control sobre cómo se distribuyen los anuncios entre los conjuntos de anuncios.

Crear un nuevo conjunto de anuncios:

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

Usar un conjunto de anuncios existente por ID:

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

Un conjunto de anuncios por cada archivo subido:

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

Agrupación automática en conjuntos de anuncios de tamaño fijo:

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

Grupos personalizados con control total sobre qué archivos van a dónde:

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

Patrón de nombres de conjunto de anuncios para los modos de varios conjuntos de anuncios:

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

La agrupación por variantes agrupa los anuncios por identificador de variación en el mismo conjunto de anuncios:

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

Sustitución de presupuesto y puja

Sustituye el presupuesto diario o el importe de la puja en los nuevos conjuntos de anuncios. Los valores están en las unidades de moneda de tu cuenta (p. ej. 50 para 50 $ o 50 euros).

dailyBudget y bidAmount son campos de Meta independientes:

• Campañas ABO (el presupuesto está en el conjunto de anuncios): puedes establecer dailyBudget, bidAmount o ambos. Las estrategias con límite de puja como COST_CAP, LOWEST_COST_WITH_BID_CAP y TARGET_COST requieren un bidAmount junto al presupuesto.
• Campañas CBO (el presupuesto está en la campaña): no establezcas dailyBudget en el conjunto de anuncios, Meta lo rechaza porque el presupuesto ya proviene de la campaña. Para las estrategias con límite de puja, establece solo bidAmount.

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

También disponible como flags del CLI: --daily-budget 50, --bid-amount 5 o ambos.

Configuración de texto

El texto común aplica la misma copia a todos los anuncios:

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

El texto por anuncio te permite establecer una copia única para cada archivo:

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

Las claves por anuncio son nombres de archivo (no rutas completas). Cada entrada admite: headlines, bodies, descriptions, cta, link, displayUrl, urlTags. Los campos que no especifiques se heredan del anuncio de plantilla.

Los preajustes de texto te permiten cargar una configuración de texto guardada:

{ "textPresetId": "preset_id_here" }

No puedes combinar textPresetId con texts.

Las opciones de estrategia controlan cómo se gestionan varias variaciones de texto:

• "flexible" (predeterminado) deja que Meta optimice entre tus variaciones de texto. Varios títulos y textos se convierten en opciones que Facebook combina libremente.
• "separate" crea un anuncio separado para cada combinación de texto.

CTA y enlaces

Una CTA de nivel superior se aplica a todos los anuncios. Las CTA por anuncio en texts.perAd la sustituyen.

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

Tipos de CTA estándar: 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

Las CTA específicas del objetivo se heredan del anuncio de plantilla y no deben establecerse manualmente. Establecerlas en el tipo de campaña incorrecto causará un error de la API de Facebook.

Prueba dividida de URL (destino dividido)

Proporciona de 2 a 5 URLs de destino bajo texts.urlVariants y cada conjunto de anuncios generado se duplica una vez por URL para que Meta optimice cada combinación de anuncio y página de destino de forma independiente.

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

• label es opcional. Cuando se omite, se usa el último slug de la ruta de la URL (/quiz-v2 → quiz-v2), con retroceso al nombre de host para las URLs raíz.
• En el modo de conjunto de anuncios único, la etiqueta de cada variante se convierte en el nombre completo del conjunto de anuncios.
• En los modos perUpload y autoGroup, el nombre de cada conjunto de anuncios duplicado añade _{label} al patrón (o sustituye un token {destination} si incluyes uno).
• El token {date} en una etiqueta se resuelve a la fecha de hoy (p. ej. launch-{date} → launch-2026-04-27).
• Cada URL de destino debe ser única. Las URLs idénticas (o variantes con barra final o con distinta mayúscula/minúscula de la misma URL) se fusionan en una sola entrada, así que asegúrate de tener al menos 2 destinos distintos.
• El presupuesto de tu conjunto de anuncios se multiplica por el número de variantes, ya que cada duplicado es su propio conjunto de anuncios.
• No compatible con anuncios de origen con destino especial (formulario de clientes potenciales, Messenger, WhatsApp, DM de Instagram, llamada). El CLI rechaza esta combinación con un error claro, esos formatos no se enrutan a través de cta.link.
• Las sustituciones de link por anuncio en texts.perAd pierden frente a la URL de la variante cuando ambas están establecidas.

Mejoras creativas

Controla las mejoras creativas de Advantage+:

{ "creativeEnhancements": "none" }

Funciones disponibles: 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

Cuando selecciones funciones concretas, lista solo las que sean relevantes para el tipo de medio. Las funciones de vídeo (video_auto_crop, video_filtering) solo se aplican a los anuncios de vídeo. Las funciones de carrusel (carousel_to_video, carousel_dynamic_description, multi_share_end_card, multi_share_optimized) solo se aplican a los anuncios de carrusel.

Anuncios de carrusel

Agrupa los archivos subidos en anuncios de carrusel con texto por tarjeta y texto general opcional del carrusel. cardTexts controla las tarjetas individuales. El texto general del carrusel puede colocarse en el objeto del carrusel o establecerse en texts.perAd usando el name del carrusel; los campos colocados ganan cuando ambos están presentes.

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

Forma alternativa para el texto general:

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

Las tarjetas deben referenciar nombres de archivo de la subida. Mínimo 2 tarjetas por carrusel. Los archivos reclamados por un carrusel se eliminan de la lista de anuncios estándar.

Anuncios flexibles

Agrupa varios recursos en un único anuncio flexible donde Meta elige el mejor recurso por ubicación:

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

Mínimo 2 recursos por grupo. Los archivos reclamados por un grupo flexible se eliminan de la lista de anuncios estándar.

Anuncios multimedia

Agrupa de 2 a 10 imágenes o vídeos subidos en un anuncio Multi Media de Meta:

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

Los recursos deben referenciar nombres de archivo de la subida. assetTexts es opcional y se alinea con assets por índice; cada campo es una única sustitución para ese recurso y los campos en blanco recurren al texto principal y a las URLs del anuncio. El recurso principal renderizado usa el texto y la URL principales del anuncio, y cualquier sustitución del texto principal de un recurso se convierte en la primera opción de texto principal. Los vídeos necesitan una URL de miniatura pública en caché procedente del procesamiento de la subida. Los archivos reclamados por un grupo Multi Media se eliminan de la lista de anuncios estándar.

Nombres de anuncios

Personaliza cómo se nombran tus anuncios:

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

Opciones

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

Subida y detección de variantes

Los grupos de variantes se detectan automáticamente a partir de las convenciones de nombres de archivo, igual que en la aplicación web. Consulta Variaciones de relación de aspecto para todos los detalles sobre las convenciones de nombres.

Sufijos de relación: hero_1x1.jpg + hero_4x5.jpg + hero_9x16.jpg + hero_16x9.jpg + hero_1.91x1.jpg se agrupan como un único anuncio con variantes. Hasta 5 relaciones por grupo.

Posición del token: el token de relación puede aparecer al final (hero_4x5.jpg), en el medio (hero_4x5_v2.jpg) o al principio (4x5_hero.jpg).

Sufijos de palabra heredados: hero.jpg + hero_vertical.jpg + hero_horizontal.jpg siguen funcionando y se asignan a 9x16 y 16x9.

El delimitador predeterminado es _. Puedes cambiarlo (o aceptar varios) en Cuenta > Valores predeterminados > Ubicaciones > Separador de nombre de archivo.

Patrones comunes

Subir y crear con un preajuste

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

Donde spec.json contiene:

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

Copiar la configuración de un anuncio existente

Navega por tu cuenta para encontrar el anuncio:

ads campaigns
ads campaign 120233848666410472
ads adset 120233848666620472
ads ad 120233848667930472

Luego crea una especificación que lo referencie:

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

El anuncio de origen debe tener configuración de creativo en línea. Si se construyó a partir de una publicación de página existente, el CLI lo rechazará antes de enviar una solicitud de creación.

Guardar un preajuste de API a partir de un anuncio existente

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

Esto guarda la misma forma de preajuste de API que usa la aplicación web. El anuncio de origen debe tener configuración de creativo en línea; los anuncios respaldados por publicaciones de página no pueden guardarse como preajustes de API.

Texto por anuncio con copia única por archivo

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

Agrupación automática en varios conjuntos de anuncios

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

Notas importantes

1. Siempre previsualiza primero. create:preview detecta errores de configuración antes de tocar Facebook.
2. Los anuncios están activos de forma predeterminada. Usa --status PAUSED o "status": "PAUSED" en la especificación para crearlos pausados.
3. uploadId proviene de la salida de la subida. Es el ID de la subida que devuelve ads upload.
4. Las subidas están vinculadas a una cuenta publicitaria. Los archivos se suben directamente a la biblioteca de medios de Facebook de la cuenta seleccionada. El ID de la subida solo puede usarse con la misma cuenta.
5. copyFromAd necesita uploadId. Debes proporcionar la subida. Opcionalmente, proporciona campaign.id y adSet.id para controlar la ubicación.
6. Las claves de texto por anuncio son nombres de archivo. Usa "hero.jpg", no "/path/to/hero.jpg".
7. textPresetId y texts son mutuamente excluyentes. Usa uno u otro, no ambos.
8. Las CTA específicas del objetivo se heredan de la plantilla. No establezcas MESSAGE_PAGE, WHATSAPP_MESSAGE, etc. manualmente.