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.

Anchor to Configure environmentsConfigure 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.

Anchor to Use an environmentUse an environment

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

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

Anchor to Set a default environmentSet a default environment

To avoid having to specify the --environment flag with every theme command, create an environment named [environments.default]. By default, theme commands use this environment.

You can override this default whenever needed by specifying an --environment flag.

Anchor to How environment flags are appliedHow 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: