Beginners' guide to using Theme Creator and Theme CLI to start building a Discourse theme

This topic will walk you through how to use the Theme CLI with our Theme Creator site to develop a theme and preview your changes on a live Discourse site.

  1. Sign up for an account here on Meta if you haven’t already

  2. Log in to Theme Creator

  3. Install the Theme CLI via the instructions here

  4. Create a new theme on Theme Creator by:

  5. Click advanced, then edit locally, and retrieve API key.

    Copy the API key that is generated.

  6. Go back to your command line and type discourse_theme download example-folder, where example-folder is where your theme will be stored locally. Follow the prompts.

    • Enter as the root URL of your Discourse site.

    • Enter your API key from the previous step when prompted.

    • Continue following the prompts and select the theme you created in step 4.

    • Enter yes when asked if you’d like to start watching your theme.


  7. Now your local theme folder is being watched for changes, which will be automatically uploaded to Theme Creator. You can open a preview of your theme by clicking preview in your theme’s settings on Theme Creator.

  8. To stop watching for changes, hit ctrl + c in your command line window. To start watching for changes again type discourse_theme watch example-theme.

:tada: You now have a local theme directory you can edit and see your changes live!

For an in-depth look at how themes are structured and what you can do, check out our Developer’s guide to Discourse Themes


Thanks for the tutorial. I followed it step by step but the cli does not seem to update the preview when I make changes to the local theme files; although the terminal logs the followings.

» Watching for changes in /Users/user/Desktop/discorse-theme...
» Fast updating common.scss
✔ Done! Watching for changes...
» Fast updating common.scss
✔ Done! Watching for changes...

For instance, I tried body{ background-color: blue;} in common/common.scss but no changes took place on the preview.

That being said, I can make this change from themes/example-theme/edit css/html/common/css

Not sure what i am missing.
Any feedback is appreciated

When you make changes via the site directly, do you see the changes you made locally in there? Are they not being uploaded at all?

Are you certain that the theme uploaded by the CLI is the active one? I’ve made the mistake of previewing the incorrect theme before.

If you stop and start watching the theme again, does that change anything?


Thank you for the fast reply.

It got working all of the sudden :slight_smile:


There seems to be an issue with the translations missing on your site? Do you have any other customizations enabled? Does it still look like this if you visit your site in safe-mode? How to use Discourse Safe Mode