MattersimpleDocs

CLI reference

The theme CLI is the npm package @mattersimple/theme; its command is mattersimple-theme. It uploads your theme to the firm, keeps a live preview in sync while you work, and publishes the theme when it's ready.

Installing

The CLI runs on Node.js 20.10 or newer. There are two ways to get it:

  • In each theme project (no global install). Every starter kit lists the CLI in its package.json, so npm install in the theme folder installs it into node_modules/. Run it there with npx mattersimple-theme … or the npm scripts. To start this way, download the kit from Website → Themes → Developer tools → Download starter kit (theme-starter-kit.zip, one my-theme folder inside), unzip it, and run npm install in the folder.
  • Globally. npm install --global @mattersimple/theme gives you mattersimple-theme in any folder, and mattersimple-theme init downloads and installs the starter kit for you. Quick start follows this path.

Check it works with npx mattersimple-theme --version.

Signing in

Terminal
mattersimple-theme login --host https://<platform address> --token rtk_…
mattersimple-theme logout

Create the token in Website → Themes → Developer tools → Developer access; that dialog shows the full login command. The login is saved in ~/.config/mattersimple/credentials.json, readable only by you. In CI, set MATTERSIMPLE_THEME_HOST and MATTERSIMPLE_THEME_TOKEN instead.

Commands

Command What it does
init [folder] [--name <name>] [--no-install] Download the starter kit into folder (default my-theme) and run npm install.
dev [--no-open] [--no-build] Build the CSS and keep rebuilding it, upload the project to your private development theme, open its preview, then push every saved change. The preview reloads after each push.
push [--name <name>] Upload the project as a new unpublished theme.
push --theme <id> [--skip-json] [--allow-live] Update a theme: sends only files that changed, and deletes files you removed.
pull --theme <id> [--only-json] [--path <folder>] Download a theme's files that differ from yours. --only-json fetches just the pages and settings, e.g. after the firm edited them in the theme editor.
package [--no-build] Build dist/<name>-<version>.zip to upload by hand.
check Have the platform validate the project, without installing it.
list List the firm's themes with their ids and roles.
open --theme <id> [--editor] Print the preview and editor links, and open one.
publish --theme <id> [--yes] Make a theme the live theme (asks first, unless --yes).

Every command takes --path <folder> to work on a folder other than the current one. push, check, package and dev run the project's build:css script first, unless --no-build.

Pages and settings when pushing

Templates, section groups and config/settings_data.json are the theme's content, which the firm may change in the theme editor. push --theme <id> only sends the documents you changed locally since the last push, so the firm's edits to the others are kept. Each document you send replaces the editor's version (the old one stays in the editor's history). On the live theme it becomes an unpublished draft.

  • --skip-json sends no documents at all.
  • To start from the firm's latest content, pull --theme <id> --only-json first.

The live theme

Pushing to the live theme changes the firm's site straight away, so push --theme <id> refuses it unless you add --allow-live. Prefer pushing to an unpublished copy and publishing that.

Development themes

dev keeps one private development theme per developer per firm. It isn't listed in the firm's theme library and can't be published; push to an unpublished theme for that. It's deleted after 7 days without a push.

Testing settings in the theme editor

The preview shows your theme with its saved settings. To try the settings themselves (the controls your settings_schema.json and section schemas create, adding and reordering sections and blocks, presets), open your development theme in the theme editor:

  1. Run npm run dev and open the Editor link it prints. npx mattersimple-theme open --theme <id> --editor opens it again later (npx mattersimple-theme list shows the id).
  2. Change settings and add sections and blocks: the editor re-renders them as you go, with request.design_mode true and the editor events firing.
  3. Keep editing your files. Each save is still pushed, but the editor doesn't reload by itself: refresh the editor page to see changed markup or new settings.

What you change in the editor is saved on the platform, in the development theme's templates/*.json, sections/*-group.json and config/settings_data.json, not in your project. So:

  • When you save one of those files locally, dev sends it and it replaces the editor's version (the old one stays in the editor's history).
  • Restarting npm run dev uploads the whole project again, which replaces all the development theme's pages and settings with your local files.
  • To keep what you set up in the editor (for example as your theme's defaults), run npx mattersimple-theme pull --theme <id> --only-json first.

To have someone at the firm try the settings, npm run push and send them the unpublished theme's editor link from Website → Themes.

npm scripts in the starter kit

Script Runs
npm run dev mattersimple-theme dev
npm run build:css / watch:css Tailwind: src/theme.css → assets/theme.css
npm run check build, then mattersimple-theme check
npm run push build, then mattersimple-theme push --unpublished
npm run package build, then mattersimple-theme package

Still need help?

Send a request to the Mattersimple team and we'll reply by email.

Sign in to contact support