Shopify CLI Guide — UrbanRoast Dev Session

0

CLI no instalada — Setup inicial

Setup

"Me aparece shopify: command not found en el equipo nuevo. ¿Qué hago?"

⚠️

Causa Shopify CLI no está instalado globalmente (o el PATH no incluye npm global bins). Instalar con npm una sola vez lo soluciona.

Asegúrate de tener Node 18+ activo: node -v
Instala la CLI globalmente:

bash

# Instalar Shopify CLI globalmente
npm install -g @shopify/cli@latest

# Verificar versión instalada
shopify version

# Ver todos los comandos disponibles
shopify commands

# Actualizar en el futuro
shopify upgrade

✓ @shopify/cli@3.67.2 instalado correctamente ✓ shopify version 3.67.2

💡

Si el comando sigue sin encontrarse tras instalar, ejecuta npm config get prefix y añade ese directorio + /bin a tu $PATH.

1

Validar configuración de la app antes del deploy

Config Validate

"¿Cómo valido mi shopify.app.toml y la extensión de descuento antes de hacer shopify app deploy?"

La herramienta correcta es shopify app config validate --json desde la raíz del proyecto. No uses GraphQL validation ni revisión manual campo a campo.

app root

→

shopify app config validate --json

→

interpretar JSON output

→

shopify app deploy

bash — desde /urbanroast-app/

# Validar configuración principal (shopify.app.toml)
shopify app config validate --json

# Si tienes config con nombre: shopify.app.staging.toml
shopify app config validate --json --config staging

# Si trabajas desde otro directorio
shopify app config validate --json --path ./urbanroast-app

{ "valid": true, "config_file": "shopify.app.toml", "errors": [], "warnings": [ "extension 'discount-function': scopes should include 'write_discounts'" ] }

🟡

Warning detectado La extensión discount-function necesita el scope write_discounts. Añádelo a shopify.extension.toml antes del deploy para evitar rechazos en revisión.

shopify.app.toml valid: true ✓
API version, scopes, urls — OK

shopify.extension.toml warning: scope missing ⚠
Añadir write_discounts

2

Listar productos del store desde la CLI

Store Execute

"Quiero ver todos mis productos y sus SKUs desde la terminal, sin entrar al Admin."

Flujo store auth → store execute. Siempre incluir --store en ambos comandos.

bash

# 1. Autenticar (scope mínimo para lectura de productos)
shopify store auth \
  --store urbanroast.myshopify.com \
  --scopes read_products

# 2. Listar productos con sus variantes y SKUs
shopify store execute \
  --store urbanroast.myshopify.com \
  --query '{ products(first: 20) { edges { node {
      id title handle
      variants(first: 10) { edges { node {
        id sku inventoryQuantity
      }}}
  }}}}'

✓ Autenticado en urbanroast.myshopify.com { "data": { "products": { "edges": [ { "node": { "title": "Café Etiopía Yirgacheffe", "handle": "etiopia-yirgacheffe", "variants": { "edges": [ { "node": { "sku": "ETHIOPIA-YIRGA-250G", "inventoryQuantity": 12 }}, { "node": { "sku": "ETHIOPIA-YIRGA-1KG", "inventoryQuantity": 5 }} ]}} }} ]}} }

Operación	Scope requerido	Flag adicional
Leer productos	read_products	—
Modificar productos	write_products	—
Leer inventario	read_inventory	—
Ajustar inventario	write_inventory	`--allow-mutations`

3

Ajustar inventario por SKU y almacén

Mutation · --allow-mutations

"Necesito ajustar el SKU ETHIOPIA-YIRGA-250G en Madrid Warehouse a 45 unidades."

⚠️

Flujo de 3 pasos Las mutaciones de inventario requieren primero resolver el inventoryItemId por SKU y el locationId por nombre de almacén, luego llamar a inventorySetQuantities.

Paso A — Autenticar con scopes de inventario:

bash

shopify store auth \
  --store urbanroast.myshopify.com \
  --scopes read_products,read_inventory,write_inventory

Paso B — Resolver inventoryItemId por SKU:

bash

shopify store execute \
  --store urbanroast.myshopify.com \
  --query '{ productVariants(first: 1, query: "sku:ETHIOPIA-YIRGA-250G") {
    edges { node { inventoryItem { id } } }
  }}'

# → inventoryItemId: "gid://shopify/InventoryItem/44291823935638"

shopify store execute \
  --store urbanroast.myshopify.com \
  --query '{ locations(first: 10) { edges { node { id name } } }}'

# → locationId Madrid Warehouse: "gid://shopify/Location/67392847921"

Paso C — Ajustar a 45 unidades (mutation):

bash

shopify store execute \
  --store urbanroast.myshopify.com \
  --allow-mutations \
  --query 'mutation {
    inventorySetQuantities(input: {
      name: "available",
      quantities: [{
        inventoryItemId: "gid://shopify/InventoryItem/44291823935638",
        locationId: "gid://shopify/Location/67392847921",
        quantity: 45
      }]
    }) {
      inventoryAdjustmentGroup { id reason }
      userErrors { field message }
    }
  }'

✓ Mutation ejecutada correctamente { "inventorySetQuantities": { "inventoryAdjustmentGroup": { "id": "gid://shopify/InventoryAdjustmentGroup/98234", "reason": "correction" }, "userErrors": [] ← sin errores ✓ } } ✓ SKU ETHIOPIA-YIRGA-250G · Madrid Warehouse: 12 → 45 unidades

✅

Regla clave Toda mutation requiere --allow-mutations en shopify store execute. Las queries de lectura no lo necesitan. Nunca omitas --query ni --store.

★

Cheatsheet — Comandos esenciales UrbanRoast App

App Development

            shopify app dev

            shopify app build

            shopify app deploy

            shopify app config validate --json

            shopify generate extension

Store Operations

            shopify store auth --store ... --scopes ...

            shopify store execute --store ... --query '...'

            shopify store execute ... --allow-mutations

            shopify store execute ... --query-file q.graphql

CLI Maintenance

            shopify version

            shopify upgrade

            shopify commands

            shopify help [command]

Docs

shopify.dev/docs/api/shopify-cli
Admin GraphQL Reference
CLI Tools Guide

Shopify CLI — Guía Operativa