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

The discourse Discourse Theme CLI is a ruby gem that allows you to use your editor of choice when developing Discourse themes and theme components. As you save files the CLI will update the remote theme or component and changes to it will appear live!


To play with it, make sure you have Ruby 2.2 or up installed.

If you are on Windows, you have 2 options:

Option 1: Windows Subsystem for Linux.

Windows 10 has access to a full Linux environment, you can use it to install ruby simply with sudo apt-get install ruby, this will give you Ruby 2.3.

Options 2: Older Windows

Older versions of Windows have no access to WSL, you can easily install Ruby with Ruby Installer, go for the recommended version and default settings for the install.


Mac OS version 10.13.3 ship with Ruby 2.3 out of the box, nothing special is needed. If you are running an earlier version of Mac OS consider using rvm, rbenv or homebrew to install a recent ruby.

Once Ruby 2.2 or later is running, open a terminal or command shell and run:

gem install discourse_theme

Once installed, to learn more about it:



The CLI provides 3 main functions:

discourse_theme new

You can use it to quickly create a new theme with discourse_theme new YOUR_DIR_NAME

discourse_theme watch

You can use it to monitor a theme and synchronize with a discourse site (with live refresh) using discourse_theme watch YOUR_DIR_NAME

What this means is that you can use your own editor to edit you theme and site will magically :unicorn: update with the changes!

discourse_theme download

You can download an existing theme from Discourse using discourse_theme download YOUR_DIR_NAME. You will then be given the option to start “watching” straight away!


You will need to generate an API Key. Go to the admin area and generate a key there.

  • :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.

Credentials are (optionally) stored at ~/.discourse_theme. API keys are stored per-site, and the URL/theme_id for each directory is also tracked. If you ever need to change your settings, just add --reset to any command and you will be prompted for all values again.


“This tool is truly a GEM!” @awole20
“This is very very good.” @awesomerobot
“It’s working :slight_smile: And it’s pretty dosh garn cool. Nice!” @angus
“OMG. It’s unbelievable.” @pfaffman

Theme Creator, create and show themes without installing Discourse!
CSS Theme Contest (with Prizes!)
Customizing handlebars templates
Setting up a solid workflow for custom theme development
Structure of themes and theme components
Theme Developer Quick Reference Guide
:gear: Add settings to your Discourse theme
Get started with Theme Creator and the Theme CLI
Remote themes not in database
Split up theme Javascript into multiple files
Beginner's guide to developing Discourse Themes
Designer's Guide to getting started with themes in Discourse
Import site theme via console
How are theme setting fields created?
Automate Discourse Theme Installation
Edit CSS/HTML editor cursor offset makes it unusable due to CSS font override
Discourse Theme CLI is the bomb
Discourse 2.0.0.beta5 Release Notes
How difficult would it be to make the Discourse UI more like Flarum?
Discourse-webpack: A boilerplate for developing JS-heavy Discourse components
Import Error: about.json does not exist, or is invalid
Reuse Discourse Hamburger Functionality
Themes - Add a description field
Create and share a font theme component
How to create a theme (if I am a pure end user)
Is it possible to use a local plugin directory with a docker install?
How to overrule a color variable for one theme only?
Beginner's guide to developing Discourse Themes
Can't customize text on custom button in template override using UI
Is it possible to use theme component from local folder (as plugin) - for local development?
Restrict editing of remote themes
When exporting a theme, I get a broken archive
Install Discourse for development using Docker
Developing Plugins Faster by separating the frontend into a theme component

Edits are welcome here, and on the readme, probably need a few to explain how to generate an api key.

1 Like

Whoa – this sounds amazing! Having come from figwheel, I can say that live reloading is a phenomenal development experience. Can’t wait to try it out!


Doing live JS updates is going to be a major challenge, for now this only does CSS, if you want to get the JS changes you need to refresh the browser.

I am open to improving the flow here a bit and issuing a browser refresh or something but want to focus on CSS hot reload first.


OK I just did a new release @angus and @awesomerobot it resolves the 400 error!


  • Cleans up config so we only have a single config file in ~ which handles multiple themes
  • Added special handling for people who forget to enter “http://” (which I need to refine)
  • Editing HTML was triggering a broken CSS update

Let me know how you go.

Also… I am cleaning up this topic as I go… so super sorry about my post deletions, just trying to keep stuff not confusing

To update to latest simply run gem update discourse_theme


This is a big one for @awesomerobot and @theme_authors

In the past when you preview, as soon as you “refreshed” the page you would lose the preview, this made preview pretty useless for cases where you are trying to amend HTML structure or adding JS.

Not any more.


Adding to the list of posts I am probably going to delete soon… something is SUPER wonky with color schemes and I think @lll mentioned this in the past, on sync we are not removing old schemes and they are also not really updating right in the preview. Working on it now…


This may not be the case any more, but previously there were two things that happened.

1- if you change one of the colors in a color scheme locally, the changes are not reflected until you change to another scheme and then move back the original color scheme.

2- if you change a color in a color scheme in a repo on Github, updating the theme doesn’t not cause the color scheme to be updated. You have to delete / re-install the theme to see the changes.


OK another post for tomorrows big cleanup… Editing color_schemes in about.json now works as you would expect it… super :tophat: off for living with the horrible bug for so long.


@lll do you have a verdict on the theme watcher thingamijig?

1 Like

Based on what I read I think it’s amazing and I can’t wait to play around with it :ok_hand:

If I am being completely honest though I tried installing the gem and was not successful mainly to my being a bit dense when it comes to anything back-end :grin:

Once I figure it out I’ll be sure to let you know :sunflower:



Working great for me now. This is very very good.


@lll / @theme_authors I just updated the OP here with instructions for Windows. Should work on pretty much any version of Windows. I tested on mine and except for a minor issue with it using polling instead of a file system watcher it works fine.

I am not including wdm cause it is buggy


This tool is truly a GEM! :troll: I tried it out last night, and I don’t have any complaints - it worked flawlessly over my css-only themes. Makes me honestly wish to polish up some of my themes some more. :slight_smile:

RE: Auto refresh - I’m good without it. I’m always a little ambivalent about auto refresh file watchers because of how much state you may automatically lose in the refresh, and may come with its own set of annoying sync issues.

Nitpick – are you planning on expanding and utilizing the ${theme}/.discourse-site file referenced in the gitignore, or was that just a placeholder before ~/.discourse_theme became the canonical config file?


That :slight_smile: yeah we got to remove it.


Thank you so much for update / details added @sam :grin:

I’m all set now, I can create new themes with discourse_theme new and it’s working flawlessly :heart_eyes: I really appreciate not having to create all the theme files / folders every-time so this is really a major plus so far.

I am getting the same error that angus got where upon trying to make a site watch a theme I get a 404.

I remember angus did something different and then it started working but can’t find that post now.

1- I run discourse_theme new c:\users\username\desktop\themes\foobar
2- a theme is created in that directory
3- I run discourse_theme watch c:\users\username\desktop\themes\foobar
4- it asks for a sitename to which I provide
5- it asks for an api key which I get from here:

I then get this error:

error importing theme status: 404 the requested url or resource could not be found

I checked:

  • the domain name
  • the theme folder
  • the api key

And they are all correct.

extra information regarding installation - not relevant to the issue above

I’m on Win 7

1- I installed ruby from the linked site here:
2- after running the installer it wanted to install msys2
3- After several attempts it just would not work and cut off in the middle of the download (issue on my end)
4- so I had to go here: and download it
5- I ran the installer for msys2
6- and then uninstalled / reinstalled ruby
7- everything works except for the issue above

I also had to install wdm but I forgot where exactly in the timeline above.

1 Like

I remember something was mentioned where they needed to use http vs. https? I can’t remember the full context though…

I still haven’t gotten around to trying this, but I most certainly intend to!


Ooh :astonished: that is the api key issue I need to fix, you need to use a per user key not a global one, go to admin user and generate the key there, you are going to need to delete your config file as well


Since this is going to be cleaned up anyways, I might as well let you know how I felt when I got it to work:

I was literally like…

Well done, this is incredibly helpful and well-thought through. Thank you so much for making this possible!

I will play around a little bit and be back with a proper reply. :grin:


After a couple of days of playing around…

Here’s what I have @sam

0 complaints and tons of kudos :star_struck:. This really takes care of all the small things that get in the way. I really like having the ability to generate new themes literally within seconds and just get to work, not to mention the ability to work on theme branches! This just works!

Thank you :grin::ok_hand:


Whoa, that was much easier than I expected it would be to set up and it really is magical! :unicorn: I’m a little late to the party, but it all works flawlessly with the help of all the information that’s been posted in here. Thanks for working on this @sam!