Masthead CLI

The Masthead CLI provides the tools needed to create, preview, validate and package themes locally.

It runs the same rendering pipeline as the hosted Masthead platform, allowing you to develop themes without running the complete Masthead application or uploading every change.

Installation

Homebrew

The recommended installation method on macOS and Linux is Homebrew.

brew install dijkstrasoftware/tap/masthead

To install the latest development version directly from the main branch:

brew install --HEAD dijkstrasoftware/tap/masthead

From source

Building the CLI from source requires Elixir.

git clone https://github.com/dijkstrasoftware/masthead-cli
cd masthead-cli

mix deps.get
mix escript.build

This produces a masthead executable in the project directory.

You can either copy or symlink it somewhere on your PATH:

ln -s "$PWD/masthead" ~/.local/bin/masthead

Alternatively, install it through Mix:

mix escript.install

Make sure the Mix escript directory is included in your PATH.

Creating your first theme

Use the new command to scaffold a complete Masthead theme.

masthead new my-theme
cd my-theme

The command creates a new directory containing a valid starter theme, including templates, styling, example configuration and preview content.

The directory name is also used to generate the initial theme name and slug. For example:

masthead new "My Theme"

creates a theme with the slug my-theme.

The command requires Git and will not overwrite an existing non-empty directory.

Once the theme has been created, start the local preview server:

masthead preview

The theme will be available at:

http://localhost:4010

Previewing a theme

Run the preview server from inside a theme directory:

masthead preview

The CLI opens a local editor containing the rendered theme and a settings sidebar.

The preview reproduces Masthead’s production rendering behavior, including:

• Liquid templates
• Theme tokens
• Page metadata
• Markdown rendering
• HTML sanitization
• Theme pages
• Custom Liquid filters
• Site routes
• Post and page filtering

Changes to Liquid templates, theme.css and manifest.json automatically refresh the preview.

Choosing a port

The preview server uses port 4010 by default.

You can provide a different port:

masthead preview --port 4020

Previewing another directory

Use --dir to preview a theme outside the current directory:

masthead preview --dir ../another-theme

Previewing without the editor

To render the theme without the settings sidebar:

masthead preview --no-editor

This is useful when you want to inspect the theme output without the small script used to synchronize the preview frame with the editor.

The preview editor

The preview editor contains three sections.

Page

The page selector allows you to switch between the pages and posts defined in your preview content.

Navigation inside the rendered theme also updates the editor automatically.

Theme tokens

The theme token section contains every token declared in manifest.json.

Tokens are grouped using their configured category and rendered with the appropriate editor control.

Page settings

Page settings contain the configuration for the currently selected page.

Theme pages use the metadata declared in their JSON sidecar file:

templates/pages/home.liquid
templates/pages/home.json

Regular pages use the global metadata defined in manifest.json.

Changing a value re-renders the page on the server. This means conditional Liquid logic, loops and structured values behave the same way they do on the hosted platform.

Local preview settings

Values changed through the preview editor are stored in:

preview.local.json

For example:

{
  "tokens": {
    "accent": "#d9480f",
    "footer_links": [
      {
        "label": "Documentation",
        "url": "/docs"
      }
    ]
  },
  "pages": {
    "home": {
      "metadata": {
        "hero": {
          "heading": "Hello"
        }
      }
    }
  }
}

This file is only used by the local preview environment.

It is:

• Automatically added to .gitignore
• Excluded from packaged themes
• Layered on top of preview.json
• Removed when using the reset action in the editor

Use preview.json for preview content that should be shared with other theme developers. Use preview.local.json for temporary local changes.

Preview content

When no preview configuration is present, the CLI provides sample pages and posts automatically.

You can define your own preview content using a preview.json file in the theme directory.

{
  "site": {
    "name": "Acme",
    "title": "Acme — we make things",
    "description": "A short site description.",
    "slug": "acme",
    "homepage": "home"
  },
  "tokens": {
    "accent": "#d9480f"
  },
  "pages": [
    {
      "title": "Home",
      "slug": "home",
      "format": "theme",
      "template": "home"
    }
  ],
  "posts": [
    {
      "title": "Hello",
      "slug": "hello",
      "published_at": "2026-01-15",
      "tags": ["Writing"],
      "body": "A post body."
    }
  ]
}

The homepage value is the slug of the page that should be rendered at /.

If no homepage is configured, Masthead renders the theme’s index.liquid template.

Markdown preview files

Pages and posts can also be defined as individual Markdown files.

Place them inside:

preview/pages/
preview/posts/

Markdown files may include JSON frontmatter:

---
{
  "title": "About",
  "slug": "about",
  "format": "markdown",
  "metadata": {
    "layout": "wide"
  },
  "show_in_nav": true
}
---

## About us

Markdown body goes here.

Values that are not provided are inferred from the filename.

For example:

about.md

becomes a page with the slug about and title About.

Files inside the preview directories take precedence over the inline pages and posts arrays in preview.json.

Validating a theme

Use the validate command to check a theme without starting the preview server.

masthead validate

Validation checks:

• manifest.json
• Required templates
• Liquid syntax
• Theme page sidecar files
• Token and metadata declarations

Validation uses the same rules as theme uploads on the hosted Masthead platform.

Packaging a theme

Use the package command to create an installable theme archive.

masthead package

By default, the archive is written to your Desktop using the theme slug and version:

my-theme-1.0.0.zip

The theme is validated before packaging. Invalid themes are not packaged.

Only files used by Masthead are included:

manifest.json
theme.css
templates/
assets/

Development files are excluded, including:

preview.json
preview.local.json
README.md
.git/
.DS_Store
*.zip

Choosing an output location

Write the archive to a directory:

masthead package --out ~/Downloads

Write it to an exact path:

masthead package --out ./dist/theme.zip

The short form is also available:

masthead package -o ./dist/theme.zip

Bumping the version

The manifest version can be updated before packaging:

masthead package --bump patch
masthead package --bump minor
masthead package --bump major

Checking your environment

Use the doctor command to inspect your local Elixir and Erlang environment.

masthead doctor

The command reports installed versions and warns about known compatibility problems.

CLI reference

Command	Description
masthead new NAME	Create a new theme from the starter template.
masthead preview	Start the local theme preview and editor.
masthead validate	Validate the theme without running a server.
masthead package	Create an installable theme archive.
masthead doctor	Inspect the local Elixir and Erlang environment.
masthead help	Show the available commands and options.

Preview options

Option	Description
--port PORT	Run the preview server on another port.
--dir PATH	Preview a theme from another directory.
--no-editor	Render the theme without the settings editor.

Package options

Option	Description
--out PATH	Choose the output directory or archive path.
-o PATH	Short form of --out.
--bump patch	Increment the patch version before packaging.
--bump minor	Increment the minor version before packaging.
--bump major	Increment the major version before packaging.