Theme Tooling and Workflow

Four tools cooperate in a theme workflow, and the rest of the page takes them in turn.

A typical Pocket Coffee change travels through them like this. A developer scaffolds or pulls the theme, runs a local preview against the development store, lints, and pushes a branch. CI lints again and uploads the branch to a throwaway development theme so that a reviewer gets a preview link. After the merge, CI uploads the release as a new unpublished theme and publishes it. Merchant edits made later in the theme editor come back to the repository as commits made by Shopify.

Shopify CLI is one npm package for apps, themes and Hydrogen storefronts. The documented requirements are Node.js 22.12 or later, a package manager (npm, Yarn 1.x or pnpm) and Git 2.28.0 or later. The 5.0.0 changelog additionally requires Git 2.38.0 or later for the operations that use Git, which concerns the app commands more than the theme commands.

Source: Shopify CLI: requirements and installation

Yarn (yarn global add @shopify/cli@latest), pnpm (pnpm install -g @shopify/cli@latest) and Homebrew (brew tap shopify/shopify then brew install shopify-cli) are the other documented routes. A theme repository can also depend on @shopify/cli as a development dependency so that every developer and the CI runner use the same version.

Three behaviours of recent versions matter for a team.

Source: Shopify CLI for themes

All theme commands share a set of flags that are worth knowing once, because each of them also has an environment variable, which is how CI configures the CLI without long command lines.

Source: Shopify CLI theme command reference

The CLI accepts three kinds of credentials for a store.

The first command against a store names it with --store, for example shopify theme dev --store pocket-coffee-dev, and later commands reuse it. shopify theme info prints the store, the theme and the CLI environment currently in use. Storefronts that are protected by the storefront password additionally need --store-password (environment variable SHOPIFY_FLAG_STORE_PASSWORD); since 2026-09-23 the theme CLI needs version 3.84.0 or later for password-protected shops, which every 5.x release satisfies.

Source: Shopify CLI for themes: authentication

Most theme commands only run in a directory that matches the default theme structure, which describes a buildless theme or the output of a build step.

Source: Shopify CLI for themes: directory structure

shopify theme init produced exactly these eight folders on 2026-10-27 together with some repository files (README, LICENSE, CODE_OF_CONDUCT, CONTRIBUTING, .gitignore, .gitattributes and .shopifyignore). If a project uses a build pipeline, run the CLI from the directory that holds the generated theme, or point --path at it.

Files that live in the repository but must never be uploaded or overwritten go into .shopifyignore at the theme root. It accepts exact file names, wildcards and regular expressions between slashes, and the --ignore flag of push and pull adds to it rather than replacing it. The Skeleton copy of the file ships with commented examples of the three forms.

Source: Shopify CLI for themes: excluding files

Excluding config/settings_data.json and the JSON templates is the usual way to stop a deployment from overwriting what a merchant configured in the theme editor. The trade-off is that new settings or templates that the release needs must then be created by other means, so use the exclusion only when the merchant owns those files.

Flags such as --store, --theme and --ignore add up quickly. A shopify.theme.toml at the project root names reusable sets of flags, each under [environments.<name>]. Any flag of the command can be used except environment, path and verbose, which the documentation says are ignored (see below for how path behaves with several environments). Boolean flags are set to true and repeatable flags are arrays.

Source: Theme environments for Shopify CLI

Use an environment with shopify theme push --environment staging (or -e staging). The CLI prints the flags it took from the environment. An environment called default is applied to every theme command without -e. Values are applied in this order of precedence, from strongest to weakest: flags typed on the command line, environment variables such as SHOPIFY_CLI_THEME_TOKEN, then the TOML environment. A flag in an environment that the running command does not accept is ignored, a wrongly typed value or mutually exclusive flags are errors, and a few shared flags change meaning between commands (force on delete deletes without asking), so keep destructive flags out of environments.

Several environments in one run are supported by check, delete, info, list, publish, pull, push, rename and share: repeat the flag, for example shopify theme push -e staging -e production. With several environments the CLI does not prompt, so every required flag must be in the command or the file, and an environment that lacks one is skipped with a warning. In this run of 5.0.0 shopify theme check -e staging -e production reported "Missing required flags in environment configuration" and named path until each environment contained path = "."; after that, check ran once per environment and prefixed each summary with the environment name. With a default environment present the output of every command also carries a [default] prefix.

Because the file can hold passwords, the docs show a password key in an environment. For a repository that is shared, leave the key out and supply the password through SHOPIFY_CLI_THEME_TOKEN, as the CI workflows below do.

shopify theme init [name] clones a Git repository into a new folder named name (a prompt asks for it when omitted). Without options it clones Shopify’s Skeleton theme from https://github.com/Shopify/skeleton-theme.git, then removes the .git folder so that the copy starts as plain files.

Source: shopify theme init

On 2026-10-27 the first run cloned Skeleton, removed .git and left 39 inspectable files that pass Theme Check without an offense. A later run from the same machine failed because the command asks the GitHub releases API about the repository and the anonymous rate limit (HTTP 403, "API rate limit exceeded") had been used up. This is a property of running the command from a shared address, not of the theme. Retrying later, or cloning with plain git clone and deleting .git, gives the same files.

The CLI help carries a caution for Theme Store authors: the example theme may be used as a starting point, but the submitted theme has to be substantively different from existing themes. The Theme Store requirements add that Skeleton is the only approved codebase and that themes built on or derived from Dawn or Horizon are not eligible. Dawn 16.0.0 and Horizon 4.3.0 are valid starting points for a merchant’s own storefront, which is the Pocket Coffee case, but the choice between the three is a design decision covered with the reference themes, not a tooling one.

Source: Theme Store requirements

shopify theme dev uploads the local theme to the store as a development theme and keeps it in step while you edit. It prints three things: a local URL, by default http://127.0.0.1:9292, that serves the store’s data through your local files; a link to the theme editor for the development theme in the admin; and a preview link that other developers can open. If a development theme already exists for the current environment, the command replaces it with your local files, unless you use --theme-editor-sync. Checkout customizations cannot be previewed on the local URL.

Source: shopify theme dev

Source: shopify theme dev

Two pitfalls follow from the behaviour above. The server runs only in a directory with the default theme structure, so a mistyped --path ends in an error. And a dev server that finishes or crashes leaves the development theme in the store; it disappears after seven days of inactivity or on logout.

shopify theme push uploads local files to a remote theme and, unless told otherwise, deletes remote files that do not exist locally. Without a target it asks which theme to overwrite. In non-interactive environments it needs exactly one of --development, --live, --theme or --unpublished, and --allow-live when the target is the live theme.

Source: shopify theme push

With --json the result conforms to the ThemePushJsonResult schema, which --json-schema prints. For one environment it is an object with status (success or partial), changed, a theme object (id as a decimal string, not a GraphQL ID, plus name, role, storeDomain, previewUrl and editorUrl) and issues (an array of filePath and message for files that failed to upload). With several environments the result is { "environments": [...] }, where each entry holds either a result (including status values skipped for an unsafe directory and cancelled) or an error of type abort, bug or external.

Source: shopify theme push: JSON output

Extracting the theme ID in a shell step works with jq -r '.theme.id'; the command printed 108267175958 for this sample. A partial status or a non-empty issues array means some files did not upload, so a deployment script should fail on anything other than success with empty issues.

shopify theme pull downloads the files of a remote theme into the current directory. It is the way to bring a merchant’s edits (theme editor settings, section order, JSON templates) into the repository when the GitHub integration is not in use, and the way to start a project from a store that has no repository yet.

Source: shopify theme pull

Pull overwrites local files that differ, so run it on a clean working tree or a new branch and review the diff before committing. Pulling only JSON templates and settings is a safe routine for capturing merchant changes without touching code.

shopify theme publish makes an unpublished theme the live theme. It does not upload anything: push first to create the theme, then publish it by ID or name. It asks for confirmation, which --force (SHOPIFY_FLAG_FORCE) skips and which is required in non-interactive runs, as is --theme (SHOPIFY_FLAG_THEME_ID). --json returns a ThemePublishResult with the theme (including a processing flag).

Source: shopify theme publish

shopify theme share uploads the local files as a new unpublished theme with a randomized name and prints a preview link, which makes it a quick way to show work to a stakeholder without touching named themes. It accepts --store, --password, --environment, --listing and --json (ThemeShareResult), and it can be repeated, so remove old shared themes with shopify theme delete or in the admin. Unlike theme dev, the shared theme survives shopify auth logout.

Source: shopify theme share

shopify theme package zips the local theme so it can be uploaded in the admin or submitted to the Theme Store. Only the folders of the default structure are included, plus listings when it exists (required for multi-preset themes). The file is named theme_name-theme_version.zip after theme_name and theme_version in config/settings_schema.json, and --json prints its absolute path as { "path": "..." }.

Source: shopify theme package

In the Skeleton copy used for this page the command wrote Skeleton-0.1.0.zip, because settings_schema.json declares "theme_name": "Skeleton" and "theme_version": "0.1.0". The archive contained only assets, blocks, config, layout, locales, sections, snippets and templates, and the roast date snippet added to the project, and contained no README, licence or Theme Check configuration. Rename the theme and bump the version in the schema file before packaging Pocket Coffee, or every release will be called Skeleton-0.1.0. The generated .gitignore already excludes *.zip.

The other commands work against a store and are listed here so that the whole shopify theme topic of CLI 5.0.0 is covered.

Source: Shopify CLI theme command reference

Theme Check is the linter for Liquid and JSON in themes and in theme app extensions. It finds syntax errors, missing templates and assets, unused variables and snippets, unknown and deprecated tags and filters, translation problems and performance problems, and it links each finding to documentation for the failing check. It runs through the CLI on demand or in CI, through the Liquid language server in editors, and in the Shopify Liquid VS Code extension. Checks are written in TypeScript, so a team can add its own (require in the configuration).

The engine needs the Shopify Liquid reference data (filters, tags, objects, schemas and system translations). It downloads it the first time it runs and caches it on the machine (on macOS under ~/Library/Caches/theme-liquid-docs-nodejs/). The cached copy used for this page held 155 filters, 33 tags and 142 objects. Later runs worked with the network blocked, so a CI job needs network access on its first run and benefits from caching that directory afterwards.

The Shopify GitHub app connects the store to a GitHub account or organization and keeps a branch and a store theme in step in both directions. A push to the branch updates the theme in the admin; a save in the theme editor, the code editor or a theme app in the Online Store becomes a commit on the branch. The integration can connect several branches, each as a separate theme (unpublished or published), so a campaign can live on its own branch.

A pipeline needs a Node.js step, a step that installs the CLI, and a step that runs the command, with these inputs.

The CLI version must be 3.20 or later. Prefer environment variables over --password on the command line, because command lines can appear in logs and process lists. The official example installs the CLI with npm install -g @shopify/cli after actions/setup-node@v4 with node-version: 20; the CLI itself now requires Node.js 22.12 or later, so the workflows below use Node 22 instead. Pin the CLI major version (@shopify/cli@5) so that a breaking major release does not change your pipeline overnight; in CI the CLI does not upgrade itself.

Source: Use Shopify CLI in a CI/CD pipeline