Development Environment

Shopify CLI follows semantic versioning since 4.0.0 (2026-05-21). Version 5.0.0 (2026-10-27) is a major release because it types the JSON output of every command: scripts that parse --json output must be updated, and shopify <command> --json-schema prints the result, error and event schemas of any command.

Source: Shopify CLI 4.0.0 release notes; Migrate to Shopify CLI 5.0

Since 4.0 the CLI upgrades itself with the package manager that installed it. It does not upgrade in CI, in project-local installs, or when the next release changes the major version. These commands control it.

Source: Shopify CLI: upgrade and auto-upgrade

The CLI collects usage data by default, including the commands and flags you run, timings, errors, and identifiers such as your Shopify account ID, app client ID and store domain. Opt out with the environment variable SHOPIFY_CLI_NO_ANALYTICS=1 or OPT_OUT_INSTRUMENTATION=true. The runs on this page used SHOPIFY_CLI_NO_ANALYTICS=1 and CI=1, which also disables prompts and automatic upgrades.

Source: About Shopify CLI for apps: usage reporting

Every command accepts the same cross-cutting flags, and each flag has an environment-variable twin named SHOPIFY_FLAG_<NAME>, which is how CI systems pass them.

Source: Shopify CLI reference (flags read from the --help output of CLI 5.0.0)

Without a login, a command that needs one stops instead of opening a browser when prompts are disabled. This is the real output of shopify app init --no-input --name pocket-coffee-app --organization-id 1 --template reactRouter --flavor typescript in a logged-out environment. Nothing was created.

Source: shopify app init

Source: Dev Dashboard

Access is role based. Partner organizations get system roles, and merchant organizations can assign the App developer role. Custom roles with the permissions "Create and manage dev stores" and "Build and manage apps" exist on Shopify Plus.

The dashboard opens on Home if you have app development access, on Stores if you only have store permissions, and on a page reading "Your account doesn’t have developer access yet" if you have neither. In that case ask the organization owner for one of the roles above. The numeric organization ID that several CLI commands need is the last segment of the dashboard URL (https://dev.shopify.com/dashboard/<organization-id>;), and shopify organization list prints it.

Source: Dev Dashboard user permissions

The CLI is the recommended path for feature-rich apps with extensions. The dashboard path is best for automation and API-only apps with no user interface in the Shopify admin, for example a nightly job that reads Pocket Coffee orders into an accounting system. The steps are:

Source: Create apps using the Dev Dashboard

The client secret is a credential. Keep it in a secret manager and reference it from code through an environment variable such as ${SHOPIFY_CLIENT_SECRET}; never commit it. The authentication page of this subsection explains the token flows in depth.

An App Automation Token authenticates the CLI in non-interactive environments, so a pipeline can run shopify app deploy. Each token is scoped to the one app where it was created and cannot touch other apps.

To rotate, select Rotate (old and new tokens are both valid until you revoke the old one), update the CI secret, then revoke the old token. Tokens created before in the Partner Dashboard (variable SHOPIFY_CLI_PARTNERS_TOKEN) keep working until they expire, but new ones are created in the Dev Dashboard and use SHOPIFY_APP_AUTOMATION_TOKEN.

Source: Manage App Automation Tokens

Shopify measures every app without instrumentation. An app’s Overview has three cards: Operations (GraphQL and REST error rates, webhook delivery failures and Function runs, each plotted against volume), Admin performance (Largest Contentful Paint, Interaction to Next Paint and Cumulative Layout Shift measured in the merchant’s browser) and Growth (revenue, install and uninstall events). Logs puts API requests, webhook deliveries, Function runs, UI extension errors and your own app events on one timeline.

During development, the Logs view is the fastest way to answer "what did my app do for this shop?" when a test order misbehaves.

Source: Monitor app performance

shopify store create dev (CLI 4.8.0 and later) creates a dev store in your organization. It prompts for missing values, or takes them as flags. In a non-interactive run --name, --plan and --organization-id (unless you belong to a single organization) are required.

For Pocket Coffee a Basic-plan store with demo data is enough to start, in Spain:

Source: Dev stores

With --json the command prints an object with a store (name, domain, adminUrl, plan, featurePreview, country and demoData, with name, domain, plan and demoData always present) and an organization (id and name). Failures use a StoreCommandError object with error, message, nextSteps and exitCode, and progress events stream as diagnostic or progress objects. These field names come from the schema printed by shopify store create dev --json-schema, which runs without a login:

Source: shopify store create dev

The themes documentation still spells the demo-data flag --with-demo-data. The help output of CLI 5.0.0 lists --demo-data, so use that spelling.

The store setup flow completes in the Shopify admin, and the store then appears in the dashboard’s Stores list.

Source: Dev stores

shopify store create preview (CLI 4.5.0 and later) is documented as creating a Shopify store without requiring an existing account (flags --name and --country). It was not run for this page because it creates an account-bound store.

Source: shopify store create preview

Source: Dev stores for themes

--demo-data (or Generate test data for store in the dashboard) fills a new store with Shopify’s generated data. It is snowboard themed, so it does not contain Pocket Coffee products, and it is meant to give apps, themes and storefronts common cases to work with: products with all fields populated, hidden, archived, draft and out-of-stock products, multi-location inventory, selling plans (preorder, prepaid, subscription, try before you buy), gift cards, customers, two B2B companies (including some Plus-only features), locations, orders in many states, a fulfillment service, and the Bogus payment gateway enabled for test orders. Create the Pocket Coffee catalog (beans, grinds, sizes and the Starter kit) yourself in the admin or through the API, and keep the generated products to cross-check behavior.

Feature previews give early access to changes, usually backwards-incompatible API changes, before they reach all stores. Only one preview can be enabled per dev store, and it must be chosen when the store is created.

For backwards-incompatible changes the preview window is nine months, which is the time between a stable API version introducing the change and that version becoming the oldest supported one.

Source: Generated test data; Feature previews

Deleting a dev store is permanent: the store and its data are purged and cannot be restored. shopify store list returns at most 250 stores, newest first, so on a large organization always filter with --type dev. The official example below removes every dev store created more than two years ago and uses jq to filter the JSON; --force skips the confirmation that is otherwise required.

Source: Dev stores: clean up dev stores

shopify app init creates the project and the app record in the Dev Dashboard.

Source: Scaffold an app; shopify app init

The template’s public repository (Shopify/shopify-app-template-react-router) was cloned and type-checked locally (npm install --ignore-scripts, npx prisma generate, npx react-router typegen and npx tsc --noEmit finished with zero errors). Its dev script is shopify app dev and its deploy script is shopify app deploy. Running it needs a login, so app dev was not run. The app structure and configuration are explained in depth on the app scaffolding page; the part that matters for the environment is shopify.app.toml.

The file below is the configuration of the Pocket Coffee app with a placeholder client ID and a reserved invalid domain. It declares the three mandatory compliance webhooks and one subscription, and it adds the [build] table that tells app dev which dev store to use and to keep the app URLs in sync with the tunnel.

Source: App configuration

The required keys are client_id, name, application_url, embedded, [access_scopes] scopes and [auth] redirect_urls. shopify app build --no-input validates the file and builds every extension without a login. Run against the file above it printed:

Changing embedded = true to embedded = "yes" makes the same command fail, which is the kind of error to expect from a mistyped file:

Source: shopify app build

The other validation messages seen when keys are missing are [auth]: Required, [application_url]: Valid URL is required and [embedded]: Boolean is required.

shopify app dev builds your app and previews it on a dev store without deploying a version. It asks which dev store to use (the only store is selected automatically) and, while it runs, it:

Source: Test apps locally; shopify app dev

The command cannot be demonstrated without a store, so its behavior above is taken from the official documentation and from the CLI’s help text.

When app dev stops, the dev preview stays on the store, so the app configuration and extensions you added remain active until you clean up or uninstall. Cleaning restores the released version of the app to the store, and anything not in that version is removed together with its data: a Discount function you added during app dev and the discounts that reference it, a UI extension placement configured in the checkout editor, or a metaobject definition and its metaobjects. Clean from the Dev Console in the Shopify admin (it also shows the previewed app, who created the preview, the last update, whether it is connected to a local app dev, and the included extensions) or from the terminal:

Source: Test apps locally: clean up the dev preview

Because changes are isolated to one dev store, a team can share one development instance of the app. Create the development instance and its configuration file once with shopify app config link (the default shopify.app.toml is the recommended file for it). Each developer then creates their own dev store, switches to the development configuration with shopify app config use if needed, and runs shopify app dev, choosing their own store. Pocket Coffee would have pocket-coffee-dev-ada and pocket-coffee-dev-grace stores for two developers, so that previews never overwrite each other.

Source: Test apps locally: develop and test apps as a team

Source: Shopify CLI app commands

shopify app security check scans an app directory for Shopify-specific security issues and writes deterministic-findings.json and agent-checks.json to .shopify/app-security/<results key>/. It ran locally against the example project above, with no login:

Source: shopify app security check

The scan covered zero files because the example project has only a configuration file. Add the .shopify/ directory to .gitignore, since it holds local results and project state.

Theme commands authenticate in one of two ways. Interactively, the CLI logs you in with your Shopify account and uses your store access (you must be the owner or have a staff account on the dev store). For scripts and shared stores, the Theme Access app creates passwords that grant write_themes only. Pass the password with --password or the environment variable SHOPIFY_CLI_THEME_TOKEN, and the store with --store or SHOPIFY_FLAG_STORE. The password email link expires after 7 days or after the developer has viewed it once. Passwords made by the earlier "Theme Kit Access" app work too. From 2026-09-23, working against a password-protected storefront (dev stores are) needs CLI 3.84.0 or later, and --store-password supplies the storefront password.

Source: Manage theme access

shopify theme dev uploads the current theme as a development theme (a temporary theme that is not published) to the connected store, prints the theme editor and preview URLs, and pushes changes to the store as you save files.

The other store commands are theme list (--role live|unpublished|development), theme push (--development, --unpublished, --live, --publish, --only, --ignore, --nodelete, --strict, --json), theme pull, theme publish, theme share (a shareable preview theme), theme preview (JSON overrides to a preview URL), theme open, theme info, theme console (a Liquid REPL against a store), theme duplicate, theme rename, theme delete, theme profile, theme metafields pull and theme package (a ZIP of the theme, which ran locally and wrote Skeleton-0.1.0.zip). A later page of this subsection covers the full workflow.

Source: shopify theme dev

Theme Check is built into the CLI and also ships as @shopify/theme-check-node (3.31.0) and a language server (shopify theme language-server). It knows every Shopify Liquid tag, filter and object, and the JSON schema of sections and blocks. The snippet below is the Pocket Coffee roast-date badge, written with three mistakes on purpose.

Saved as snippets/roast-badge.liquid in the Skeleton starter, shopify theme check reported two errors and two warnings and exited non-zero (only errors fail the run by default):

The listing above is condensed from the boxed output of the CLI (the boxes and blank lines are removed). With -o json the same run printed {valid: false, errorCount: 2, warningCount: 2, infoCount: 0} and an issues array whose entries carry check, severity, filePath, startRow and message, which is the shape a CI annotation step reads.

Useful options: --fail-level crash|error|suggestion|style|warning|info sets the severity that makes the run fail, --auto-correct fixes what can be fixed, --list prints every enabled check with its severity, --init writes a .theme-check.yml (starting with extends: theme-check:recommended), and -C theme-check:all enables the stricter preset. Plain Liquid engines such as LiquidJS and Ruby Liquid cannot replace it: they do not know the Shopify filters (money, asset_url, image_url, t) or tags (schema, form, paginate, section, content_for), so use Theme Check for validation and shopify theme dev for real rendering.

Source: Theme Check

When you work with several stores (a dev store per developer, a staging store, production), put the per-store flags in a shopify.theme.toml at the root of the theme and select them with --environment (or -e). Each [environments.<name>] table holds flags and values (Boolean flags take true). The flags environment, path and verbose are ignored inside an environment. Never put the Theme Access password in this file when the repository is shared; use the environment variable instead.

Precedence is, from highest to lowest: flags on the command, environment variables, then the environment table. An environment named default is used when --environment is omitted. Several commands accept more than one -e: check, delete, info, list, publish, pull, push, rename and share. With several environments the CLI does not prompt for missing values, so a missing required flag skips that environment with a warning. Take care with flags whose meaning depends on the command, such as force: putting it in an environment makes theme delete run without confirmation.

Using the file above in the Skeleton starter, shopify theme check -e staging printed the applied environment flags and the result (boxes removed):

Flags that the command does not accept (here store) are ignored silently, which is why -e development also ran. An unknown environment name only produces the warning "Environment nope not found." and the command then runs with its defaults, so check the name when a command seems to ignore your settings.

Source: Theme environments for Shopify CLI

Activate it in Settings > Payments: deactivate any active credit-card provider (for Shopify Payments, Manage > Manage payment methods > Switch to a third-party provider), choose Test payment gateway from the provider list, select Activate, and save. Then check out in the storefront as a customer, using these values:

Deactivate the gateway when you finish testing. The Test payment gateway is not compatible with Shopify POS; to test POS orders use Shopify Payments in test mode on a paid plan.

Source: Placing a test order

Where Shopify Payments is available, test mode is a switch in Settings > Payments > Shopify Payments > Manage > Test mode > Enable test mode. While it is on, no real payments are captured and customers cannot place live orders. Use these rules when entering cards:

The published test numbers include the following. The official page lists more brands (Discover, Diners Club, JCB, BCcard, UnionPay, Cartes Bancaires and eftpos Australia) and more failure types.

Do not fulfill test orders: shipping labels bought for them are charged. If an app fulfills orders automatically, deactivate it before testing. Deactivate test mode when testing is finished so that real payments are captured.

Source: Testing Shopify Payments

Many third-party providers offer their own test mode: activate it in the provider’s settings and use the provider’s test cards. You can also process a real order with a real provider and then cancel and refund it immediately, though processor fees may apply (this is not possible in a dev store, where real transactions are unsupported). B2B test orders need customer accounts activated and a test company with a company location. Client transfer stores cannot be tested with real transactions, gift cards, store credit, manual payment methods (cash and POS custom payments) or draft orders created in the admin, so place test orders through the store’s checkout there; transfer the store to a paid plan to test those.

Source: Test orders in dev and client transfer stores

The orderCreate mutation builds orders that did not come through checkout. Its input has a boolean test field that marks the order as a test order, and each transaction input also has a test field. Always set both when you script test data. The mutation does not apply automatic discounts and supports one discount code only.

The two documents below were validated offline against the introspected Admin API 2026-10 schema (3,708 types, 537 mutations), together with their variables. They were not sent to a store.

The check used graphql@16 (buildClientSchema, validate and getVariableValues) and printed document VALID and variables VALID. Replacing "quantity": 2 with "quantity": "two" printed variables INVALID with Int cannot represent non-integer value: "two", and misspelling partnerDevelopment in a query printed Cannot query field "partnerDevelopement" on type "ShopPlan". Did you mean "partnerDevelopment"?. Use graphql@16 for Shopify schemas, because graphql@17 rejects the introspection result of the Admin API.

Source: orderCreate; Placing a test order

The pricing, discount and zone rules are configured by the pages that follow; this table is the checklist to repeat after each change.