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:
Before sending anything, push checks every version it recorded against what the server holds now. If any of them moved, it refuses having written nothing:
Retrying will not help, which is why the message says so. Pull into a clean directory, look at what changed, and re-apply. That check is not the only guard. Every individual write still carries the version you pulled, because somebody can always land a change in the gap between the check and the write. If that happens the push stops part-way and says so, rather than claiming nothing was written:
The fix is the same either way. The difference is only whether some templates already landed, and the message tells you which case you are in.

​
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

Translates a Shopify theme into a Mercemur storefront.
Nothing is published. The result lands on disk for you to read, diff and edit like any other file. mercemur theme push and mercemur theme publish are still what put it in front of shoppers.It reads six files, and the two that catch people out are sections/header-group.json and sections/footer-group.json. Your header, announcement bar and footer live there, not in templates/index.json, so a partial copy imports a store with no header while the homepage still looks fine.Only configuration is read. No Liquid is parsed and none is generated: since Online Store 2.0 the editable surface is JSON, and generated templates would not be editable in the visual builder anyway.Anything with no equivalent here is printed rather than dropped quietly:
Section content comes across as your theme had it, and the two products model settings differently. Read the file before you publish.
Which themes this works on. The translation is built from Dawn and Horizon, Shopify’s own themes. Section type names are chosen by whoever built a theme, so there is no shared vocabulary across the ecosystem: a theme built on neither shares none of their section names, and the import will tell you it recognised nothing rather than writing you an empty store.Themes predating Online Store 2.0 keep their homepage in templates/index.liquid with no index.json, so there is nothing here to read at all. The command says so rather than suggesting you pull again.
Prints which store the next command would talk to, and why.
Settings resolve per field across four layers, so the store in effect often appears in none of the files you are looking at. This names the layer that won for each one.It reports where the API key was found and never the key itself, so the output is safe to paste into a bug report.
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.