--- title: Theme environments for Shopify CLI description: >- Learn how to configure multiple development environments for your theme repository. source_url: html: 'https://shopify.dev/docs/storefronts/themes/tools/cli/environments' md: 'https://shopify.dev/docs/storefronts/themes/tools/cli/environments.md' --- ExpandOn this page * [Configure environments](https://shopify.dev/docs/storefronts/themes/tools/cli/environments.md#configure-environments) * [Use an environment](https://shopify.dev/docs/storefronts/themes/tools/cli/environments.md#use-an-environment) * [Use multiple environments](https://shopify.dev/docs/storefronts/themes/tools/cli/environments.md#use-multiple-environments) # 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](https://shopify.dev/docs/storefronts/themes/tools/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 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](https://shopify.dev/docs/api/shopify-cli/theme), except for `environment`, `path`, `verbose`, which are ignored. To use a Boolean flag for an environment, specify `true` as the value. ## shopify.theme.toml ```text [environments.env1] theme = "123456789012" store = "my-store" password = "shptka_123456" ignore = "sections/header.liquid" [environments.env2] store = "another-store" path = "./dist" ignore = ["sections/announcement-bar.liquid", "sections/header.liquid"] output = "json" live = true allow-live = true ``` 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 To use an environment, pass the environment name with your command: ```terminal shopify theme dev --environment env1 # using the flag alias shopify theme dev -e env1 ``` The flag values that are applied to the command are displayed: ```terminal shopify theme dev --environment env1 ╭─ info ─────────────────────────────────────────────────╮ │ │ │ Using applicable flags from env1 environment: │ │ │ │ • store: my-store │ │ • password: *******456 │ │ • ignore = "sections/header.liquid" │ │ │ ╰────────────────────────────────────────────────────────╯ ``` ### Set 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. ### 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](https://shopify.dev/docs/storefronts/themes/tools/cli/ci-cd#step-2-integrate-shopify-cli-into-your-pipeline) 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: ```terminal shopify theme dev --environment env1 --store my-new-store --password shptka_102938 ╭─ info ─────────────────────────────────────────────────╮ │ │ │ Using applicable flags from env1 environment: │ │ │ │ • ignore = "sections/header.liquid" │ │ │ ╰────────────────────────────────────────────────────────╯ ``` *** ## Use multiple environments Some theme commands support multiple environments: * `check` * `delete` * `info` * `list` * `publish` * `pull` * `push` * `rename` * `share` To use multiple environments, pass the environment names with your command: ```terminal shopify theme delete --environment env1 --environment env2 --development ``` Caution When using multiple environments, the CLI doesn't prompt for missing information. Include all required flags in the command or your `shopify.theme.toml` file. If a required flag is missing, then the environment is skipped and a warning will be shown. If the command doesn't accept a `--force` flag, then it runs immediately. Otherwise, a confirmation prompt will be displayed: ```terminal ? Run delete in the following environments? ┃ Environment ┃ • env1 store: my-store.myshopify.com, password, development: true ┃ • env2 store: another-store.myshopify.com, password, development: true > (y) Yes, proceed (n) Cancel ``` *** * [Configure environments](https://shopify.dev/docs/storefronts/themes/tools/cli/environments.md#configure-environments) * [Use an environment](https://shopify.dev/docs/storefronts/themes/tools/cli/environments.md#use-an-environment) * [Use multiple environments](https://shopify.dev/docs/storefronts/themes/tools/cli/environments.md#use-multiple-environments)