Shopify CLI Theme Development Workflow

Install Shopify CLI 3.x globally via npm, Homebrew, or the official installer. Authenticate with shopify auth login and link your project to a development store with shopify theme init or by cloning an existing repo. A standard theme repo contains config/, layout/, locales/, sections/, snippets/, templates/, assets/, and optionally .theme-check.yml for lint rules.

Treat the theme like application code: version control with Git, branch per feature, and protect main. Never edit the live published theme directly in the admin code editor for production stores; use unpublished themes or development themes as targets for CLI push. Development stores are free sandboxes for full CLI capability including Theme Access tokens for CI.

Environment variables: SHOPIFY_CLI_THEME_TOKEN (Theme Access app) enables automation without interactive login. Store the shop domain, theme ID, and flags in CI secrets. ADSPOC teams standardize on Node LTS, pinned CLI versions in package.json scripts, and npm run theme:dev wrappers so juniors invoke the same commands.

shopify theme dev uploads your working copy to a temporary development theme (or an existing dev theme ID) and starts a local proxy. File saves trigger sync to Shopify and refresh the preview in the browser. Flags matter: --store flag selects the shop, --theme specifies a theme ID, --only and --ignore limit sync paths for large repos.

The CLI prints a preview URL, typically https://127.0.0.1:9292 with the remote preview tunnel, and a link to open the theme editor on the dev theme. Developers work in VS Code with Liquid syntax extensions, Theme Check on save, and Shopify Liquid language server where available.

Common issues: port conflicts on 9292, stale sessions after password changes, and firewall blocks on corporate networks. Fix by specifying --port, re-authenticating, or using cloud dev environments. Always confirm you are not developing against the live published theme ID; check theme name in the admin or CLI output before the first push.

shopify theme push deploys local files to a remote theme. Use --unpublished to create a new theme safe for QA, --live only in controlled release pipelines, and --nodelete to avoid removing remote files absent locally (use cautiously). Partial pushes with --only sections/header.liquid speed up hotfixes.

shopify theme pull downloads remote theme files, essential when merchants edited settings or apps injected snippets in admin. Resolve merge conflicts in Git after pull; never blind push over merchant changes. Promotion flow: dev theme → QA unpublished theme → scheduled push to live with backup pull first.

package.json scripts example: "theme:push:qa": "shopify theme push --unpublished --theme $QA_THEME_ID". Document theme IDs in team wiki, not in public repos. For multiple stores (staging/production), use separate shopify.theme.toml environments introduced in modern CLI config files.

Theme Check is Shopify's static analyzer for Liquid, JSON templates, and theme structure. Run shopify theme check or integrate @shopify/theme-check-node in CI. Rules flag deprecated tags, missing templates, unused assigns, parser-blocking scripts, and accessibility issues.

Customize .theme-check.yml to ignore rules temporarily during migration, but never disable performance and UndefinedObject checks in production repos. Fix TranslationKeyExists errors before launch so locales are complete. CI should fail builds on error severity; treat warnings as tech debt with tickets.

Pair Theme Check with Prettier for JSON templates and ESLint for theme JavaScript modules. ADSPOC pipelines run check on pull requests, then push to dev themes only when green, reducing regressions on merchant-facing unpublished themes.

Connect GitHub to Shopify admin under Online Store > Themes > GitHub integration to sync a branch to a theme. Commits to the linked branch update the connected theme automatically, useful for merchant-owned repos with review gates. Developers still use CLI locally for faster iteration than commit-per-save.

Shareable preview links: shopify theme share generates a URL for stakeholders without admin access. Preview themes use query parameters like ?preview_theme_id= for QA of unpublished work. Document which theme ID each link references to avoid approving the wrong build.

Collaboration patterns: designers work in Figma, developers in Git, merchants in the theme editor for content. Lock structural files in CODEOWNERS, allow merchants safe settings-only changes via schema. Runbook: feature branch → PR with Theme Check → merge → auto sync or manual push → merchant UAT on preview URL → live promotion window with rollback pull ready.