El CLI de Tiendanube es la herramienta de línea de comandos oficial para desarrollar diseños en Tiendanube. Con ella, editas los archivos del diseño en tu editor, sincronizas los cambios con la tienda, generas un link de vista previa para aprobación y publicas el diseño cuando esté listo, sin depender de un cliente FTP de terceros.
Helpjuice Warning Callout Title
El CLI tiene dos modos de sincronización. El modo Fork, que usa la API pública, funciona solo en diseños basados en secciones, como Ipanema. Para diseños legados, el modo disponible es FTP.
¿Qué necesito antes de instalar el CLI?
Fíjate estos tres puntos antes de empezar:
- Node.js 24.15 o superior instalado en tu máquina;
- Una carpeta local vacía para recibir los archivos del diseño;
- Las credenciales de FTP de la tienda, en el modo FTP, o acceso al panel de administrador para autorizar el CLI, en el modo Fork.
¿Cómo instalo el CLI de Tiendanube?
Para instalar el CLI sigue estos pasos:
1. Abrir la terminal de tu computadora.
2. Ejecutar el comando de instalación: npm install -g @tiendanube/cli
3. Confirmar que la instalación funcionó con nuvemshop --version
¡Listo!
El CLI está instalado y disponible en tu terminal.
Helpjuice Info Callout Title
Los comandos nuvemshop y tiendanube ejecutan la misma CLI, así que puedes usar el que prefieras. Para probarla sin instalarla globalmente, ejecuta npx --package=@tiendanube/cli nuvemshop --help.
¿Cómo conecto el CLI a mi tienda?
La conexión vale para la carpeta desde la que ejecutas los comandos, así que crea la carpeta del diseño y abre la terminal ahí antes de empezar. Elige el modo según el diseño de la tienda:
Diseños clásicos legacy (FTP)
En este modo, el CLI se conecta con la tienda usando las mismas credenciales de FTP que ya están en el panel. Descarga el diseño actual y sincroniza automáticamente los cambios.
Los pasos a seguir son:
1. Ejecutar nuvemshop theme ftp setup indicando los parámetros --ftp-server, --ftp-username, --ftp-password y --store-url.
2. Descargar los archivos del diseño con nuvemshop theme ftp pull. Este paso es obligatorio antes de enviar o seguir cambios, para que la carpeta local refleje lo que está en la tienda.
Diseños basados en secciones (Fork)
Para diseños desarrollados a partir de Ipanema, trabajas en un Fork (copia aislada) y validas los cambios antes del go-live.
Los pasos a seguir son:
1. Ejecutar nuvemshop theme authorize.
2. Iniciar sesión en la página que se abre en el navegador y copiar el token que aparece en pantalla.
3. Pegar el token en la terminal cuando te lo pida.
4. Listar los diseños de la tienda con nuvemshop theme list y ubicar el id del diseño que vas a editar.
5. Descargar los archivos con nuvemshop theme pull --theme-id <id>. El id queda guardado como predeterminado, así que los comandos siguientes no lo van a necesitar. Para consultar en cualquier momento cuál es el id predeterminado guardado, ejecuta nuvemshop theme current.
Si la tienda todavía no tiene un diseño para editar, crea uno antes con nuvemshop theme create --base-theme "ipanema" --title "<título>" y usa el id que devuelve el comando.
Helpjuice Success Callout Title
La configuración queda guardada en el archivo .nuvem de la carpeta del diseño. Está ofuscado, pero no encriptado, así que incluye .nuvem en el .gitignore y no lo compartas ni lo versiones.
¿Cómo edito y envío los cambios del diseño?
Con los archivos en la carpeta local, editas en tu editor y usas los comandos de abajo para sincronizar. Haz clic en cada tarea para ver los detalles:
Seguir los cambios mientras editas
Ejecutar nuvemshop theme watch, en el modo Fork, o nuvemshop theme ftp watch, en el modo FTP.
El CLI observa la carpeta del diseño y, cada vez que guardas un archivo, envía el cambio a la tienda. Por defecto también abre una ventana de Chromium, te lleva al panel para iniciar sesión y después navega a la tienda, recargando la página con cada sincronización.
Para sincronizar sin abrir el navegador, agrega --no-browser y recarga la tienda por tu cuenta.
Los archivos y carpetas que empiezan con punto, como .nuvem y .git, no se envían ni se observan.
Revisar qué va a cambiar antes de enviar
Ejecutar nuvemshop theme diff para ver qué archivos se crearían, actualizarían o eliminarían, sin enviar nada a la tienda.
Para ver también qué cambió dentro de cada archivo, agrega --detailed.
Los archivos que el envío ignoraría aparecen como ignorados, y no como cambios. Este comando está disponible en el modo Fork.
Enviar los cambios a la tienda
Ejecutar nuvemshop theme push, en el modo Fork, o nuvemshop theme ftp push, en el modo FTP.
El CLI compara los archivos locales con los de la tienda y envía solo lo que cambió. Para enviar todos los archivos sin esa comparación, agrega --force.
Habilitar la edición de todo el diseño
Ejecutar nuvemshop theme fork.
Sin este comando, el envío queda limitado a algunas carpetas y archivos del diseño. Después de activar el modo fork, el envío puede incluir el árbol completo del diseño, algo necesario cuando editas archivos fuera de custom/, templates/ y settings_data.json.
La terminal confirma la operación indicando que el diseño fue forkeado y que fork ahora es verdadero.
¿Cómo previsualizo y publico el diseño?
Antes de dejar el diseño en vivo, puedes revisar el resultado y medir su performance. Haz clic en cada tarea para ver los detalles:
Generar el link de vista previa
Ejecutar nuvemshop theme preview.
El comando devuelve un link de la tienda con el identificador del diseño, que puedes compartir para aprobación sin que el diseño quede visible para quien compra.
Medir la performance del diseño
Ejecutar nuvemshop theme performance.
El CLI corre una auditoría de performance sobre la vista previa del diseño, para celular y para computadora, y muestra un reporte por dispositivo con la nota general y las métricas principales.
Para recibir también la lista de recomendaciones de mejora, agrega --detailed. La auditoría puede tardar algunos minutos.
Publicar el diseño en la tienda
Ejecutar nuvemshop theme publish.
La publicación convierte a ese diseño en el diseño productivo de la tienda, es decir, el que los clientes empiezan a ver. La terminal confirma indicando que el diseño fue publicado.
Helpjuice Warning Callout Title
Antes de publicar en la tienda de un cliente, confirma que nadie esté editando el diseño que está en vivo, y usa el link de vista previa para aprobar el resultado.
¿Cómo administro los diseños de la tienda desde el CLI?
Además de editar, el CLI crea, duplica, actualiza y elimina diseños. Haz clic en cada tarea para ver los detalles:
Crear un diseño nuevo
Ejecutar nuvemshop theme create --base-theme "ipanema" --title "<título>".
El comando devuelve el id del diseño creado. Por el momento, el diseño base aceptado es ipanema. De forma opcional, se puede sumar --base-theme-variant "<variante>" para elegir una variante puntual del catálogo. Si no se indica, se usa la variante Clothing por defecto.
Clonar un diseño existente
Ejecutar nuvemshop theme clone.
El CLI crea un diseño idéntico al de origen y devuelve el id del nuevo diseño. Es el camino para trabajar en una copia sin tocar el diseño que está en vivo.
Actualizar la versión del diseño base
Ejecutar nuvemshop theme update.
La actualización crea un borrador nuevo en una versión más reciente del diseño base, y el diseño de origen queda intacto. Antes de crear nada, el CLI te informa qué ediciones locales se descartarían.
Para ver solo ese reporte, sin crear el borrador, agrega --dry-run. También se puede indicar la versión de destino con --to "<versión>" y un título propio para el borrador nuevo con --title "<título>"; si no se indican, el CLI ofrece las versiones disponibles y asigna un título por defecto.
Eliminar un diseño
Ejecutar nuvemshop theme delete.
La eliminación es permanente y no tiene vuelta atrás. Elimina el diseño de la tienda, pero no borra los archivos de tu carpeta local.
Preguntas frecuentes sobre el CLI de Tiendanube
¿Qué modo de sincronización debo usar?
Depende del diseño de la tienda. El modo Fork, que usa la API pública, funciona solo en diseños basados en secciones, como Ipanema, y es donde están los comandos de vista previa, diff, performance y publicación.
El modo FTP cubre los diseños legados y abarca configuración, descarga, envío y seguimiento de los cambios.
Los dos modos guardan la configuración en el mismo archivo .nuvem, así que es posible tener las dos configuraciones en la misma carpeta.
¿El CLI recolecta datos de uso?
Sí, el CLI recolecta datos anónimos de uso por defecto, para identificar qué comandos usa la gente y cuáles fallan.
Se recolectan el comando ejecutado, si funcionó o falló, cuánto tardó, las versiones del CLI, de Node.js y del sistema operativo, y un identificador aleatorio generado en tu máquina.
No se recolectan datos de la tienda ni de la cuenta, nombres ni contenidos de archivos, credenciales, tokens, configuración de FTP, argumentos de comando ni mensajes de error.
Para revisar la configuración actual, ejecuta nuvemshop telemetry status. Para desactivarla, ejecuta nuvemshop telemetry disable.
¿En qué sistemas operativos funciona el CLI?
El CLI está basada en Node.js y funciona en Windows, macOS y Linux de la misma manera que cualquier otro paquete de npm instalado globalmente.
¿Cómo desinstalo el CLI?
Si la instalaste globalmente, ejecuta npm uninstall -g @tiendanube/cli.
Si solo usaste npx, no hay nada para eliminar, simplemente deja de usar el comando.
Para la referencia completa de los comandos y de los parámetros de cada uno, consulta la documentación oficial de el CLI.