Shopify CLI para temas: desarrolla en local con theme dev, push y pull

Editar un tema de Shopify directamente en el editor de código del administrador funciona para un cambio rápido, pero se queda corto en cuanto trabajas en serio: no tienes control de versiones, no puedes usar tu editor favorito y cada prueba implica guardar y recargar. Shopify CLI resuelve eso: es una herramienta de línea de comandos para construir apps y temas de Shopify, que te permite trabajar en local, ver los cambios en tiempo real y subir el tema con un comando.

En este artículo me enfoco en el desarrollo de temas.

Requisitos e instalación

Según la documentación oficial, necesitas:

• Node.js 22.12 o superior
• Un gestor de paquetes de Node.js: npm, Yarn 1.x o pnpm
• Git 2.28.0 o superior

Instálalo de forma global para poder ejecutar shopify desde cualquier carpeta:

npm install -g @shopify/cli@latest

También hay comandos equivalentes para Yarn (yarn global add @shopify/cli@latest) y pnpm (pnpm install -g @shopify/cli@latest). En macOS, además, puedes usar Homebrew:

brew tap shopify/shopify
brew install shopify-cli

Para ver los comandos disponibles, ejecuta shopify help. La sintaxis general es shopify [tema] [comando].

Sobre las actualizaciones: a partir de Shopify CLI 4.0, la herramienta se actualiza sola usando el gestor de paquetes con el que la instalaste (no lo hace en entornos de CI, instalaciones locales del proyecto ni en cambios de versión mayor). Para actualizar de inmediato, usa shopify upgrade. Si prefieres desactivarlo, shopify config autoupgrade off.

Qué te da

Estas son las funciones principales que describe la documentación:

• Previsualizar, probar y compartir cambios con seguridad usando temas de desarrollo.
• Recarga en caliente (hot reload) de cambios en CSS y secciones, o recarga automática de la página al cambiar un archivo.
• Iniciar un tema nuevo.
• Subir y publicar temas desde la línea de comandos.
• Trabajar con varios temas usando entornos.
• Ejecutar Theme Check sobre tu tema.

Temas de desarrollo

Un tema de desarrollo es un tema temporal y oculto conectado a la tienda que usas para desarrollar. Así pruebas en local con los datos reales de esa tienda. Puedes usarlo en una tienda de Shopify o en una tienda de desarrollo. Según la documentación:

• No cuentan para el límite de temas de tu tienda.
• Se eliminan de la tienda tras siete días de inactividad.
• Se eliminan también cuando ejecutas shopify auth logout.

Si necesitas un enlace de vista previa que siga funcionando después de cerrar sesión, sube el tema como un tema no publicado con shopify theme push (o shopify theme share).

Empieza: theme init

Este comando clona un repositorio de Git para usarlo como punto de partida. Si no indicas ninguno, crea una copia del tema Skeleton de Shopify con el nombre que le des en la carpeta actual (si no das nombre, te lo pide):

shopify theme init [name] [flags]

Con -u, --clone-url indicas otro repositorio de Git para clonar. Si vas a publicar un tema en la Theme Store, la documentación avisa de que el tema que envíes debe ser sustancialmente distinto de los existentes.

Conéctate a una tienda

La primera vez que ejecutes un comando que interactúa con una tienda, pasa el flag --store:

shopify theme dev --store my-store

La tienda que indiques se usa en los comandos siguientes hasta que especifiques otra. Para comprobar con cuál trabajas, ejecuta shopify theme info.

Para autenticarte hay tres opciones:

1. Iniciar sesión con una cuenta de Shopify: una cuenta de colaborador con el permiso Manage themes, una cuenta de personal con el permiso Themes, o el propietario de la tienda. Se te pide el inicio de sesión cuando ejecutas un comando que requiere acceso a la tienda.
2. Una contraseña de Theme Access: la generas con la app Theme Access y la pasas con el flag --password.
3. Un token de acceso de una app personalizada: también con --password. La app necesita los alcances read_themes y write_themes; para la recarga en caliente, además, unauthenticated_read_content, y en ese caso pasas los tokens como variables de entorno en lugar de usar --password.

Para cambiar de cuenta, cierra sesión con shopify auth logout.

Desarrolla con theme dev

Este es el comando que más vas a usar. Sube tu tema local a la tienda como tema de desarrollo (o como el tema que especifiques) y te da:

• Un enlace local en http://127.0.0.1:9292 que recarga en caliente los cambios de CSS y secciones, o refresca toda la página cuando cambia un archivo, usando los datos de la tienda.
• Un enlace al editor del tema en el administrador de Shopify.
• Un enlace de vista previa que puedes compartir con otros desarrolladores.

shopify theme dev

Puedes cambiar la interfaz de red y el puerto con --host y --port. Estos son algunos flags útiles de la referencia:

Dos avisos importantes de la documentación: no puedes previsualizar personalizaciones del checkout en http://127.0.0.1:9292, y si ya tienes un tema de desarrollo para tu entorno actual, el comando lo reemplaza con tu tema local (puedes cambiar esto con --theme-editor-sync).

Sube y baja cambios: theme push y theme pull

theme push sube tus archivos locales a Shopify. Si no indicas un tema, te pide elegir cuál sobrescribir de la lista de tu tienda.

shopify theme push

Un ejemplo de la referencia, que crea un tema nuevo no publicado y devuelve la información en JSON (útil para scripts o CI):

shopify theme push --unpublished --json

Otros flags relevantes:

theme pull hace lo contrario: descarga los archivos del tema desde Shopify. Si no indicas un tema, te muestra la lista para elegir.

shopify theme pull

Usa -l, --live para bajar el tema en vivo, -d, --development para el de desarrollo, y -n, --nodelete para que no se borren archivos locales que no existen en remoto.

Un consejo mío: antes de un push sobre un tema en vivo, haz un pull reciente. Si alguien editó el tema desde el administrador, sobrescribirlo con tu copia local podría borrar esos cambios. Ojo con -a, --allow-live: úsalo solo cuando estés seguro de lo que subes.

Revisa tu código con theme check

Este comando ejecuta Theme Check para analizar tu tema y comprobar que cumple las buenas prácticas de temas y de Liquid:

shopify theme check

Con -a, --auto-correct corrige automáticamente lo que puede, --init genera un archivo .theme-check.yml, y --fail-level define la severidad mínima con la que sale con código de error (útil en CI).

Otros comandos que conviene conocer

La referencia incluye, entre otros:

• shopify theme list: lista los temas de tu tienda con sus IDs y estados.
• shopify theme open: devuelve enlaces para previsualizar el tema indicado.
• shopify theme share: sube tu tema como un tema nuevo no publicado en tu biblioteca de temas.
• shopify theme publish: publica un tema no publicado de tu biblioteca.
• shopify theme console: inicia el REPL de Liquid.
• shopify theme package: empaqueta tus archivos en un ZIP que se puede subir a Shopify.
• shopify theme profile: perfila el Liquid de una página.
• shopify theme metafields pull: obtiene metafields del administrador de Shopify.

Estructura de directorios

Algunos comandos, como theme dev, solo funcionan si la carpeta cumple la estructura predeterminada de un tema de Shopify:

└── project
    ├── assets
    ├── blocks
    ├── config
    ├── layout
    ├── locales
    ├── sections
    ├── snippets
    └── templates
        └── customers

Si usas herramientas de compilación para generar los archivos del tema, quizá tengas que ejecutar los comandos desde la carpeta donde quedan los archivos generados.

Entornos y archivos ignorados

Muchas configuraciones se pasan con flags (tienda, tema, etc.). Para no repetirlos, usa entornos: conjuntos de configuración que se llaman por nombre con un solo flag --environment. Sirven, por ejemplo, para alternar entre tiendas de desarrollo o para desplegar a instancias de desarrollo, staging y producción. La documentación de entornos explica cómo configurarlos.

Si en el mismo repositorio tienes archivos con los que no quieres que la CLI interactúe, agrégalos a un .shopifyignore en la raíz del tema. Acepta nombres simples (templates/product.temp.json), comodines (config/*_secret.json, *.jpg) y expresiones regulares (/\.(txt|gif|bat)$/). También puedes excluir archivos en un push o pull con --ignore.

Un flujo de trabajo razonable

Este es el que yo seguiría, y es una recomendación mía, no una regla de Shopify:

1. shopify theme pull para partir del tema actual y guardarlo en Git.
2. shopify theme dev para trabajar con recarga en caliente.
3. shopify theme check antes de cada commit.
4. shopify theme push --unpublished para revisar el resultado en un tema no publicado.
5. Publicar solo cuando todo esté revisado.

Y si usas un agente de IA para acelerar el trabajo con Liquid, mira cómo el Shopify AI Toolkit con Claude Code le da acceso a la documentación oficial de Shopify.

Conclusión

Con theme dev, push, pull y theme check tienes un flujo de desarrollo de temas comparable al de cualquier proyecto web: tu editor, control de versiones y revisión automática. La documentación oficial detalla todos los flags de cada comando; esta guía cubre los que más se usan.

Fuentes

• Shopify CLI for themes
• Shopify CLI (instalación y requisitos)
• Shopify CLI Theme commands
• theme dev
• theme push
• theme pull
• theme check
• theme init