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

Exploración

Subida de medios

Creación de anuncios

Gestión de trabajos

Flags de create

Estos flags se aplican a ads create, ads create:preview y ads create:interactive. Pueden usarse en lugar o junto con un archivo de especificación.

Flags de exploración

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

Flags comunes

Formato del archivo de especificación

El archivo JSON de especificación controla todos los aspectos de la creación del anuncio. Solo hay dos campos 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 opciones para decirle al CLI qué configuración de anuncio usar como base.

Al usar copyFromAd, proporciona el lote de 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, explora tu cuenta: ads campaigns luego ads campaign <id> luego ads adset <id> luego ads ad <id>.

Estructura de la campaña

Por defecto, los anuncios van a la campaña del anuncio plantilla. Puedes crear una campaña nueva indicando campaign.name.

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

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

Modos de conjunto de anuncios

Por defecto, los anuncios van al conjunto de anuncios existente del anuncio plantilla. Los siguientes modos te dan control sobre cómo se distribuyen los anuncios en los conjuntos.

Crear un nuevo conjunto de anuncios:

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

Usar un conjunto existente por ID:

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

Un conjunto de anuncios por archivo subido:

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

Agrupar automáticamente en conjuntos de un tamaño fijo:

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

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

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

Patrón de nombre del conjunto de anuncios para modos multi-conjunto:

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

Agrupación por variante agrupa anuncios por identificador de variación en el mismo conjunto:

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

Sobrescritura de presupuesto y puja

Sobrescribe el presupuesto diario y/o el bid en los nuevos conjuntos de anuncios. Los valores están en las unidades de moneda de tu cuenta (por ejemplo, 50 por $50 o 50 euros).

dailyBudget y bidAmount son campos independientes de Meta:

• Campañas ABO (el presupuesto vive en el conjunto de anuncios): puedes poner dailyBudget, bidAmount o ambos. Las estrategias con bid cap como COST_CAP, LOWEST_COST_WITH_BID_CAP y TARGET_COST requieren un bidAmount junto con el presupuesto.
• Campañas CBO (el presupuesto vive en la campaña): no pongas dailyBudget en el conjunto de anuncios; Meta lo rechaza porque el presupuesto ya viene de la campaña. Para estrategias con bid cap, pon solo bidAmount.

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

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

Configuración de texto

Texto común aplica el mismo texto a todos los anuncios:

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

Texto por anuncio te permite definir texto único 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 plantilla.

Preajustes de texto permiten cargar una configuración de texto guardada:

{ "textPresetId": "preset_id_here" }

No puedes combinar textPresetId con texts.

Opciones de estrategia controlan cómo se manejan las variaciones múltiples de texto:

• "flexible" (por defecto) deja que Meta optimice entre tus variaciones de texto. Varios titulares y cuerpos se convierten en opciones que Facebook mezcla y combina.
• "separate" crea un anuncio por cada combinación de texto.

CTA y enlaces

Un CTA a nivel superior se aplica a todos los anuncios. Los CTA por anuncio en texts.perAd lo sobrescriben.

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

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

Los CTAs específicos del objetivo se heredan del anuncio plantilla y no deben definirse manualmente. Establecerlos en el tipo de campaña equivocado causará un error de la API de Facebook.

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

Al seleccionar funciones a medida, solo lista las relevantes para el tipo de medio. Las funciones de video (video_auto_crop, video_filtering) solo se aplican a anuncios de video. Las de carrusel (carousel_to_video, carousel_dynamic_description, multi_share_end_card, multi_share_optimized) solo se aplican a Carousel Ads.

Carousel Ads

Agrupa los archivos subidos en Carousel Ads con texto por tarjeta:

{
  "carousel": [
    {
      "name": "My Carousel",
      "cards": ["slide1.jpg", "slide2.jpg", "slide3.jpg"],
      "cardTexts": [
        { "headline": "Slide 1", "description": "First card", "link": "https://example.com/1" },
        { "headline": "Slide 2", "description": "Second card", "link": "https://example.com/2" }
      ]
    }
  ]
}

Las tarjetas deben referenciar nombres de archivo del lote de subida. Mínimo 2 tarjetas por carrusel. Los archivos asignados a un carrusel se retiran de la lista estándar de anuncios.

Flexible Ads

Agrupa varios recursos en un único Flexible Ad 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 asignados a un grupo flexible se retiran de la lista estándar de anuncios.

Nombrado 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 por convenciones de nombre de archivo, igual que en la aplicación web. Consulta Variantes de relación de aspecto para ver los detalles completos de las convenciones de nombrado.

Sufijos de relación: hero_4x5.jpg + hero_9x16.jpg + hero_16x9.jpg se agrupan como un anuncio de variante.

Sufijos con palabras: hero.jpg + hero_vertical.jpg + hero_horizontal.jpg se agrupan como un anuncio de variante.

Funciona con delimitadores _ y -. Un archivo sin sufijo de relación (por ejemplo, hero.jpg) solo se agrupa con variantes _vertical/_horizontal. Para agrupación por relación, todos los archivos deben tener sufijos de relación.

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 configuración de un anuncio existente

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

Texto por anuncio con copy único 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"
      }
    }
  }
}

Agrupar automáticamente 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 por defecto. Usa --status PAUSED o "status": "PAUSED" en la especificación para crearlos en pausa.
3. uploadId proviene de la salida de subida. Es el ID de lote devuelto por 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 lote solo puede usarse con la misma cuenta.
5. copyFromAd necesita uploadId. Debes indicar el lote de subida. Opcionalmente indica 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 los dos.
8. Los CTA específicos del objetivo se heredan de la plantilla. No establezcas MESSAGE_PAGE, WHATSAPP_MESSAGE, etc. manualmente.