How a simple configuration task turned into a deep dive into Shopify CLI internals, and what we learned along the way.
The Problem
Like many developers, I wanted to streamline my Shopify theme development workflow. Every time I ran shopify theme dev, I had to manually specify the store URL and theme ID. This was tedious and error-prone. The solution seemed simple: use a shopify.theme.toml configuration file to store these values.
Little did I know, this would lead me down a rabbit hole of configuration mysteries.
The Initial Setup
I started by creating a shopify.theme.toml file in my theme’s root directory. Based on some online examples, I configured it like this:
[theme]
store = "my-store.myshopify.com"
theme_id = "123456789"
This seemed logical. After all, the file was for theme configuration, so [theme] made sense, right?
Wrong.
The First Clue: Environment Sections
After some research, I discovered that Shopify CLI uses “environments” for configuration. I updated the file:
[environments.default]
store = "my-store.myshopify.com"
theme_id = "123456789"
The store URL was being picked up correctly, but the theme ID was still being ignored. The CLI kept defaulting to a development theme instead of the live theme I specified.
The Authentication Detour
At one point, I encountered a 401 authentication error: “Service is not valid for authentication.” This sent me down a different path, thinking the issue was with authentication rather than configuration. After logging out and back in, the authentication worked, but the theme ID problem persisted.
The Investigation Deepens
I started investigating all possible reasons why the theme ID might not be read:
- Environment name mismatch – Was I using the wrong environment name?
- TOML syntax issues – Were there hidden syntax errors?
- CLI caching – Was the CLI caching old settings?
- File location – Was the file in the right place?
- CLI version compatibility – Was my CLI version too old or too new?
- Flag name issues – Was
theme_ideven the right flag name?
The last question turned out to be the key.
The Breakthrough: Reading the Official Documentation
After hours of troubleshooting, I finally did what I should have done from the start: I read the official Shopify CLI documentation.
The documentation revealed the truth:
Issue #1: Wrong Flag Name
The flag is called theme, not theme_id. This was a critical difference:
# ❌ Wrong
theme_id = "123456789"
# ✅ Correct
theme = "123456789"
Issue #2: Wrong Flag Format for allow-live
For working with live themes, the flag uses a hyphen, not an underscore:
# ❌ Wrong
allow_live = true
# ✅ Correct
allow-live = true
Issue #3: The Complete Configuration
The correct format according to the official documentation is:
[environments.default]
store = "my-store.myshopify.com"
theme = "123456789"
allow-live = true
The Final Solution
With the correct configuration, running shopify theme dev (or shopify theme dev --environment default) now correctly uses the specified theme ID.
Key Lessons Learned
1. Always Check the Official Documentation First
While community examples and Stack Overflow answers can be helpful, they’re often outdated or incorrect. The official documentation is the source of truth.
2. Flag Names Matter
CLI tools are often strict about flag names. A small difference like theme_id vs theme or allow_live vs allow-live can mean the difference between working and not working.
3. Environment Configuration is Powerful
Shopify CLI’s environment system is actually quite robust. You can configure multiple environments for different stores or contexts:
[environments.development]
store = "dev-store.myshopify.com"
theme = "111111111"[environments.staging]
store = “staging-store.myshopify.com” theme = “222222222”
[environments.production]
store = “prod-store.myshopify.com” theme = “333333333”
Then switch between them with:
shopify theme dev --environment development
shopify theme dev --environment staging
shopify theme dev --environment production
4. Default Environment is Convenient
Using [environments.default] means you don’t need to specify the --environment flag every time. The CLI automatically uses the default environment.
5. Flag Precedence
According to the documentation, flags are applied in this order:
- Command-level flags (highest priority)
- Environment variables
- Environment settings from
shopify.theme.toml(lowest priority)
This means you can always override config file settings with command-line flags when needed.
Common Pitfalls to Avoid
- Using
theme_idinstead oftheme– This is the most common mistake - Using
allow_liveinstead ofallow-live– Hyphens vs underscores matter - Forgetting to use
--environmentflag – If you use a custom environment name (notdefault), you must specify it - Not reading the official docs – Community examples can be misleading
- Assuming the config works for live themes – You need
allow-live = trueto work on live themes
The Correct Configuration Template
Here’s a template you can use for your own projects:
# Shopify Theme Configuration
# Store your store URL and theme ID here to avoid typing them every time[environments.default]
store = “your-store.myshopify.com” theme = “your-theme-id” allow-live = true # Required if working on a live theme # Optional: Add more environments for different contexts # [environments.staging] # store = “staging-store.myshopify.com” # theme = “staging-theme-id”
Conclusion
What started as a simple configuration task turned into a valuable lesson in the importance of:
- Reading official documentation
- Understanding CLI flag naming conventions
- Systematic troubleshooting
- Not assuming community examples are always correct
The Shopify CLI’s environment system is actually quite powerful once you understand how it works. The key is using the correct flag names and format as specified in the official documentation.
Moral of the story: When in doubt, RTFM (Read The Fine Manual) – or in this case, the official Shopify CLI documentation.
Have you encountered similar configuration mysteries? Share your experiences and solutions in the comments below!