Claude Code + Shopify CLI Integration Guide (2026)

Why Nobody Has Written This Tutorial Yet

Search "shopify cli claude code" and you will find forum threads, a few cryptic X posts, and zero step-by-step tutorials. That is strange, because in April 2026 Claude Code + Shopify CLI is the single highest-leverage pairing for anyone building Shopify themes or apps. You get an agent that can read every Liquid file in your repo, scaffold an app, run shopify theme dev, parse the output, and fix theme check errors in the same loop — without you touching your mouse.

This guide is the missing manual for Claude Code Shopify CLI integration. We will cover installing both tools side by side, configuring CLAUDE.md so the agent never pushes to your live theme by accident, wiring up the Shopify Dev MCP server for grounded docs, scaffolding apps with shopify app init, running theme check as a quality gate, and the five errors you will hit in your first hour (plus the fix for each). Think of it as a companion piece to our broader Claude Code for Shopify development playbook — that article is the overview, this one is the workflow.

If you are a Shopify developer who still copy-pastes Liquid into a chat window, treat this as a graduation ceremony. By the end, you will have a terminal setup that does the boring half of your job while you focus on the creative half.

Setup: Install Claude Code and Shopify CLI Side by Side

You need three tools on your machine: Node.js 20.10+, the Shopify CLI, and Claude Code. Skip any one of them and nothing below will work.

Install Node through nvm or Volta — never a global installer — because Shopify's theme commands are pinned to the Node version in your shell. Then run:

# Install Shopify CLI 3.x globally
npm install -g @shopify/cli@latest

# Install Claude Code (official Anthropic installer)
curl -fsSL https://claude.ai/install.sh | bash

# Verify both
shopify version
claude --version

A working setup will show Shopify CLI 3.70+ and Claude Code 1.x or newer. The official Shopify CLI install docs list platform-specific notes for Windows (WSL2 is strongly recommended) and for corporate proxies.

Authenticate Before You Open Claude Code

Run shopify auth login and shopify theme list --store your-store.myshopify.com before you ever start Claude Code. Two reasons:

• The CLI caches your store handle. Claude Code inherits the cache and stops asking mid-task.
• Auth tokens live in your OS keychain, not in environment variables the agent can read. That is a security feature — keep it that way.

Start Claude Code Inside the Project, Not Your Home Directory

Always launch Claude Code from the root of a Shopify theme or app repo. The agent indexes whatever directory it starts in, and if you launch it from ~/ it will try to index your entire home folder. Use cd /path/to/theme && claude — muscle-memorize it.

Configure CLAUDE.md for Shopify CLI Projects

CLAUDE.md is a markdown file Claude Code auto-loads as persistent context. Without it, the agent has to rediscover your project conventions every session. With it, you get deterministic behavior across runs.

Drop this template at the root of any Shopify theme repo:

# Project: {Store Name} Theme

## Stack
- Dawn fork (Shopify CLI 3.x)
- Node 20.10, Liquid, Vanilla JS (no framework)
- Deployed via `shopify theme push` to staging; production push requires --live flag

## Commands

![Isometric diagram of code deploying to Shopify](./images/theme-development-workflow.png)

- `shopify theme dev --store {store}.myshopify.com` — local preview
- `shopify theme check` — run theme check linter
- `shopify theme push --unpublished --json` — push to unpublished theme
- NEVER run `shopify theme push --live` without explicit user approval

## Conventions
- Section schema settings are alphabetized
- All new sections use app blocks (type: "@app")
- Images use `image_url: width: 800, format: 'webp'`
- Asset names kebab-case; snippet names kebab-case

This is the minimum. The full pattern for skills, subagents, and slash commands lives in the Claude Code best practices docs.

Separate Skills for Theme vs App Work

If your repo contains both a theme and a custom app, create two CLAUDE.md files — one at theme/CLAUDE.md and one at app/CLAUDE.md. The agent reads the nearest file when it changes directories. Store-wide conventions (branding, commit style) go in the root CLAUDE.md; command-specific rules go in the subdirectory files.

Document Danger Zones Explicitly

The single most valuable line in any Shopify CLAUDE.md is a negative instruction. "Never push to the live theme." "Never hardcode API keys." "Never run shopify theme delete without listing first." Agents follow negative instructions surprisingly well when they are unambiguous.

Theme Dev Workflow Inside Claude Code

The magic moment is running shopify theme dev from inside Claude Code and watching the agent parse the preview URL, the hot-reload status, and any Liquid errors without you copy-pasting anything.

Start a session with:

> Run `shopify theme dev --store my-store.myshopify.com` and share the preview URL. When I describe a change, edit the correct Liquid file, and the server will hot-reload automatically.

Claude Code will spawn the dev server as a background process, wait for the "Preview your theme" line, pull the URL, and idle. When you say "add a testimonials section below the hero," it edits sections/testimonials.liquid, saves, and the running theme dev hot-reloads the iframe. You never leave the terminal.

Let the Agent Watch the Logs

Ask the agent to "tail the dev server output and stop if you see a Liquid error." Shopify CLI streams compile errors to stdout — Claude Code can see them in real time and patch the offending file before you notice. This is the workflow difference the Shopify Dev MCP launch post is pointing at when it talks about "agent-native development."

Use --theme-editor-sync for Settings Changes

If a merchant is editing settings in the theme editor while you edit code locally, pass --theme-editor-sync so the CLI pulls their changes down. The agent should be told about this flag in CLAUDE.md, because without it the agent will happily overwrite a merchant's color picker tweaks.

Theme Push Safety Rules You Must Enforce

Pushing to production is where autonomous agents get dangerous. One wrong flag and a live store's checkout breaks. Here is the comparison table you want pinned to your CLAUDE.md:

Encode this as a slash command like /push-staging that runs the safe form and refuses the dangerous one. The Shopify theme commands reference documents every flag — worth skimming before you write your own slash commands.

Always Back Up Before a Live Push

Even with a safety rule, accidents happen. Before any --live push, have the agent run shopify theme pull --theme {live-id} --path ./.backup-{timestamp} and commit it to a backups branch. This takes thirty seconds and has saved more than one merchant's Black Friday.

Preview With theme share Before theme push

For agency work, skip push --live entirely. Use shopify theme share to generate a 7-day preview URL, send it to the client, and only promote once they approve. This workflow is easy to encode as a Claude Code subagent called "client-preview."

App Scaffolding With Claude Code

shopify app init creates a Remix-based app skeleton, wires up OAuth, and registers webhooks. Run it inside Claude Code and you get scaffolding plus a reading of the generated code in one motion.

Type:

> Run `shopify app init my-app --template remix` and then summarize the folder structure. Explain what `shopify.web.toml`, `shopify.app.toml`, and the `extensions/` folder are for.

The agent scaffolds the app, reads the three TOML files, and gives you a walk-through. This is especially useful if it has been six months since you built your last custom app — the Shopify app structure docs update often enough that you will forget details.

Generate Extensions Through the Agent

Shopify apps are built from extensions — Admin UI, Checkout UI, Theme App, Functions. The CLI command shopify app generate extension is interactive, which confuses non-TTY agent runs. Use the --type flag to pre-answer:

shopify app generate extension --type=ui_extension --name=product-review-summary
shopify app generate extension --type=theme_app_extension --name=loyalty-badge
shopify app generate extension --type=function --name=volume-discount --template=product_discounts

Claude Code handles these non-interactively and then edits the generated extensions/{name}/src/ files to match your spec. This is the fastest way to go from "I have an idea" to "I have a working Shopify Function" — topic we covered hands-on in our Shopify Functions tutorial.

Scaffold Webhooks in shopify.app.toml, Not Code

Since CLI 3.50, webhook subscriptions live declaratively in shopify.app.toml. Tell the agent: "Add a ORDERS_CREATE and APP_UNINSTALLED webhook to shopify.app.toml pointing at /webhooks." It will edit the TOML correctly and regenerate the Remix route stubs. Doing this manually is error-prone — agents are actually better at TOML than most humans.

MCP Server Integration With Shopify Dev MCP

The single biggest upgrade to Claude Code + Shopify CLI in 2026 is the Shopify Dev MCP server. MCP (Model Context Protocol) is Anthropic's open standard for connecting tools and data to LLMs, and Shopify's implementation gives Claude Code grounded, versioned access to the entire Shopify docs corpus plus live GraphQL schema introspection.

Install it with a single line in your Claude Code MCP config (~/.config/claude-code/mcp.json):

{
  "mcpServers": {
    "shopify-dev-mcp": {
      "command": "npx",
      "args": ["-y", "@shopify/dev-mcp@latest"]
    }
  }
}

Restart Claude Code and the agent gains three new tools: search_dev_docs, introspect_admin_schema, and fetch_docs_by_path. Ask "What is the correct GraphQL mutation to create a draft order in 2026-04?" and the agent queries the live schema instead of hallucinating fields that were deprecated two years ago.

Ground Every GraphQL Query Through MCP

A rule worth adding to CLAUDE.md: "Before writing any Admin API GraphQL query, call introspect_admin_schema for the relevant type. Never guess field names." Agent-written GraphQL is still the #1 source of runtime errors in custom Shopify apps. MCP-grounded queries almost eliminate this class of bug. Anthropic's MCP documentation covers the protocol in depth if you want to build your own server for proprietary APIs.

Combine With the Shopify CLI MCP (Experimental)

In preview as of April 2026, the Shopify CLI team is shipping a complementary MCP server that exposes shopify theme dev, shopify app dev, and log tailing as first-class agent tools — removing the need to shell out. Watch the Shopify Partners changelog for the general availability announcement.

Running Theme Check as a Quality Gate

shopify theme check is the official linter for Liquid themes, enforcing performance, accessibility, and schema correctness rules from the theme check repo. You should run it before every theme push, and Claude Code is great at acting on its output.

Generate the config with the agent:

> Create a `.theme-check.yml` at the repo root. Enable all default checks except `MissingTemplate` (we have an intentionally minimal template set). Set severity to `error` for `ParserBlocking` and `AssetSizeCSS`.

Claude Code will write a clean config. Then ask it to run shopify theme check --fail-level error --output json, parse the JSON, and fix each issue in order of severity. This is a loop it can complete autonomously — no human-in-the-loop for style violations.

Wire Theme Check Into a Pre-Commit Hook

Add a Husky pre-commit hook that runs shopify theme check --fail-level error. Claude Code can set this up in under a minute: "Add Husky and lint-staged, run theme check on staged .liquid files before commit." You will never push a theme with a ParserBlocking script again.

Use --auto-correct Carefully

Theme check's --auto-correct flag fixes many issues in place, but it has been known to strip custom whitespace in .liquid files. Have the agent review the diff after auto-correct before staging. A useful slash command: /theme-check-fix that runs theme check --auto-correct, shows the git diff, and asks for approval.

Debugging CLI Errors From Inside Claude Code

Every Shopify developer hits the same five errors in their first week. The fix for each is known; the trick is teaching Claude Code to recognize the error and apply the fix without asking.

Paste this table into your CLAUDE.md and the agent will self-correct instead of stalling. This is the same pattern experienced developers use when they share debugging lore inside our Shopify community — write it down once, save a hundred hours.

Teach the Agent to Read shopify app dev Output

The shopify app dev command streams logs from three processes (the tunnel, the Remix server, and the extension compiler) interleaved. Extract-and-fix patterns Claude Code should learn:

• Tunnel error → "Waiting for Cloudflare tunnel" for 30+ seconds: kill and restart with shopify app dev --reset.
• GraphQL 401 on webhook registration: app is missing a scope — edit shopify.app.toml and redeploy.
• `Extension type "checkout_ui_extension" is deprecated`: migrate to ui_extension via the Checkout Extensibility upgrade guide.

Capture Logs to a File the Agent Can Re-Read

For long-running shopify app dev sessions, pipe output to a log file: shopify app dev 2>&1 | tee .tmp/app-dev.log. The agent can grep or tail the file any time, whereas reading its own shell scrollback after a token-heavy conversation gets messy. This tip alone will pay for itself by the end of your first real debugging session.

Common Mistakes That Break the Integration

Even a perfect setup can fail because of habits carried over from non-agent workflows. These are the five most common self-inflicted injuries.

1. Running Claude Code with `--yolo` or equivalent auto-approve modes on live stores. Never. The agent's judgment on destructive commands is good, not perfect, and shopify theme push --live is the wrong command to be imperfect on. Keep approval prompts on for anything that touches production.

2. Treating `CLAUDE.md` as write-once. You will discover new conventions every week. Schedule a Friday 10-minute review of your CLAUDE.md files, add the new rules, remove obsolete ones. The file is living documentation for your agent co-worker.

3. Skipping the MCP server and asking the agent from memory. Pre-MCP, agents hallucinated GraphQL fields regularly. Post-MCP, there is no excuse. If the agent proposes a mutation without calling introspect_admin_schema first, reject the change.

4. Using global `shopify` instead of per-project CLI version pinning. In a theme with a package.json, add @shopify/cli as a dev dependency and commit a pnpm-lock.yaml. This guarantees Claude Code, CI, and every teammate run the same CLI version. Version drift bugs are brutal to debug.

5. Forgetting to clean up tunnels. shopify app dev creates Cloudflare tunnels that sometimes linger after Ctrl+C. If you see "address already in use," run shopify app dev --reset or, in extreme cases, pkill cloudflared. Document this in CLAUDE.md so the agent knows the recovery path.

Do Not Let the Agent Deploy Apps Silently

shopify app deploy pushes extensions to a new version in the Partner Dashboard. It is not reversible beyond rolling back to a prior version — and only Admins can do that. Make this a requires-human-approval command in every project. Your future self (or your agency client) will thank you.

Do Not Store Store Passwords in CLAUDE.md

Obvious, but it happens. CLAUDE.md is often committed to git. Store credentials belong in .env.local (gitignored) or, better, in your OS keychain via shopify auth login. If you need to share a dev store password with an agent, paste it into the live conversation, not the persistent config.

Real Workflow: Building a Custom Section From Scratch

Here is a compressed transcript of a real session — scaffolding, editing, testing, and pushing a custom "featured-reviews" section with zero mouse clicks.

1. cd ~/code/acme-theme && claude
2. Prompt: "Create a new section called featured-reviews that displays 3 product reviews from metafields. Each review has author, rating (1-5 stars rendered as SVG), and body. Make it responsive and add schema settings for background color and heading."
3. Claude reads sections/, notices the existing convention of using class="page-width" and Dawn-style schema blocks, generates sections/featured-reviews.liquid with correct metafield namespace syntax.
4. Prompt: "Run shopify theme check and fix any errors."
5. Claude runs the linter, sees an ImgLazyLoading warning, adds loading="lazy" to the star SVGs' wrapper, re-runs, passes.
6. Prompt: "Push to the unpublished staging theme."
7. Claude runs shopify theme push --unpublished --json, parses the response, grabs the preview URL, returns it.

Total time: under four minutes. The same flow six months ago — manual schema writing, switching windows to theme check, opening the Shopify admin to find the unpublished theme ID — would have taken twenty. That compounding time savings is why Claude Code adoption among Shopify developers in our developer communities has roughly tripled since November 2025.

Wiring Up CI With GitHub Actions + Shopify CLI

The integration does not stop at your laptop. You can run Claude Code non-interactively in CI to, for example, auto-fix theme check issues on every pull request, or generate a changelog from the diff.

A minimal workflow:

# .github/workflows/theme-check.yml
name: Theme Check
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20.10'
      - run: npm install -g @shopify/cli@latest
      - run: shopify theme check --fail-level error

Add a second job that runs claude --print "Summarize the theme check output and suggest fixes" for agent-generated PR comments. This is the same pattern the Talk Shop team uses for its own blog automation — a glimpse of which is discussed in our AI automation for Shopify stores coverage.

Gate Production Deploys on Human Review

Never let a GitHub Action push to a live theme unattended. Require a manual approval step on the deploy-live job via GitHub's environment protection rules. The GitHub Actions environments docs walk through the exact settings.

Measuring Whether the Integration Is Paying Off

If you cannot measure the time saved, you cannot justify the behavior change. Track three simple metrics for your first month:

• PRs per day. Pre-Claude, most solo theme devs shipped 1-2 PRs/day. Target 4-5 by week three.
• Theme check errors per PR. Should trend to zero; the agent fixes them before you see them.
• Time from idea to preview URL. Stopwatch it. Benchmark: section scaffold + push to staging should be under 10 minutes from prompt to URL.

If those numbers are not moving, the problem is almost always CLAUDE.md — either it is too vague or it is missing the danger-zone negatives. Iterate on the config until the agent behaves like a senior dev.

Key Takeaways and What to Build Next

The Claude Code Shopify CLI integration is not an incremental productivity bump — it is a workflow shift on the scale of "stopped using FTP, started using git." You write prompts instead of keystrokes, the agent drives the CLI, and you spend your time on design, architecture, and merchant conversations.

The minimum-viable setup is five things: Shopify CLI 3.70+, Claude Code, a CLAUDE.md at the repo root with commands and danger zones, the Shopify Dev MCP server wired into your MCP config, and theme check in a pre-commit hook. Every other optimization — custom slash commands, per-directory CLAUDE.md files, CI agent comments — is a cherry on top.

If you want to go further, read the pillar guide at Claude Code for Shopify development, browse the latest theme techniques on Talk Shop's blog, and when you are ready to hire or be hired for this kind of agent-assisted work, check out the Shopify experts network to connect with teams already shipping this way.

Your turn: What is the first Shopify CLI command you are going to let Claude Code run autonomously — theme dev, theme check, or app generate extension? Share your setup in the Talk Shop Discord and we will debug your CLAUDE.md live.

About Talk Shop

The Talk Shop team — insights from our community of Shopify developers, merchants, and experts.