Skip to main content
Theme staging gives a theme its own private copy, called staging. You publish your local theme files to staging, open it on your real storefront through a preview link, share that link for review, and only then push the same files to your live theme. Publishing to staging never changes what shoppers see.
Theme staging is in early access. It works only for companies where Fluid has turned on branch environments. For any other company, the staging commands answer Theme staging is not enabled for this company.

​
How staging works

  • One staging per theme. A draft or live theme can have one staging copy. It belongs to that theme and lasts until the theme is deleted.
  • It starts as a copy. Requesting staging copies the theme: its templates, sections, settings, translations, files, and member sites.
  • Only staging publishes change it. The staging copy isn’t listed with your other themes, can’t be made live, and refuses edits from the theme editor or a fluid theme push aimed at it. Your local files reach it only through fluid theme staging publish.
  • Publishes land all at once. A staging publish applies every changed file in one step, so anyone previewing staging sees the whole previous version or the whole new one, never half of each.
  • Every publish bumps a revision. Staging starts at revision 0 and goes up by one with each publish.

​
Create staging

Run the staging commands from a theme directory you pulled with fluid theme pull. They use the theme this directory is bound to in .fluid-theme.json. Pass --theme <id> to name another theme, or --root <path> to read a different directory.
1

Request staging

Fluid starts copying the theme in the background. If staging already exists or is already being created, the command reports where it stands instead of failing.
2

Wait until it's ready

The command checks every few seconds and returns when staging is ready or has failed. It gives up after 600 seconds; set another limit with --timeout <seconds>. It exits with code 1 unless staging is ready.
3

Check it

It prints staging’s state and, once it’s ready, its preview link.
If creating staging fails, run fluid theme staging request again. It picks up where the copy stopped.

​
Publish to staging

The publish sends your local theme files to staging. Your live theme isn’t touched.
  • Only changed files travel. The CLI sends a SHA-256 checksum for each file, Fluid compares them with what staging already has, and only new or changed content is uploaded and applied. Publishing again with nothing changed is quick.
  • Someone else may have published first. If another publish reached staging after yours started, yours is refused instead of overwriting it. Publish again.
  • Deleting a file locally doesn’t delete it from staging. A publish changes only the files you have.
  • Member sites come along. members_sites.json is published with the rest of the theme, without references to retired account and member pages. Fluid stores the member configuration it imports, and may rewrite keys in it, for example a site key becoming the site’s name.
Some files are never published to staging, and the command lists them as skipped: One publish can hold up to 5,000 files, each up to 5 MB of text or 25 MB for images and other binary files.

​
Preview and share staging

fluid theme staging status prints staging’s preview link. It opens staging on your real storefront domain, with a Preview mode banner at the top naming the staging theme.
  • Anyone can open it. The link doesn’t need a Fluid login, so you can send it to a reviewer.
  • It lasts 7 days. Run fluid theme staging status again for a fresh link.
  • The preview stays on while you browse. Following links on the storefront keeps showing staging in that browser until you choose Exit preview in the banner.
  • It stops working once staging is removed. After that, the link shows the live theme.
Cart and checkout in a staging preview act on your real store. Adding to the cart or checking out during a preview uses live data and can create real orders. Share staging links for review, not for test purchases.
Products or pages pinned to a specific template keep using the live theme’s template in a staging preview.

​
Push to live

Staging doesn’t go live by itself, and there’s no command that copies staging to your live theme. When staging looks right, push the same files to your live theme as usual:
fluid theme push sends the files in your directory, not what’s on staging. If you edited files after your last staging publish, or a teammate published to staging from their own copy, live won’t match what you reviewed. Publish to staging and check it again before you push.

​
Remove staging

Staging is removed together with its theme: deleting a theme also deletes its staging copy, its preview link, and everything it stored. There’s no command that removes staging on its own.

​
Use staging in Mist Desktop

For a theme project, Mist Desktop shows staging next to Local and Prod in the preview:
  • Request staging in the preview bar creates it and shows its progress.
  • The Staging tab opens staging inside Mist, and Copy link copies a fresh preview link for the page you’re viewing.
  • Publish to staging sits beside Publish in the top bar. Publish still pushes your local files to the live theme.

​
Scripts and coding agents

Every staging command accepts --json. status, request, and wait print the staging state, the branch with its revision and preview_url, and any operation still running. publish prints the new branch, how many files it declared and uploaded, and any skipped files with the reason. On failure, the command prints one JSON error with the refusal’s type and message, and exits with code 1.

​
Messages you might see