shopify-agentic-dev-workflow

A terminal-first agentic toolkit for Shopify stores. One command connects your store, sets up your local workspace, configures your AI coding agent, and gives your entire team — developers, catalogers, marketers, and business admins — a full CLI to operate Shopify without living in the Admin panel.

Works with Codex, Claude Code, Cursor, and Gemini. Shopify CLI 4.x runs under the hood.

Quick start

# Install globally from npm
npm install -g shopify-agentic-dev-workflow

# In your project folder
shopify-agent init       # connect store, configure auth, select theme, write guardrails
shopify-agent doctor     # verify all tools and show active config
shopify-agent dashboard  # snapshot of open orders, low stock, active discounts

Who this is for

| Role | What they can do | |---|---| | Developers | Theme dev (hot-reload, lint, push, publish), app dev, raw GraphQL | | Catalogers | Manage products, variants, collections, inventory | | Marketing teams | Discount codes, gift cards, pages, blog articles, redirects, metafields | | Business admins | Orders, customers, store info, dashboard |

All of it from the terminal. All mutations prompt for confirmation before touching live data.

What still needs Shopify Admin

• Add collaborator or staff access
• Create or install a custom app and approve OAuth scopes
• Connect GitHub theme sync
• Theme editor UI (drag-and-drop sections)

Commands

Setup & diagnostics

shopify-agent init              # Full interactive setup wizard
shopify-agent doctor            # Check tools, show active config + install hints
shopify-agent capabilities      # Detect which Shopify CLI 4.x commands are available
shopify-agent auth              # shopify auth login

shopify-agent agents:install    # Write AGENTS.md / CLAUDE.md / Cursor rules / GEMINI.md
shopify-agent mcp:install       # Add Shopify Dev MCP to ~/.codex/config.toml

shopify-agent profile:list      # List saved profiles
shopify-agent profile:use       # Switch active profile

shopify-agent store:list        # Show Shopify orgs linked to your account
shopify-agent store:auth        # Create Admin API token with selected scopes (CLI 4.x)

Theme development

shopify-agent theme:list        # List themes with roles
shopify-agent theme:select      # Pick active theme (live ⚠ warning included)
shopify-agent theme:pull        # Download theme files locally
shopify-agent theme:dev         # Hot-reload dev server — opens browser automatically
shopify-agent theme:check       # Liquid linting via Theme Check
shopify-agent theme:push        # Push to staging (3-option guard if theme is live)
shopify-agent theme:publish     # Prompts for confirmation before going live

App development

shopify-agent app:dev           # shopify app dev
shopify-agent app:deploy        # shopify app deploy

Raw GraphQL

shopify-agent admin:query  <file.graphql>   # Read-only Admin GraphQL
shopify-agent admin:mutate <file.graphql>   # Mutation (prompts for confirmation)

📦 Products & Catalog

shopify-agent products:list                  # List products  [--status active|draft|archived] [--limit N]
shopify-agent products:get                   # Interactive full product detail viewer
shopify-agent products:create                # Wizard: title, type, vendor, price, SKU, inventory, status
shopify-agent products:publish               # Set a product to Active (visible in store)
shopify-agent products:archive               # Set a product to Archived
shopify-agent products:draft                 # Set a product back to Draft
shopify-agent products:delete                # Delete a product (with confirmation)

shopify-agent variants:list                  # Pick a product → see all variants with price/SKU/qty
shopify-agent variants:update                # Update price, SKU, barcode for a variant

shopify-agent collections:list               # List all collections (manual + smart)
shopify-agent collections:create             # Wizard: manual or smart (with rule builder)

🏷️ Inventory

shopify-agent inventory:list                 # List all inventory levels across locations
shopify-agent inventory:set <qty>            # Set ALL variants to <qty> in bulk
shopify-agent inventory:adjust               # Adjust one variant: +5, -3, or =10

📋 Orders

shopify-agent orders:list                    # List orders  [--status open|closed|cancelled|any] [--limit N]
shopify-agent orders:get                     # Full order detail: line items, tracking, totals
shopify-agent orders:cancel                  # Cancel an open order (choose reason, refund, restock)
shopify-agent orders:close                   # Mark an order as closed

👥 Customers

shopify-agent customers:list                 # List customers  [--limit N]
shopify-agent customers:search               # Search by name, email, phone, or tag
shopify-agent customers:get                  # Full customer profile + recent order history
shopify-agent customers:create               # Wizard: name, email, phone, tags, marketing opt-in
shopify-agent customers:tags                 # Add or remove tags on a customer

🎟️ Discounts & Gift Cards

shopify-agent discounts:list                 # List all discount codes with usage stats
shopify-agent discounts:create               # Wizard: % off, fixed amount, per-customer, expiry, usage limit
shopify-agent discounts:delete               # Delete a discount code
shopify-agent discounts:enable               # Re-activate a disabled discount
shopify-agent discounts:disable              # Deactivate without deleting

shopify-agent gift-cards:list                # List all gift cards with balance
shopify-agent gift-cards:create              # Create a gift card (with optional customer assignment)

🏪 Store

shopify-agent store:info                     # Name, plan, currency, timezone, multi-currency
shopify-agent store:locations                # List locations with fulfillment status
shopify-agent store:dashboard                # Snapshot: open orders + low-stock + active discounts
shopify-agent dashboard                      # Alias for store:dashboard

📝 Content

shopify-agent pages:list                     # List all pages
shopify-agent pages:create                   # Wizard: title, body HTML, publish immediately
shopify-agent blogs:list                     # List blogs with 5 recent articles each
shopify-agent articles:list                  # Pick a blog → list articles with author + status
shopify-agent redirects:list                 # List all URL redirects
shopify-agent redirects:create               # Create a URL redirect (from → to)

🔧 Metafields

shopify-agent metafields:list                # List metafields for any resource
shopify-agent metafields:set                 # Create or update a metafield on any resource
# Works with: Product, Collection, Customer, Order, Shop

Flags

--yes, -y       Auto-confirm all prompts (for scripting / CI)
--status <s>    Filter by status where supported
--limit <n>     Limit result count where supported

Examples:

shopify-agent products:list --status active --limit 100
shopify-agent orders:list --status open
shopify-agent inventory:set 10 --yes
shopify-agent discounts:list

GraphQL template files

Pre-built query/mutation files in templates/graphql/ for use with admin:query and admin:mutate:

templates/graphql/
  products/
    list.graphql               Active products with variants and pricing
    low-inventory.graphql      Products with < 5 units (restocking alert)
  orders/
    list-open.graphql          Open orders with line items + tracking
    revenue-summary.graphql    Paid orders with totals for a date range
  customers/
    top-spenders.graphql       Customers ranked by total spend
    new-customers.graphql      Customers created in the last 30 days
  discounts/
    active-discounts.graphql   Active discount codes with usage counts
  store/
    full-info.graphql          Complete shop info + locations
    webhooks.graphql           All registered webhook subscriptions
  content/
    pages-list.graphql         All pages with SEO fields
    redirects-list.graphql     All URL redirects
  metafields/
    product-metafields.graphql Metafields for a specific product (edit GID)
  shop-query.graphql           Shop name + domain
  inventory-audit.graphql      Inventory levels across all locations
  discounts-list.graphql       All discount codes
  products-seo-audit.graphql   Products with SEO title/description gaps

Live theme safety

Every operation that touches a live theme requires explicit confirmation. theme:push on a live theme shows:

1. Push to a NEW staging theme (safe — preview before publishing)  [RECOMMENDED]
2. Push directly to LIVE theme  (type store domain to confirm)
3. Cancel

theme:publish shows the theme name, store domain, and consequences before asking.

The AI guardrail files installed by agents:install enforce the same rules inside Codex/Claude/Cursor/Gemini.

Theme dev workflow

# One-time setup per project
shopify-agent init              # connect store, select unpublished theme
shopify-agent theme:pull        # download theme files to themes/<theme-name>-<theme-id>/

# Daily loop
shopify-agent theme:dev         # hot-reload server, browser opens automatically
# edit sections/*.liquid, assets/*.css, etc.
shopify-agent theme:check       # lint after changes
shopify-agent theme:push        # push to unpublished staging theme
# preview in Shopify Admin → Themes → Preview

shopify-agent theme:publish     # prompts for confirmation — go live after review

Theme folders and Git guardrails

The CLI keeps each Shopify theme isolated under themes/<theme-name>-<theme-id>/ and writes .shopify-theme.json metadata inside that folder. This prevents a developer from pulling Theme A over Theme B or dumping theme files into the project root.

theme:pull, theme:push, and theme:publish require a clean Git worktree. Commit after every pull and before every push so every Shopify operation has a visible rollback point.

Figma-to-Dawn workflow

When building a storefront from Figma, treat design fidelity and live Shopify data as two separate concerns:

• Map Figma frames to real Dawn sections and templates: home, collection, product, cart, header, and footer.
• Use section schema settings for merchant-editable content.
• Keep design-preview fallback content until the real catalog is ready; demo store products can make a correct layout look broken.
• Add explicit toggles such as Use live collection products and Use live product data before letting Shopify catalog data override Figma visuals.
• Verify with shopify-agent theme:check and desktop/mobile preview screenshots for home, PLP, PDP, header, footer, links, and horizontal overflow.

Configuration

init creates two local files (both git-ignored):

| File | Contents | |---|---| | .env | 7 managed SHOPIFY_* keys — user-added keys are never overwritten | | .shopify-agent/profiles/<name>.json | Store domain, theme ID/name/role, token, app config, API version |

Key .env values:

SHOPIFY_STORE=your-store.myshopify.com
SHOPIFY_CLI_THEME_TOKEN=         # Theme Access token (optional; blank = Shopify CLI session)
SHOPIFY_THEME_ID=                # Active staging theme ID
SHOPIFY_API_VERSION=2026-04

Auth model

| Method | How | Best for | |---|---|---| | Shopify CLI session | shopify auth login (browser OAuth) | Local dev with Partners/staff access | | Theme Access token | Password from Theme Access app | Theme-only work, CI, agencies |

The toolkit never reads or copies Shopify CLI's internal session tokens.

Requirements

• Node.js 18+ (checked at startup — error includes install URL)
• Shopify CLI 4.x (npm install -g @shopify/cli@latest)
• Git

Optional:

• GitHub CLI (gh) for repo/PR workflow
• Codex, Claude Code, Cursor, or Gemini for AI-assisted development

Install guides

• macOS: brew install node && npm install -g @shopify/cli@latest
• Windows/Linux: see docs/00-prerequisites.md

Publishing to npm

The public npm package name is currently intended to be:

shopify-agentic-dev-workflow

Release checklist:

npm login
npm test
npm pack --dry-run
npm publish

After publishing, users can install it with:

npm install -g shopify-agentic-dev-workflow
shopify-agent init

Repository layout

bin/shopify-agent.js            CLI entrypoint — all 60+ commands, single file, no deps
docs/                           Onboarding, SDLC, security, product design notes
scripts/bootstrap.sh            Local dev bootstrap helper
templates/
  .env.example
  codex-config.toml
  github-actions/deploy-theme.yml
  graphql/                      Pre-built GraphQL query + mutation files by category
  prompts/                      Reusable agent task prompts
HANDOFF.md                      Full technical handoff for agents and new contributors

Security defaults

• Secrets are never committed — .env and .shopify-agent/ are git-ignored
• All mutation commands prompt for confirmation before modifying live store data
• theme:publish shows consequences and asks before going live
• Live theme:push requires typing the store domain
• --yes / -y flag bypasses prompts — only for scripts where user has already reviewed
• Agent guardrail files enforce all rules inside Codex/Claude/Cursor/Gemini

For the team

See HANDOFF.md for full architecture, all design decisions, and implementation details. See docs/10-field-learnings.md for lessons from a full store connection, theme pull, Figma build, and local QA session.