Shopify CLI Vs Theme Kit

If you’re choosing between Shopify CLI and Theme Kit for theme development in 2026, the decision is already made for you: Shopify officially deprecated Theme Kit in September 2024 and now directs every developer to Shopify CLI. Theme Kit still installs and runs basic push/pull operations on existing projects, but it no longer receives feature updates, won’t support newer Shopify capabilities, and Shopify has confirmed it will stop functioning entirely at some point. This guide covers the side-by-side comparison, the CLI commands you’ll actually run day-to-day, the SHOPIFY_CLI_THEME_TOKEN setup for non-interactive CI deploys, and a 15-minute migration path if you’re still on Theme Kit.

What Is the Shopify CLI? (Quick Overview for 2026)

The Shopify CLI is the official command-line tool for building and managing Shopify themes, apps, and Hydrogen storefronts. Since Theme Kit was deprecated in 2024, the CLI is the only Shopify-supported workflow for theme development. The latest stable release as of 2026 is Shopify CLI 3.x, installed with npm: npm install -g @shopify/cli @shopify/theme (Node 18 or higher is required).

The three most common use cases for the CLI in 2026:

• Theme development: shopify theme dev spins up a local preview at http://127.0.0.1:9292 with hot reload. Edit any Liquid, CSS, or JS file and the browser refreshes instantly.
• App development: shopify app dev (and shopify app init to scaffold a new app) proxies your local app through a Cloudflare tunnel so Shopify can talk to it during testing. No more ngrok setup, no more manual webhook configuration.
• Hydrogen (headless) storefronts: shopify hydrogen dev runs a local Hydrogen server with the same hot-reload experience as theme dev.

If you’ve ever used Theme Kit, the muscle-memory difference is that everything now starts with the literal command shopify followed by the resource type (theme, app, or hydrogen) and then the action. Most of what Theme Kit could do, the CLI can do better. A few workflows (especially batch CI deploys) need a different approach, which the comparison below and the SHOPIFY_CLI_THEME_TOKEN section cover in detail.

Theme Kit Is Deprecated, What That Means for You

In September 2024, Shopify officially announced that Theme Kit (also known as themekit, the Go-based CLI tool that developers used for years) is no longer actively developed. The official Shopify documentation now directs every theme developer to use Shopify CLI instead.

What still works on Theme Kit:

• Pushing and pulling theme files to and from existing Shopify stores.
• Watching for local file changes and syncing them.
• Working with themes that don’t use Online Store 2.0 features.

What does NOT work on Theme Kit:

• Local theme preview with hot reload. Theme Kit relies on a polling-and-sync model that’s much slower than Shopify CLI’s local dev server.
• Full support for Online Store 2.0 features. JSON templates, app blocks, theme app extensions, and section-rendering API endpoints work properly only through Shopify CLI.
• Modern theme-check rules. Shopify’s theme-check linter receives updates only through the CLI.
• Future Shopify features. Anything new from Shopify’s theme platform from 2024 onward will be CLI-only.

Should you migrate immediately? If you’re starting a new theme project, yes, use Shopify CLI from day one. If you have an existing project on Theme Kit and it’s not broken, you can keep using Theme Kit short-term. But the migration is small (covered later in this guide) and the longer you wait, the more deprecated tooling debt you accumulate.

Quick Comparison Table: Shopify CLI vs Theme Kit

How to Install Shopify CLI

Install with one npm command:

npm install -g @shopify/cli @shopify/theme

Node 18+ is required. Verify the install with shopify version, which prints the installed version (currently Shopify CLI 3.x as of 2026). If you’d rather not install globally, run it on-demand with npx @shopify/cli@latest, useful in CI containers where you want the latest version every run.

The first time you run any shopify theme command in a directory, the CLI opens a browser window for OAuth login. Sign in with the Shopify account that has access to the development store. Authentication persists in your home directory, so you only do this once per machine.

Migrating From Theme Kit to Shopify CLI

If you have an existing Theme Kit project, here’s the practical migration path. The whole process takes about 15 minutes per theme.

Step 1, Install Shopify CLI. If you don’t already have it: npm install -g @shopify/cli @shopify/theme. Verify with shopify version.

Step 2, Authenticate. From your theme directory, run shopify theme dev --store your-store.myshopify.com. The first time, it opens a browser window for OAuth login. Theme Kit’s API-password approach is replaced. You authenticate once with your Shopify account and the credentials persist locally.

Step 3, Confirm the theme structure is compatible. Theme Kit and Shopify CLI use the same theme folder structure (assets, config, layout, locales, sections, snippets, templates). No file restructuring is needed for the migration itself.

Step 4, Replace your Theme Kit commands. Practical one-to-one mapping:

• theme watch → shopify theme dev
• theme deploy → shopify theme push
• theme download → shopify theme pull
• theme open → shopify theme open
• theme new → shopify theme init

Step 5, Update your config.yml. Theme Kit used a config.yml in the theme root for store URL and API password. Shopify CLI doesn’t need this file at all. Store identity is handled through the OAuth session and command flags. You can delete the config file once you’re confident the CLI workflow is working.

Step 6, Update your CI/CD or deployment scripts. If you’re using Theme Kit in GitHub Actions, GitLab CI, or any deploy automation, swap the binary download for the npm install plus update the commands. For non-interactive auth in CI, set SHOPIFY_CLI_THEME_TOKEN (see the next section). Shopify also publishes a GitHub Action that wraps the CLI for theme deployment.

SHOPIFY_CLI_THEME_TOKEN: Non-Interactive Auth for CI/CD and Headless Deploys

The OAuth browser flow is great for local development but useless in CI pipelines, headless servers, or any context where no human is sitting at a browser. For those cases, Shopify CLI reads a theme access token from the SHOPIFY_CLI_THEME_TOKEN environment variable and authenticates non-interactively.

Step 1, Generate a theme access token. Install Shopify’s Theme Access app on the target store (free, official Shopify app). Inside the app, create a new password for the developer or pipeline that needs deploy access, and Shopify emails them a token that starts with shptka_. Treat this token like a password.

Step 2, Export the variables in your CI environment. Two variables are needed together: the token and the store URL.

export SHOPIFY_CLI_THEME_TOKEN=shptka_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
export SHOPIFY_FLAG_STORE=your-store.myshopify.com

In GitHub Actions, store both as repository secrets and reference them in your workflow’s env: block. In GitLab CI, add them as masked variables under Settings, CI/CD, Variables. Whatever your runner is, make sure they’re masked so the token never prints in build logs.

Step 3, Run the CLI as normal. Once the variables are set, every shopify theme command runs without prompting. A typical CI deploy step looks like this:

shopify theme push --unpublished --json --path ./theme

Add --theme=$THEME_ID to push to a specific existing theme, or --allow-live to publish over the live theme (use with care, usually gated behind manual approval in production pipelines).

App-side equivalent: For app-development CI workflows, the matching variable is SHOPIFY_CLI_PARTNERS_TOKEN, generated from your Shopify Partners dashboard. It authenticates shopify app deploy and other app commands non-interactively.

Common gotcha: the older SHOPIFY_PASSWORD and SHOPIFY_API_KEY variables from the Theme Kit era are not equivalent and won’t work with Shopify CLI. If you’re migrating a pipeline, delete those, generate a new Theme Access token, and set SHOPIFY_CLI_THEME_TOKEN instead.

Essential Shopify CLI Commands for Theme Developers

The day-to-day commands you’ll run most often:

shopify theme dev, starts a local development server with hot reload. Edit any theme file and the browser updates immediately. This is the headline feature that Theme Kit can’t match.

shopify theme push, uploads your local theme to a development theme on the connected store. Add --unpublished to push to a brand-new unpublished theme, or --theme=THEME_ID to push to a specific existing theme.

shopify theme pull, downloads a theme from your store to your local directory. Use this to sync changes another developer made via the theme editor.

shopify theme check, lints your theme files for errors, deprecated syntax, and Liquid issues. Run before pushing to catch problems early.

shopify theme list, lists all themes on the connected store with their IDs. Useful when you need to push to a specific theme.

shopify theme init, creates a new theme project from Shopify’s Dawn theme starter. Faster than cloning a repo manually.

shopify theme open, opens the current theme in the Shopify admin’s theme editor in your browser.

shopify theme share, generates a temporary preview URL for your unpublished theme that anyone can access without authentication. Useful for sharing work-in-progress with clients.

shopify login / shopify logout, manage your active OAuth session. Run shopify logout if you need to switch Shopify accounts on the same machine.

Workflow Comparison: Speed and Feedback

Shopify CLI workflow. Shopify CLI runs a local development server at http://127.0.0.1:9292. You edit a Liquid file in your editor, the CLI detects the change, and the browser updates in milliseconds, no manual push, no waiting for sync. The theme check linter catches errors before you push to production. For solo developers and small teams who prioritize speed, this workflow is significantly faster than anything Theme Kit can do.

Theme Kit workflow (legacy). Theme Kit watches local files and pushes changes to your Shopify store as you save. You then refresh the browser to see changes. The round-trip time is several seconds even on a fast connection. Error detection is limited and most problems surface only after you push to production.

Authentication and Security

Theme Kit used API passwords stored in config.yml files. Anyone who got that file got full access to your store, and rotating credentials meant updating every developer’s local config. Shopify CLI replaced this with OAuth: you authenticate through the browser once, the credentials never sit in a file, and revoking access is one click in the Shopify admin. For pipelines, scoped Theme Access tokens (the shptka_ values used with SHOPIFY_CLI_THEME_TOKEN) are revocable per-developer, per-store, without touching anyone else’s setup. This is materially better for any team larger than one person.

Troubleshooting Tips

If shopify theme dev hangs on startup: ensure your store URL is correct (no trailing slash, includes .myshopify.com) and that your account has access to the store. The CLI will print a clear error if authentication fails.

If hot reload stops working mid-session: restart the dev server. This is rare but happens after large structural changes (adding new sections, renaming templates).

If theme check reports errors you don’t agree with: the linter has a config file at .theme-check.yml in your theme root where you can disable specific rules. Don’t disable broadly, the rules exist for good reasons, but it’s reasonable to silence one or two that don’t apply to your project.

If SHOPIFY_CLI_THEME_TOKEN isn’t being picked up in CI: confirm both the token and SHOPIFY_FLAG_STORE are exported in the same shell step as the shopify command. Setting them in one job step and running the CLI in another (without re-exporting) is the most common cause of “not authenticated” errors in GitHub Actions and GitLab pipelines.

If you need to fall back to Theme Kit for a specific reason: it still installs and runs, but document why and plan the eventual migration. “We need it for X” is fine; “we’re avoiding Shopify CLI on principle” stops being defensible as more Shopify features become CLI-only.