Configuración por CLI

El CLI de Ads Uploader (interfaz de línea de comandos) te permite subir medios y crear anuncios de Meta desde una terminal. El acceso al CLI es para planes de pago y no está disponible durante la prueba.

El CLI sigue la misma estructura que la app web. Si ya has subido anuncios con la app web, el CLI te resultará familiar enseguida: eliges un anuncio de origen o un preajuste, añades tus medios, previsualizas y luego creas.

Los preajustes que creas en la app web aparecen en el CLI, y puedes guardar preajustes de API nuevos desde el CLI con ads presets:save. El CLI también usa las mismas referencias de builds guardados que el uploader web y el MCP, así que puedes seguir con un build en curso sin empezar de nuevo.

¿Por qué usar el CLI? Te da el mismo proceso de lanzamiento de Ads Uploader a través de una interfaz pensada para agentes de IA. Cargar varios lotes es más rápido, y puedes dejar que un agente escriba los textos de los anuncios y arme los builds por ti. Elige el CLI cuando quieras llevar toda tu operación a través de un agente. Para ayudas pequeñas y concretas dentro de un flujo centrado en la web, consulta ¿CLI o MCP? en la página del MCP.

La mayoría de la gente usa el CLI a través de un agente de IA como Claude Code o Cursor. Consulta Uso con IA más abajo.

Instalar e iniciar sesión

El CLI necesita Node.js 18 o posterior. Instálalo desde npm:

npm install -g @adsuploader/cli

Luego inicia sesión:

ads login

ads login abre tu navegador para que apruebes el inicio de sesión con tu cuenta de Ads Uploader. Ejecútalo en una computadora donde puedas abrir un navegador e iniciar sesión en adsuploader.com. Después, el CLI usa tu conexión con Meta existente.

Cuánto dura un inicio de sesión. Un token de inicio de sesión dura 30 días. Después, vuelve a ejecutar ads login. Puedes ver y revocar tus sesiones del CLI en Account > Profile, en la tarjeta CLI Sessions.

Actualizar. El CLI te avisa cuando sale una versión nueva. Actualízalo con:

npm update -g @adsuploader/cli

Ejecuta ads --version para ver qué versión tienes.

Define tu cuenta publicitaria

Ejecuta ads accounts para listar las cuentas publicitarias conectadas a tu cuenta de Meta y luego define una por defecto:

ads account act_123456789

Es lo mismo que el selector de cuenta de la app web. Si te acaban de dar acceso a una cuenta publicitaria nueva en Meta, ejecuta ads accounts:refresh para volver a obtener la lista al momento.

Explora tu cuenta

Antes de crear anuncios, puedes recorrer tu cuenta desde la terminal, igual que en la app web:

Así encuentras el anuncio del que copiar la configuración, o el preajuste o build que vas a usar.

Subir medios

Sube imágenes y videos a tu cuenta publicitaria con 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 subida devuelve un batch ID (ID de lote). Lo usas al crear anuncios. Ejecuta ads uploads para ver tus lotes recientes.

ads upload detecta los enlaces HTTPS por sí solo. Puedes mezclar archivos locales y enlaces en un mismo comando: primero van los archivos locales y luego Ads Uploader descarga cada enlace en su servidor dentro del mismo lote. Así, la agrupación por relación de aspecto y el emparejamiento de miniaturas siguen funcionando con todo. Los enlaces públicos a archivos de Google Drive funcionan como cualquier otro enlace. Para una carpeta entera de Drive, usa ads upload:drive; la carpeta debe estar compartida como Anyone with the link (Viewer).

Nombra tus archivos con sufijos de relación y el CLI agrupa las versiones por ti, igual que la app web. Consulta Variantes de relación de aspecto.

Si algunos archivos fallan (por ejemplo, por una caída de la red), ejecuta ads upload --retry-failed para reintentar los archivos fallidos de tu último lote con errores. Añade un batch ID para reintentar un lote concreto.

Crear anuncios

Crear anuncios tiene dos pasos: previsualizar y crear.

El archivo de especificación

Un archivo de especificación JSON le dice al CLI qué crear. La especificación más sencilla apunta a un preajuste guardado y a tu lote de subida:

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

En lugar de un preajuste, puedes copiar la configuración de un anuncio existente:

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

Para encontrar el ID del anuncio, explora con ads campaigns, ads campaign <id>, ads adset <id> y ads ad <id>. Los anuncios creados a partir de una publicación existente de una página no se pueden usar como plantilla, porque no tienen configuración de creatividad que copiar.

También puedes saltarte el archivo de especificación y lanzar un build guardado con --build <buildId>.

Previsualiza primero

Previsualiza siempre antes de crear. ads create:preview spec.json muestra exactamente lo que se crearía, sin crear nada en Meta. Detecta errores de configuración antes de que algo se active.

Crear

Cuando la vista previa se vea bien, ejecuta ads create spec.json. Los anuncios se activan por defecto, igual que en la app web. Para crearlos en pausa, añade --status PAUSED o pon "options": { "status": "PAUSED" } en la especificación.

Duplicar anuncios existentes por Post ID

El CLI también puede ejecutar el Duplicator, que copia un anuncio existente en otra campaña o conjunto de anuncios conservando la interacción de su publicación:

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

Previsualiza primero la correspondencia entre origen y destino ejecutando los mismos argumentos con ads duplicator:post-id:preview. Consulta Flags de duplicación por Post ID para ver todos los flags y el formato de la especificación.

Referencia completa

Para ver todos los comandos y flags, el formato completo de la especificación, las mejoras de la creatividad, los anuncios de carrusel, flexibles y Multi Media, los marcadores de nombres y los límites de la especificación, consulta la Referencia completa del CLI.

Seguir los trabajos

La creación de anuncios se ejecuta en segundo plano. El CLI muestra el progreso mientras se ejecuta, y puedes revisar un trabajo más tarde:

ads create y --follow siguen un trabajo durante un máximo de 30 minutos seguidos. En lotes muy grandes, el CLI puede dejar de seguirlo con un mensaje "Still running" antes de que termine el trabajo. No es un fallo: el trabajo sigue ejecutándose en el servidor. Retómalo con ads jobs JOB_ID --follow. En ese caso el código de salida es 2 (0 significa éxito y 1 significa error).

Puedes ejecutar un solo trabajo de creación de anuncios a la vez por usuario. Si inicias otro mientras hay uno en curso, el CLI te dice que esperes a que termine o que lo canceles.

Límites de solicitudes

El CLI tiene límites de solicitudes por usuario y por tipo de solicitud. El uso normal nunca llega a los límites, pero un script descontrolado recibe una respuesta 429 Rate Limit Exceeded con una cabecera Retry-After. No metas comandos del CLI en bucles de sondeo (como watch o bucles while de la shell). Usa ads jobs JOB_ID --follow para ver el progreso en directo.

Configuración y variables de entorno

Ejecuta ads config para revisar tu configuración. Muestra si has iniciado sesión, tu correo, tu cuenta publicitaria por defecto, la URL de la API y la carpeta de configuración (~/.config/adsuploader/). Tu inicio de sesión se guarda en credentials.json dentro de esa carpeta, y solo tú puedes leerlo. ads whoami muestra tu correo, tu cuenta por defecto y la URL de la API.

Consejos

• Previsualiza siempre primero. create:preview detecta errores de configuración antes de que se cree ningún anuncio en Meta.
• Los anuncios se activan por defecto. Usa --status PAUSED si quieres revisarlos primero en Ads Manager.
• Las subidas pertenecen a una cuenta publicitaria. Un batch ID solo funciona con la cuenta publicitaria a la que subiste.
• Los preajustes vienen de la app web. Crea preajustes en la app web, o guarda preajustes de API con ads presets:save, y luego úsalos por ID en el CLI.

Uso con IA

El CLI está pensado para que lo manejen agentes de IA como Claude Code o Cursor. Después de instalarlo e iniciar sesión, dale a tu agente el archivo de skill para que conozca todos los comandos y opciones de la especificación.

El archivo de skill viene dentro del paquete de npm. Con la instalación global de arriba, está en:

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

En Claude Code, instálalo como una skill llamada ads:

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

Claude Code la carga cuando le pides trabajo de anuncios, o puedes escribir /ads. En otras herramientas de IA como Cursor, añade SKILL.md como regla o archivo de contexto.

El CLI es una interfaz para media buyers y sus agentes. No está pensado para integrarse en otras aplicaciones.

Ejemplo de instrucción

Una vez configurado, dale a tu agente instrucciones como:

Tengo creatividades nuevas en mi carpeta downloads/ads. Súbelas y crea anuncios con la misma configuración que mi preajuste de compras Summer Sale. Agrúpalas en conjuntos de anuncios de cinco con la fecha de hoy en el nombre y un presupuesto diario de $25. Escribe un texto distinto para cada imagen según lo que muestra. Pausa a nivel de conjunto de anuncios y previsualiza primero.

Acceso a la API

El CLI y el servidor MCP hablan con la API v1 de Ads Uploader. Usan el token que obtienes con ads login o al iniciar sesión en el servidor MCP. Hoy no hay claves de API independientes, así que usa el CLI o el MCP cuando quieras acceso programático a Ads Uploader.

Anuncios de partnership

El CLI puede lanzar anuncios de partnership de dos formas:

• Con tus propios medios. Usa una especificación normal de imagen, video, carrusel, flexible, Multi Media o variantes de relación y añade profile.partnership.enabled: true con los IDs de tu socio. Puedes definir un socio distinto por anuncio o por conjunto de anuncios, o elegir No Partner en algunas filas.
• Desde publicaciones existentes de Instagram. Importa una publicación de Instagram autorizada por URL, shortcode, ID de medio o código de anuncio con mediaItems[].kind: "partnershipPost".

Cada socio necesita acceso aprobado a la publicidad de partnership, y la aprobación se vuelve a comprobar al previsualizar y al crear. Para ver las formas completas de la especificación, las claves de ámbito y los límites, consulta Anuncios de partnership con tus propios medios y Especificación de partnership con publicación existente de Instagram en la Referencia completa del CLI.