Shopify Theme Dev Command: Flags, Tokens, and Non-Interactive CI

A client’s preview pipeline hung for eleven minutes before the runner timed out. I pulled the log: shopify theme dev was sitting at a login prompt that no human was ever going to answer. The fix the previous contractor had reached for was shopify theme dev --store x --password y --force, on the theory that --force would push past the prompt. It does not exist on this command. The prompt was there because the auth token was passed as a flag the CI environment had stripped, not as the environment variable the command actually reads.

TL;DR: shopify theme dev has no --force flag and no --no-store or offline mode. Authenticate with --password (a Theme Access or Admin API token, env SHOPIFY_CLI_THEME_TOKEN) and --store (env SHOPIFY_FLAG_STORE). To run it non-interactively in a script or CI, set those two as environment variables and the command skips every prompt. Do not confuse --password (CLI auth) with --store-password (the storefront password on a locked store).

Why this matters for your store:

• A theme dev call that stalls on a hidden prompt fails the whole build, and the log rarely says “I am waiting for input.” It just hangs until the runner kills it.
• Half the broken setups I audit pass the storefront password where the auth token belongs, or the reverse. They are two different secrets with two different jobs.
• theme dev spins up a development theme that renders real store data. Running it against the wrong store, or a live theme without meaning to, is a foot-gun worth understanding before you automate it.

The shopify theme dev flags that actually exist

These are the real shopify theme dev flags, each with the environment variable that sets it. The env var is the part that matters for non-interactive runs.

# The ones you use daily
shopify theme dev \
  --store my-store \           # -s, env SHOPIFY_FLAG_STORE
  --password shptka_xxx \      # env SHOPIFY_CLI_THEME_TOKEN (Theme Access / Admin API token)
  --theme 123456789012         # -t, env SHOPIFY_FLAG_THEME_ID (else a dev theme is created)

The supporting cast, all real and all documented:

• --store-password (env SHOPIFY_FLAG_STORE_PASSWORD): the storefront password for a password-protected store. Not authentication.
• --theme-editor-sync (env SHOPIFY_FLAG_THEME_EDITOR_SYNC): pull Theme Editor changes back into your local files while the server runs.
• --live-reload <mode> (env SHOPIFY_FLAG_LIVE_RELOAD): hot-reload (default), full-page, or off.
• --allow-live (-a, env SHOPIFY_FLAG_ALLOW_LIVE): permit running against the live theme. Off by default for good reason.
• --nodelete (-n), --only (-o), --ignore (-x): control which files sync and reload.
• --host, --port: bind the local preview server.
• --environment (-e, env SHOPIFY_FLAG_ENVIRONMENT): apply a named environment (see the last section).

Authentication: --password is not --store-password

This is the single most common theme dev failure I see. The two flags sound alike and do completely different things.

--password authenticates the CLI. The value is a password generated by the Theme Access app or an Admin API token, and it carries scopes. For theme dev it needs read_themes and write_themes. Its environment variable is SHOPIFY_CLI_THEME_TOKEN.

--store-password is the storefront password, the one you set under Online Store preferences when the store is hidden behind a password page. It has nothing to do with API auth. Its environment variable is SHOPIFY_FLAG_STORE_PASSWORD.

# Locked store, run as the developer with a Theme Access token
SHOPIFY_CLI_THEME_TOKEN=shptka_xxx \
shopify theme dev --store my-store --store-password hunter2

Pass the auth token where the storefront password goes and the CLI fails to connect. Pass the storefront password where the token goes and it cannot read your themes. When a theme dev setup “just won’t connect,” check this first.

Running shopify theme dev non-interactively (CI, scripts, dev containers)

This is what most people are actually asking when they search for --force or “non-interactive”: how do I run this with zero prompts? The answer is environment variables, not a flag.

# No prompts, no flags: the command reads these and proceeds
export SHOPIFY_CLI_THEME_TOKEN=shptka_your_theme_access_token
export SHOPIFY_FLAG_STORE=my-store.myshopify.com

shopify theme dev

With both variables set, theme dev authenticates with the token and connects to the store without asking anything. One scope detail trips up hot reloading specifically: the token needs unauthenticated_read_content in addition to read_themes and write_themes, and it must arrive as the SHOPIFY_CLI_THEME_TOKEN env var, not the --password flag, for the Storefront API integration that powers hot reload to initialize.

Generate the token from the Theme Access app (one token per collaborator, revocable, scoped to themes) rather than a full Admin API key. It is the safer secret to drop into a CI variable.

There is no --force, no --no-store, no mock local filesystem mode

All three show up in searches and none of them exist on theme dev.

--force is real on other commands (theme delete --force skips the confirmation prompt), which is probably where the muscle memory comes from. On theme dev it does nothing but throw an unknown-flag error. There is no prompt for it to skip anyway once your env vars are set.

--no-store and any notion of a “mock local filesystem” mode also do not exist. theme dev always connects to a real store and uploads to a development theme, because rendering Liquid needs that store’s data (products, collections, metafields). If you want to exercise Liquid logic without a store, reach for shopify theme console, the Liquid REPL, instead. There is no offline theme dev.

For the sibling command and the path-argument change that bites people the same way, see my note on the Shopify theme check --path argument.

Managing multiple stores with environments

If you hop between a development store, a staging store, and a client’s production store, stop typing --store and --password every time. Define them once in a shopify.theme.toml at the project root.

# shopify.theme.toml
[environments.staging]
store = "client-staging"
theme = "123456789012"
password = "shptka_staging_token"

[environments.production]
store = "client-live"
password = "shptka_prod_token"

shopify theme dev --environment staging   # or -e staging

An [environments.default] table is applied automatically when you omit --environment. Precedence is command flag, then environment variable, then the toml value, so a flag you type always overrides the file. Keep tokens out of the committed file on shared repos; reference them through env vars and leave the file for store and theme IDs.

The takeaway:

• theme dev has no --force and no --no-store. Those queries are dead ends.
• Authenticate with --password (env SHOPIFY_CLI_THEME_TOKEN), a Theme Access or Admin API token, never the storefront password.
• --store-password is the locked-storefront password, a separate secret for a separate job.
• For non-interactive runs, export SHOPIFY_CLI_THEME_TOKEN and SHOPIFY_FLAG_STORE; add unauthenticated_read_content to the token if you need hot reload.
• Use shopify.theme.toml environments to stop repeating --store and --password across projects.

For the wider Liquid and theme-tooling workflow these commands sit inside, see my Shopify Liquid best practices guide.