Install the Discourse Theme CLI console app to help you build themes

If you go to /admin/api/keys, does the API key you’re using show a user avatar or “all users”? This detail is often missed:

You can clear the error and start over with: discourse_theme watch your-dir-name --reset


Thank you! I really appreciate it. My API is a single user, however, I must have been a key off when posting the actual API code.

1 Like

i install discourse_theme via gem on my mac my terminal use zsh and so it’s seems that zsh don’t recognize zsh :
Capture d’écran 2021-03-11 à 13.36.34 and i don’t know how to resolve this issue

1 Like

Can we just mount our theme folder to the local development environment straightforward without this tool? Or connect to a local Discourse instance instead of the online theme creator.

No, Discourse themes are stored in the database, so there’s no way to “mount” them into a running version of the application.

Yeah you can do this - just specify localhost:3000 (or whatever address/port you are using for your development instance)


Any official support for Beginners Guide to Install Discourse for Development using Docker?

Now that Docker and WSL2 are so stable and fast, this is really my preferred way of running a local dev instance. It would be great to add support for this gem so we can use it to quickly iterate themes and theme components.

Perhaps I’m missing an obvious trick?


Would it be possible to add a flag that sets the watched theme as the default for the Discourse instance? not at all a priority because it’s very particular to the workflow of switching themes a lot throughout the day, but it would be nice if I could avoid the manual steps of going to admin/customize each time.


I think we can definitely make that work for full themes. How would it work for components… we just skip the logic?


I guess maybe we could apply the component to a blank parent theme and set that as the default (GitHub - discourse/discourse-blank-theme)?

Skipping it would be fine too, full themes are the most common case for me anyway.

1 Like

I’d love to see that too!

Though when there’s an automatic logic, it could help to have some kind of visual indicator that it’s currently in effect on a site. Like replacing the favicon with an eye icon?

Frame 4

1 Like

We’ve just completed building a dev environment with the discourse theme cli connecting to a local (docker) instance of Discourse. We found the instruction wording here slightly misleading.

You need to use a per user key not a global one, go to admin user and generate the key there

This means selecting a “User Level” of Single User not All Users. You must also check “Global Key”, otherwise you will get a 403.

The wording of “global” here can be confusing, as that word only appears on the page when referring to the permissions for the api key, being a “Global Key”, which you in fact have to enable.

My recommendation would be to clarify the instructions to say

  • :exclamation: Select a “User Level” of Single User when generating the key, not All Users.
  • :exclamation: Make sure to check Global Key or you will receive 403 forbidden errors.

The OP is a wiki, so you can make those changes. They sound right to me That language is confusing, and I bet it aas written before there was scoping for api keys.


Do I need to have a discourse developing on local box or I can see the changes on my live production site?

1 Like

You only need to run the discourse_theme CLI on your local box. Discourse itself can be running anywhere, so yes you can use it to connect to your live production site :+1:. We also provide a free sandbox environment at


Does anyone else get timeouts regularly when uploading and sometimes during the initial watch call? It kills the development experience and sometimes happens constantly in a row.

Ruby version: ruby 2.6.8p205 (2021-07-07 revision 67951) [universal.arm64e-darwin21]
But it also happens with the same frequency for my associate running an ArchLinux based distro, which makes me think it’s not a problem with my setup…

I’ve considered rewriting the tool in Node.js or Go since I don’t know

My Discourse instance is officially hosted using the Business plan. We haven’t launched yet and there’s no server side customizations, so there’s barely any activity that could result in slow performance. I guess the CLI is not very tolerant of failures? Maybe there should be some retries or a larger number for timeout?


I haven’t seen it before, though I haven’t often done it with a hosted site. But I’m pretty sure that there are a bunch of people who do.

I’d think it a local networking issue, except

Well, that is odd.

That sounds like a tremendous waste of time unless you would find it really, really fun.

Are you both using the same corporate VPN by chance? That’s all I can think of that might explain it.


Hi thanks for the reply! I’m almost sure now something is up with the SSL certificate:

It’s weird because it eventually is able to handshake successfully after a long random time, but I guess the CLI doesn’t cache it for long like browsers do and with the low timeout and no retries, the exceptions happen very frequently. I just don’t know how to fix it… I guess I need to contact Discourse Support? I don’t have access to anything related from the Admin Dashboard, and I assume I need to SSH into the server to fix this, which isn’t possible with I guess.


:wave: Hi Matheus,

On our hosting, we take care of the certificate using LetsEncrypt. I haven’t heard any other reports of issues like this, so I think it’s most likely to be something unusual on your side.

You mentioned that your coworker also has the same issue? Do you both use the same network, and if so is there some kind of proxy in place for web traffic?

What command did you use to generate the screenshot in your post? Would you mind sharing the full output as text? (If you prefer to keep it private, a PM is fine)


Love this. Thanks very much for doing it!

I want to let you know that several of the previews don’t work, however.

/dr, still trying to figure this all out

You’ll need to supply a good deal more information for your reporting whatever problem you’re having to be helpful.

1 Like