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 > MCP, CLI & API, en la tarjeta MCP and CLI-Connected AI Apps.

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.

Claves API para tus propios agentes y scripts

Para conexiones de larga duración de tus propios agentes y scripts, usa una clave API mediante ADS_API_KEY o ads login --api-key. Consulta Claves API para saber cómo crearla, configurarla, usarla para una sola persona y revocarla.

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>. Un anuncio creado a partir de una publicación existente de una página también sirve como plantilla, y los anuncios nuevos usan el enlace de la publicación. Si ni el anuncio ni su publicación tienen enlace a un sitio web, indica cta.link en la especificación.

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

Las duplicaciones de agentes mediante MCP, CLI o la API pública siguen el ajuste Agent Launch de la cuenta en la página Account Permissions, igual que los lanzamientos. Agent Edit no se aplica a ellas. Allowed (el valor predeterminado) inicia la copia directamente. Approval devuelve pending_approval y reviewUrl; no se duplica nada hasta que el usuario aprueba en la página Agent Inbox. Comparte el enlace; no repitas la solicitud ni consultes un trabajo, porque no existe hasta la aprobación. Off rechaza la solicitud con AGENT_LAUNCH_DISABLED. Las copias ACTIVE normales pueden requerir confirmación explícita con confirmSpend: true (--confirm-spend en la CLI); las copias por Post ID nunca la requieren. Las cargas de medios nuevos y el Duplicator web utilizado por una persona no cambian.

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 se comunican con la API v1 de Ads Uploader. Usan el token que obtienes con ads login o al iniciar sesión en el servidor MCP. Para tus propios agentes, scripts y solicitudes directas a la API, crea una clave API en Account > MCP, CLI & API y envíala como Authorization: Bearer adk_.... El CLI puede usar la misma clave mediante ADS_API_KEY. También funciona con el servidor MCP. Consulta Claves API.

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".

La aprobación se vuelve a comprobar al previsualizar y al crear. Un socio con la aprobación pendiente o aún no concedida no bloquea el lanzamiento: recibes un aviso PARTNERSHIP_APPROVAL_PENDING, y Meta puede retener la entrega hasta que el socio apruebe. 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.

Product Showcase

Product Showcase muestra productos de un catálogo debajo de un anuncio de una sola imagen o vídeo. Los anuncios de catálogo completo (dinámicos/DPA) aún no son compatibles.

Los IDs deben ser cadenas de dígitos. Las recomendaciones requieren campañas de Ventas (OUTCOME_SALES); la selección manual de catálogo y conjunto también funciona con otros objetivos. No se admite Product Showcase en anuncios de carrusel, flexibles, multimedia, publicaciones existentes ni Partnership.

Consulta catálogos y conjuntos y solicita una recomendación:

ads catalogs list --account act_123
ads catalogs product-sets 3390205374500501 --product-set 29588799347389253 --json
ads catalogs recommend --url https://www.asphaltgold.com/collections/nike-sneaker --page 1234 --pixel 5678
ads create:preview spec.json --product-showcase recommended
ads create spec.json --product-showcase on --catalog 3390205374500501 --product-set 29588799347389253
ads create:preview spec.json --product-showcase off

Create y Preview aceptan productShowcase: { enabled?, catalogId?, productSetId?, useRecommendation? }; enabled vale true por defecto. Si se omite, se hereda el anuncio de origen. RECOMMENDED usa el valor de Meta (choiceSource: "DEFAULT"); MUST_PICK exige un ID candidato como productSetId ("MANUAL"). MANUAL requiere catálogo y conjunto. Los IDs alternativos validados usan "MANUAL".

Flags de Create y Preview: --product-showcase <on|off|recommended>, --catalog <id>, --product-set <id>. Solo IDs equivale a on; recommended establece useRecommendation: true. Off establece { enabled: false }, no admite IDs y conserva el conjunto del anuncio de origen.

Preview devuelve productShowcase con enabled, IDs, nombre opcional, choiceSource y source (recommendation, manual, source_ad), o null. Las recomendaciones son de solo lectura. Test Mode exige IDs cuando está activado, no consulta catálogos e indica que no se verificaron. Las selecciones guardadas de la interfaz se convierten; los valores predeterminados se revisan al lanzar.