The CLI treats your storefront as a directory you can edit, diff and commit.
1

Pull it down

Writes your templates and builder configuration into theme/.
2

Edit with live preview

Prints a preview link, then uploads each save as a draft. Refresh the link to see it. Nothing reaches a shopper.
3

Publish when you are ready

Promotes the draft to live.

​
What lands on disk

templates/ holds one file per page kind. online-store.json is your builder document: page layout and design tokens together, written indented so its diffs are readable in a pull request. .mercemur-state.json records the version of each resource as of your last pull. It is per checkout, so do not commit it. Add it to .gitignore:
If you lose it, run mercemur theme pull again. The CLI refuses to push without it rather than guessing, because guessing means overwriting somebody else’s work.

​
Draft and live are separate

Every command in this workflow writes to a draft. Shoppers see the published copy. Only publish moves one to the other. That split is deliberate, and it is why push and publish are two commands rather than one flag. A draft save is private to you and cheap to get wrong. A publish changes what every visitor to your store sees. Collapsing them would put both behind one line in your audit log and one entry in a retry policy.

​
Pushing safely

Before sending anything, see where you stand:
That compares your files against the server’s current draft, so it catches the case a dry run cannot: somebody else changed the store while you were working.
A dry run sends nothing and prints exactly what a real push would do, including whether each file updates something or creates it:
Every write carries the version you pulled. If somebody changed the same template in the dashboard while you were editing, the push refuses rather than overwriting them:
Retrying will not help, which is why the message says so. Pull into a clean directory, look at what changed, and re-apply.

​
Publishing

publish promotes the draft the server holds, not the files on your disk. Those are usually the same thing, and when they are not it refuses:
Without that check, editing a file and forgetting to push would publish the previous version and report success. Templates publish before the builder configuration, because the configuration refers to them. The other order would briefly leave a live layout pointing at markup shoppers cannot see yet.

​
Working with git

The two content files are meant for version control:
Branch, review and revert your storefront the way you do the rest of your code. To roll back, check out the older files and push them.
A git revert changes your files, not your store. Run mercemur theme push and then mercemur theme publish to make the rollback live.

​
Command reference

Downloads every template and the builder configuration, and records their versions.Overwrites local files. Commit or stash first if you have unpushed edits.
Uploads local files as a draft, then records the new versions so a second push needs no re-pull.Exits 4 if anything changed on the server since your pull.
Mints a preview link and pushes each save as a draft.--json is refused here rather than ignored. A watch session is a stream for a person; for scripted output run mercemur theme push --json in your own loop.Editors write a file several times per save, so changes are debounced into one upload. A failed upload prints and the session continues; press ctrl-c to stop.The preview link lasts 48 hours and renders your draft. Anyone holding the link can see it, so treat it as you would a shared document.
Makes the pushed draft live for shoppers.Refuses if your local files differ from the draft on the server, or if any version is unknown.
Compares your local files against the draft on the server. Reads only, so it is safe to run at any time.
This answers something push --dry-run cannot: whether the server moved since your pull. A dry run only knows what is on your disk.With --json it reports in_sync, so a pipeline can check whether the storefront matches the repository.
Lists past versions of the builder configuration, newest first.
One is recorded each time the configuration is published. Templates are not listed here, because they live in your own git history; the builder document keeps server-side revisions because the dashboard edits it too.Read a revision before restoring it. A list of ids and timestamps tells you when something changed, never what it changed to:
Copies a past revision back into the draft.Nothing changes for shoppers until you publish, so a restore is as reversible as any other edit until then. Afterwards run mercemur theme pull to bring the restored document down, then publish when you are happy with it.Like every other write, it presents the version you pulled and refuses if somebody changed the configuration in the dashboard meanwhile.

​
In CI

Check the exit code rather than parsing the message. 4 means somebody changed the store while your pipeline was running, and the right response is to fail the build and look, not to retry.