Theme development with the CLI

Pull a theme to your machine, edit Liquid templates in your own editor, and sync every save to an isolated draft.

Website

Quick answers

6 questions · click to open

Can I break the live site while I work?

No. Everything you do goes to a draft that’s completely isolated from the live site. Nothing changes for visitors until an admin clicks Publish, and discarding a draft reverts the lot.

Do I need to run cobber push?

Only if you edited files while the dev server wasn’t running. With cobber dev going, every save is already synced — push exists for the changes you made offline.

What do I need before I start?

Node.js 20 or later, an editor, and an admin account with the websites.develop permission on the organisation.

Where do colours and fonts live?

In the dashboard, not in the template files. Theme configuration — primary colour, fonts, custom CSS — is edited under Settings → Themes → Editor, and templates read it through CSS variables.

Can I work on more than one organisation?

Yes. Log in to as many as you like. The subdomain is saved into each theme folder’s manifest, so dev and push always act on the right org no matter which one is your default.

My preview URL stopped working.

Preview tokens are valid for 24 hours. Stop and restart cobber dev to get a fresh one.

Cobber themes control the look and feel of an organisation’s public website. Each theme contains content templates (Liquid HTML files) organised into categories, plus configuration (colours, fonts, custom CSS) managed in the dashboard.

The Cobber CLI lets you pull a theme to disk, edit templates in VS Code or any editor, and sync changes to a draft in real time. The draft is isolated from the live site — nothing goes live until an admin clicks Publish.

How it works

cobber pull — download a draft copy of the theme to your machine
Run cobber dev to start the syncer
Edit .liquid files locally — the CLI syncs each save to the server
Preview your changes instantly in the browser
When you’re happy, review the diff in the browser and click Publish

What you need first

Prerequisites
Requirement	Details
Node.js	Version 20 or later
Dashboard access	An admin account on the organisation with the `websites.develop` permission
Code editor	Any editor — VS Code, Sublime, Cursor, etc. Install a Liquid syntax extension for highlighting.

Quick start

# 1. Install
npm install -g @cobberhq/cli

# 2. Authenticate
cobber login patrioticpretzels

# 3. Pull a theme
cobber pull

# 4. Start developing
cd patrioticpretzels-themes/standard
cobber dev

# 5. Edit .liquid files in your editor — changes sync live

# 6. When done, push any offline edits
cobber push

# 7. Review and publish in the dashboard

Check you’re on the latest CLI by comparing cobber --version against the version on npm.

Authenticating

cobber login <subdomain>

Replace <subdomain> with the organisation’s subdomain (for example cobber login patrioticpretzels). A browser window opens where you log in and approve the device code. The CLI receives a long-lived access token, stored at ~/.cobber/config.json. You only need to do this once per organisation per machine.

Working with several organisations. Authenticate with as many as you like — credentials are stored per-subdomain, and the org you logged into most recently becomes the default that cobber pull uses. When you pull a theme the subdomain is saved in the manifest, so cobber dev and cobber push always use the right org for that folder regardless of which is default. Run cobber orgs to see which orgs you’re logged into and which is default (marked with *). Every command prints the org it’s acting on, so you can catch a wrong-org pull before it happens.

Pulling a theme

# Interactive — prompts you to pick a theme
cobber pull

# Pull a specific theme by name or slug
cobber pull standard

# Pull every theme at once
cobber pull --all

What you get on disk

Directory structure
Directory	Purpose
`page_layouts/`	One template per page type (home, donation, membership, contact, volunteer, petition, signup, about). Each file controls the HTML for that page type.
`site_layouts/`	The site-wide layout wrapper. Typically one file (`layout.liquid`) that includes the `<head>`, navigation, footer, and a `{{ content }}` placeholder where page content is injected.
`snippets/`	Reusable HTML fragments. Include them in other templates with `{% snippet "name" %}`.
`widget_partials/`	Templates for embeddable widgets and their success pages.
`.cobber/manifest.json`	Internal metadata — draft ID, file checksums, API endpoint. Don’t edit this file.

Each .liquid file maps 1:1 to a content template on the server. The filename (minus the extension) is the template key.

The development loop

cd <subdomain>-themes/<theme-slug>
cobber dev

This starts a file watcher and opens a preview URL in your browser. Every time you save a .liquid file the CLI detects the change, pushes the updated content to the draft, and the preview tab reloads to show it.

Keep the terminal and browser side by side — edits appear in under a second.

Pushing offline edits

If you used cobber dev, your changes are already on the server: every save was synced live, and you don’t need to push. cobber push is only for files you edited while the dev server wasn’t running.

cobber push

This compares local files against the manifest checksums and uploads any that changed. It also detects new and deleted files. After pushing, the CLI prints a link to the draft review page, which shows a side-by-side diff of every changed template so an admin can see exactly what changed before publishing.

Publishing

Publishing merges the draft back into the published theme, and is done by an admin in the dashboard:

Open the theme

Go to Settings → Themes in the organisation dashboard, click the theme, then View Draft.

The theme list, with a draft waiting to be reviewed.
Review the diff

Check each changed template side by side.
Publish

Click Publish to make the changes live. The draft is discarded afterwards — run cobber pull again to start a new cycle.

Safe by design. The draft is completely isolated. You can experiment freely — nothing affects the live site until Publish is clicked, and discarding a draft reverts all changes.

Gotchas

Worth knowing
Thing	Detail
Colours and fonts live in the dashboard	Theme configuration (primary colour, fonts, custom CSS) is not stored in template files. Edit it under Settings → Themes → Editor. Templates access it via CSS variables.
Don’t edit manifest.json	`.cobber/manifest.json` tracks the draft ID and file checksums. Editing it can cause sync issues. If things get out of sync, delete the theme directory and `cobber pull` again.
Multiple themes	An organisation can have several themes. Individual pages can be assigned to different themes, or the whole site can use one active theme. `cobber pull --all` pulls every theme at once.

The full list of variables, tags and filters available inside a template is in the Liquid reference.