• Configure environments
  • Use an environment

Theme environments for Shopify CLI

Many command configurations, such as the theme and store to be used with the command, are passed using flags. To avoid passing multiple flags with each command, and to easily switch projects or contexts, you can use environments. Environments are sets of command configurations that can be referenced by name using a single --environment flag.

You might want to use environments in the following cases:

  • You need to switch between development stores frequently.
  • You access multiple stores using Theme Access passwords.
  • You want to deploy your project to development, staging, and production instances of your theme.

You need to configure environments in each theme repository where you work. Environments are configured using a shopify.theme.toml configuration file.

Configure environments

Anchor link to section titled "Configure environments"

To configure an environment for your local theme project, do the following:

  1. Create a file called shopify.theme.toml at the root of the project.
  2. For each environment that you want to create, add a table heading using the syntax [environments.YOUR_ENVIRONMENT_NAME].
  3. Below the heading that you created, add key-value pairs for the flags and flag values that you want to use for the environment.

You can set environment-specific values for any flag, except for environment, path, verbose, which are ignored.

To use a Boolean flag for an environment, specify true as the value.

Caution

Some shared flags, such as force, have a different meaning depending on the command. Including these flags in your environment might have unintended consequences in some contexts. For example, applying force on the delete command will delete a theme without confirmation.

Use an environment

Anchor link to section titled "Use an environment"

To use an environment, pass the environment name with your command:

The flag values that are applied to the command are displayed:

How environment flags are applied

Anchor link to section titled "How environment flags are applied"

You can use environments with any theme command. Environment flags are applied using the following rules:

  • If a flag is included in an environment, but it isn't accepted for the command that you're running, then it's ignored.
  • If your environment uses the wrong data type for a flag, or applies mutually exclusive flags, then an error is thrown.

  • Flag values are applied in order of precedence:

    1. Command-level flags
    2. Environment variables
    3. Environment settings from shopify.theme.toml

    This means that if you pass a flag as part of a command, then the flag value that you passed in the command will be used instead of the environment flag value:

On this page

  • Configure environments
  • Use an environment