[Bug]: Shopify CLI shouldn't read all TOML files in the project and "guess" they are all applicable to current app

[vfonic]

Please confirm that you have:

• Searched existing issues to see if your issue is a duplicate. (If you’ve found a duplicate issue, feel free to add additional information in a comment on it.)
• Reproduced the issue in the latest CLI version.

In which of these areas are you experiencing a problem?

App, Extension

Expected behavior

The app starts.

Actual behavior

You can only have one web with the backend role in your app
You can only have one web with the frontend role in your app

I'm using git workspaces for doing CLI AI agent coding across multiple workspaces.
Shopify CLI is preventing me from doing this because Shopify CLI does a lot of magic that is hidden from the end user/developer/me.
This has been an issue for me for years now.

Would it be possible for Shopify CLI to stop:

1. Stop saving config preferences in a hidden place (.shopify directory is not the only place as copying that directory over doesn't resolve the issue)
2. Stop assuming anything for end user
3. Stop trying to be the main tool needed to start: web server, backend, frontend, database, docker, virtual machine, remote desktop (see where I'm going?)
4. Stop creating free Cloudflare tunnel
5. Stop not respecting the command line arguments (config file, tunnel, etc.)

Shopify CLI (shopify app dev or shopify theme dev) should start file watcher for extension compilation and theme assets sync. Nothing else. Ever.

Would it be possible? Please.
It's really exhausting trying to debug Shopify CLI and other Shopify related issues which are completely unrelated to the actual implementation of my app code.

Here are few issue I'm facing ever. day.:

1. Required App Bridge upgrade to newer version
2. New Polaris upgrade which is completely incompatible of the last version
3. App migration from Partner Dashboard to Dev Dashboard (now everything is in two places, what a mess...)
4. Unknown app permissions, incomplete documentation
5. Unmaintained app templates (I'm using Ruby on Rails, that's enough to say. Here's a motivational comment from Shopify staff: Rails 8, Hotwire, Stimulus, no react shopify-app-template-ruby#122 (comment))

Please, just do less. Don't try to build everything CLI tool. It's not going to work.
Instead of adding new features, can you please fix the open issues first?

Thank you!

Verbose output

Verbose output

Would be great to have a more verbose output than the simple message above:

You can only have one web with the backend role in your app

Reproduction steps

When using git workspaces, Shopify CLI "forgets" its config because it's hidden from user (developer). Even after copying over the .shopify directory to the new git workspace, the error still persists.

As of now I cannot start shopify app dev in main git repo. Basically I cannot start shopify app dev anywhere anymore.

Operating System

macOS

Shopify CLI version (shopify --version)

3.84.1

Shell

oh my zsh

Node version (run node -v if you're not sure)

v22.12.0

What language and version are you using in your application?

ruby 3.4.4 (2025-05-14 revision a38531fd3f) +PRISM [arm64-darwin24]

[vfonic]

Why is Shopify CLI reading:

2025-10-01T21:25:32.596Z: Reading the content of file at shopify.app.production.toml...
2025-10-01T21:25:32.596Z: Reading the content of file at shopify.app.staging.toml...

When started with this command: shopify app dev -c shopify.app.local.toml --verbose

[vfonic]

BTW the git workspaces are within the same git root directory, but are gitignored:

/features

This is what causes the issue. Shopify CLI recursively searches for all TOML files, reads them all, finds several "backend" and "frontend" roles and errors out.

[isaacroldan]

Hi @vfonic, sorry your are facing this issues and thank you for taking the time to report them, i'll try to help:

Stop saving config preferences in a hidden place (.shopify directory is not the only place as copying that directory over doesn't resolve the issue)

We are slowly moving stuff into .shopify as the main place to store "hidden" stuff. But the main thing that's not there is: session tokens and caches (like, what was the last toml that you used).

Stop assuming anything for end user

To be able to run a proper dev experience, we need to assume certain things. Do you have specific examples where this is getting in the way?

Stop trying to be the main tool needed to start: web server, backend, frontend, database, docker, virtual machine, remote desktop (see where I'm going?)

The CLI will try to start your app, but that's always optional. You can just run it yourself and tell the CLI in which port it is running. (in your web.toml just specify a port and leave the dev command empty or with a no-op)

Stop creating free Cloudflare tunnel

This is also optional, you can use --use-localhost to avoid tunnels or --tunnel-url to bring your own tunnel solution.

Stop not respecting the command line arguments (config file, tunnel, etc.)

Where is the CLI not respecting command line arguments? When you specify a toml, that's what the CLI is going to use. It might read other tomls to understands what's available, but only the selected one is used.

Shopify CLI recursively searches for all TOML files, reads them all, finds several "backend" and "frontend" roles and errors out.

This is not exactly the case. The CLI will only use the selected app toml, even if there are more. But UNLESS you specify otherwise, it will load all web toml files available (because you can have multiple).
If you want to use just specific ones, you can tell the CLI using web_directories in your app toml (doc)

Hope this help, if you have more specific pain points or something is still not clear, please let me know!

Thank you again for your report

[vfonic]

Hi @vfonic, sorry your are facing this issues and thank you for taking the time to report them, i'll try to help:

Stop saving config preferences in a hidden place (.shopify directory is not the only place as copying that directory over doesn't resolve the issue)

We are slowly moving stuff into .shopify as the main place to store "hidden" stuff. But the main thing that's not there is: session tokens and caches (like, what was the last toml that you used).

Session tokens, makes total sense to me.

But why do you cache which TOML was last used?
This can cause issue because it's not all that obvious which "settings" were last used.
For example, I had an issue where Shopify CLI cached the "last theme ID used" (or store, can't really remember, it's one of numerous issues I have with Shopify CLI). It was showing me an error "theme.liquid or settings_data.json not found". Which had me waste some time to figure out that I was trying to use a theme with an ID from one store, in another store. This all happened even though I didn't provide theme ID or store, but that info was cached.
Not to mention that I could have mistakenly deployed (shopify theme deploy) one store's/client's theme to a different store/client because the CLI had it cached.
This is a security and privacy issue. The theme files, although unlikely and not recommended, could include some business sensitive information in Liquid files comments, or whatever... A client could see that I also work for another client, and their political views don't align, so they fire me. I'm making stuff up, but there's a slight chance of this happening and I think it shouldn't be ignored.
I'd highly recommend for this functionality to be removed.
Or, at least for shopify.app.toml, a better default could be to default to ./shopify.app.toml in project root, instead of "last used" (which is unknown and changes depending on the past Shopify CLI command usages).

Stop assuming anything for end user

To be able to run a proper dev experience, we need to assume certain things. Do you have specific examples where this is getting in the way?

I've given the above example of working across multiple clients/stores/themes/apps/extensions.
Shopify CLI is unpredictable.

What I try to do to make it behave in a predictable way is to always provide all of the arguments. This doesn't always work because I get errors like: --tunner-url is not recognized argument for this command or similar. This is terrible from my point of view as a user/developer of the tool.

Stop trying to be the main tool needed to start: web server, backend, frontend, database, docker, virtual machine, remote desktop (see where I'm going?)

The CLI will try to start your app, but that's always optional. You can just run it yourself and tell the CLI in which port it is running. (in your web.toml just specify a port and leave the dev command empty or with a no-op)

I already tried that and at various times it works, at other times it doesn't. Just tried it and now it works. I have no idea why it works when it works and why it doesn't when it doesn't. Ideally, the exact same code on two different machines should install and run in the same predictable way. Today, this is not possible to achieve with Shopify CLI.

I have so far reported 28 issues to this repo:
https://github.com/Shopify/cli/issues?q=is%3Aissue%20author%3Avfonic
It's exhausting and time-consuming to keep reporting these issues.
Ain't nobody got time fo' that! :)

Stop creating free Cloudflare tunnel

This is also optional, you can use --use-localhost to avoid tunnels or --tunnel-url to bring your own tunnel solution.

I tried and at various times it works at other times/commands it doesn't. Can't remember now about a particular example, but I'll open an issue no. 29 if I remember.

Stop not respecting the command line arguments (config file, tunnel, etc.)

Where is the CLI not respecting command line arguments? When you specify a toml, that's what the CLI is going to use. It might read other tomls to understands what's available, but only the selected one is used.

Why would it read other TOMLs? What does it need to understand what's available?
It doesn't sound strange to you to even say/write that?
"Here's the config file to use."
"Sure, but let me first read ALL the other config files that you didn't tell me to."
🤷‍♂️

Shopify CLI recursively searches for all TOML files, reads them all, finds several "backend" and "frontend" roles and errors out.

This is not exactly the case. The CLI will only use the selected app toml, even if there are more. But UNLESS you specify otherwise, it will load all web toml files available (because you can have multiple). If you want to use just specific ones, you can tell the CLI using web_directories in your app toml (doc)

Thanks! I didn't know about this config option! I do have a shopify.web.toml in the root of my project, but I think I can move it someplace else to mitigate this.

Hope this help, if you have more specific pain points or something is still not clear, please let me know!

Thank you again for your report

Thank you, sir! 🙏

[vfonic]

I just realized how my .web.toml files look like and it made me giggle. Thought I would share:

roles = ["backend"]
webhooks_path = "api/webhooks/app_uninstalled"

[commands]
dev = ""
build = ""

roles = ["frontend"]

[commands]
dev = ""
build = ""

At the moment, I'm hesitant to make changes because I want to focus on productive work rather than troubleshooting Shopify CLI.
It’s interesting how (and why) Shopify CLI is handling process running — definitely a unique approach!

[vfonic]

@isaacroldan your suggestion to use web_directories argument didn't work, as described in my issue no. 29:
[Bug]: shopify app deploy doesn't recognize web_directories argument #6518

This is a recurring theme: Shopify CLI accepts different arguments, depending on the command used. I understand why this might make sense, when those arguments don't make sense. But in other cases, it prevents me from writing a shell script/alias/function that always passes the same (all) arguments so that I can have consistent behavior, independent of Shopify CLI's internal cache (the infamous last command used, last TOML used, last store used, last theme ID used, etc.)

[isaacroldan]

Hey @vfonic, sorry haven't had time to reply to your previous message. Just a quick note that web_directories is not a command flag, is an optional property inside the app.toml file.
In your case if the web.toml is inside a folder called frontend, then you should add

web_directories = ["frontend"]

About your web.toml contents, does the CLI serves your app properly when running dev? or do you have a static App URL for dev and rely on that?

[vfonic]

Ah, I was wondering how to correctly specify web_directories as an array argument to the CLI. Got it. I'll add it to *.app.toml.

My app seems to start properly and I can load it as embedded app inside Shopify admin (the most important test).

I'm running it via process management tool, either Foreman or Overmind:
https://github.com/ddollar/foreman
https://evilmartians.com/opensource/overmind

It uses Procfile.dev, similarly how Heroku uses Procfile for various processes/services.

Here'y my Procfile.dev that starts the app:

web: rails server
cloudflare: cloudflared tunnel run my-domains-subdomain-for-tunnel
css: SHOPIFY_API_KEY=xxxxxxx yarn build && yarn build:css --watch
vite: cd frontend && yarn dev
shopify_cli: shopify app dev -s xxxxxxx -c shopify.app.local.toml --use-localhost

When I need to interact with shopify_cli ((d)ev status, (p)review, (q)uit, (s)tore info, etc.), I can connect to that process via overmind connect shopify_cli

I've since deleted shopify.web.toml from project root and updated frontend/shopify.web.toml:

roles = ["frontend", "backend"]
webhooks_path = "api/webhooks/app_uninstalled"

[commands]
dev = ""
build = ""

(I have no idea what webhooks_path = "api/webhooks/app_uninstalled" is used for. It was there from the unmaintained Shopify Rails app template: https://github.com/Shopify/shopify-app-template-ruby)

[isaacroldan]

The webhooks_path is called locally when you change the dev store you are using to test, because your local app might need to do some cleanup. In theory all templates are prepared to handle this route (but you can also change/delete that)

To better understand your workflow, since you are using both tunnel and localhost in that Procfile.dev and an empty web.toml: what value do you have in your app.toml for automatically_update_urls_on_dev and the app url?
Is it automatically_update_urls_on_dev = false and app_url = <tunnel_url>?

[vfonic]

The webhooks_path is called locally when you change the dev store you are using to test, because your local app might need to do some cleanup. In theory all templates are prepared to handle this route (but you can also change/delete that)

To better understand your workflow, since you are using both tunnel and localhost in that Procfile.dev and an empty web.toml: what value do you have in your app.toml for automatically_update_urls_on_dev and the app url? Is it automatically_update_urls_on_dev = false and app_url = <tunnel_url>?

That's correct.

application_url = "https://my-permanent-tunnel-url.example.com/"

# ...

[build]
automatically_update_urls_on_dev = false
# ...

Just to confirm, I can start the shopify app dev server successfully and have the app connected with the development store, load it as an embedded app, etc.
Thank you for all the help! It helped me get unstuck. I really appreciate it! 🙏

---

Perhaps we can make this issue more actionable and possible to close if we reduce it to: Provide clearer error message when multiple frontend and/or backend roles are found across multiple shopify.web.toml files.

The error message could show path to all shopify.web.toml files where "frontend" and/or "backend" roles were found.

This would make it much easier for the end user to resolve the issue.
Feel free to change the issue title and/or close the issue when you see fit.
Thanks again!

[isaacroldan]

That's reasonable, fix to the error message here: #6529