@fluid-app/fluid-cli-theme-dev
Fluid CLI plugin for theme development. Adds fluid theme commands for local dev server, push, pull, scaffolding, and
page-clone evidence (crawl / compare).
Installation
npm install -g @fluid-app/fluid-cli @fluid-app/fluid-cli-theme-dev
Requires @fluid-app/fluid-cli as the core CLI.
Authentication
Log in before using any theme commands:
fluid login
Commands
fluid theme dev
Start a local dev server that proxies your storefront with hot reload:
fluid theme dev
The dev server will:
- Create (or reuse) an isolated development theme
- Preserve pulled binary assets as ImageKit URL references without downloading or re-uploading their bytes
- Keep editable source files (Liquid, CSS, JS, SVG, JSON) locally
- Upload a newly added binary once, save its ImageKit URL reference, and remove its local bytes
- Watch for source-file changes and sync them automatically
- Proxy requests to
{company}.fluid.appwith local file overrides
For a pulled theme, a newly created dev theme is a server-side reference clone
of the pulled source. It preserves theme content and DAM/ImageKit references,
so initial dev startup does not reseed every asset from the working copy. The
CLI keeps a compact local index of the development theme's acknowledged
checksums and version. Later startups validate that version, compare local files
to the cached dev state, and send only the actual changes without downloading
the complete remote resource index. A web-editor write, changed ImageKit
manifest, missing or malformed cache, or interrupted write invalidates the
shortcut and falls back to the full remote comparison. Set
FLUID_THEME_DEV_DISABLE_SHADOW_SYNC=1 to force that comparison as an emergency
rollback.
Theme paths that differ only by letter case are refused before pull, push, or dev writes. Windows separators are normalized before comparison. Default macOS and Windows filesystems cannot preserve both resources, so continuing would replace one path and delete the other.
| Flag | Default | Description |
|---|---|---|
--host <host> | 127.0.0.1 | Local server host |
--port <port> | 9292 | Local server port |
-t, --theme <name-or-id> | auto | Use a specific theme instead of dev theme |
--live-reload <mode> | full-page | Reload mode: full-page or off |
--navigate | off | Open browser navigator after start |
--root <path> | . | Theme root directory |
Member sites
Theme member sites are retired. Member sites are built with Sites now:
fluid sites (fluid member-site). fluid theme no longer syncs
members_sites.json, config/members_sites.json or members_page/**, and
fluid theme dev has no /_members preview. See
Member sites (retired).
fluid theme push
Upload local theme files to a remote theme:
fluid theme push # Interactive theme selection
fluid theme push --theme "My Theme" # By name
fluid theme push --theme 42 # By ID
fluid theme push --publish # Push and publish
fluid theme push --nodelete # Keep remote files not present locally
fluid theme push --auto-baseline # First push without a baseline: record
# the server's current state as the
# baseline, then push only local diffs
Pushing into an existing theme requires a local baseline (recorded by pull, or migrated from a checksum-era .fluid-theme.json). Without one, push refuses so it can't silently clobber the server. --auto-baseline instead records the server's current state as the baseline — no local file is modified, files identical to the server aren't re-uploaded, and files that exist only on the server are never deleted — then pushes what differs locally. Mist Desktop's one-click Publish uses this flag.
Files containing unresolved <<<<<<< / ======= / >>>>>>> conflict markers are never uploaded; push lists them and exits (with a machine-readable FLUID_THEME_PUSH_BLOCKED code=conflict_markers files=… line under --auto-baseline).
fluid theme pull
Download a remote theme to your local directory:
fluid theme pull # Interactive theme selection
fluid theme pull --theme "My Theme" # By name or ID
fluid theme pull --nodelete # Keep local files not present on remote
fluid theme pull --resolve remote # Auto-resolve conflicts to the server's
# side (or `--resolve local` to keep
# yours) instead of writing markers
By default, conflicting edits (changed locally and on the server since the last sync) are written with git-style conflict markers for you to resolve. For non-interactive use, --resolve local keeps your side of each conflicting hunk and --resolve remote takes the server's; before any auto-resolution overwrites local content, the pre-merge working tree is committed to the theme's shadow history (.fluid-theme/repo) so the discarded side stays restorable.
fluid theme widget
Customize a Fluid native widget ({% section 'fluid://native/widgets/<key>' %})
through the theme's own copy of it. The copy replaces the widget at every
placement in the theme, the same copy the visual builder makes when a widget is
dropped:
fluid theme widget copy acct # Make the copy and pull it into fluid_native_acct/ (asks first on the live theme)
fluid theme widget copy acct --yes # Same, without the live-theme confirmation
fluid theme widget reset acct # Delete the copy and its fluid_native_acct/ folder (asks first)
fluid theme widget reset acct --yes # Same, without the confirmation
A copy keeps the template type of Fluid's original, so it is pulled into
sections/fluid_native_<key>/ for a widget that is still a section and into
widgets/fluid_native_<key>/ for one stored as a widget. reset deletes the
theme's copy of either type and removes both folders.
Both commands act on the theme in .fluid-theme.json unless --theme <id> is
passed, then run an ordinary fluid theme pull of that theme so the sync
baseline matches the server. The pull also brings down any other changes made
to the theme since the last pull.
On the live (active) theme a copy or reset changes what members see as soon as
it is made, so copy asks before it makes the copy there and reset says the
theme is live in its confirmation. --yes skips both prompts.
Do not create sections/fluid_native_<key>/ or widgets/fluid_native_<key>/
by hand: without a copy of that type, a push makes it a plain template that
replaces nothing, and every placement keeps rendering Fluid's original.
fluid theme push warns about such folders.
fluid theme init
Scaffold a new theme from the base template:
fluid theme init my-theme
cd my-theme
fluid theme dev
fluid theme navigate
Interactively select a route and open it in the browser (requires a running dev server):
fluid theme navigate
fluid theme skills install
Copy the bundled theme AI skills (e.g. themes-review) into the current directory so an
agent can load them. Defaults to .agents/skills/, the tool-neutral convention for agent
skills:
fluid theme skills install # → .agents/skills/
fluid theme skills install --dir .claude/skills # custom location
fluid theme skills install --force # overwrite existing skills without prompting
Existing skills are left untouched unless you confirm the overwrite (or pass --force).
fluid theme crawl <url>
Scrape a public page through Fluid's managed browser (JavaScript rendered) and print JSON with its Markdown, optional HTML, and a hosted screenshot URL. Mist's agent runs this command for every crawl.
fluid theme crawl https://example.com/ # Markdown, main content only
fluid theme crawl https://example.com/ --format html --format screenshot
fluid theme crawl https://example.com/ \
--viewport 1440x900 --full-page --quality 90 --no-main-content-only \
--evidence . # durable page-clone bundle
fluid theme crawl https://example.com/ \
--action '{"type":"click","selector":"#accept-cookies"}' \
--action '{"type":"wait","milliseconds":1000}' # act before the capture
| Option | Meaning |
|---|---|
--format <f> | markdown, html, or screenshot; repeatable or comma-separated. Default markdown, or all three with --evidence |
--viewport WxH | Exact CSS-pixel viewport (implies a screenshot). Use 1440x900 and 390x844 for desktop/mobile parity |
--full-page | Capture the complete document height |
--quality <1-100> | Screenshot quality |
--no-main-content-only | Keep the nav, announcement bar, and footer. Use it for site cloning |
--evidence <dir> | Save an evidence bundle under <dir>/.mist-desktop/source-baselines/. Requires --viewport |
--action <json> | A browser action before the evidence walk: {"type":"wait","milliseconds":N} (up to 10000), {"type":"click","selector":"…"}, or {"type":"scroll","direction":"up|down"}. Repeatable, up to 8 |
--post-evidence-action <json> | An action after the evidence walk and before the final screenshot, e.g. to close a drawer the walk opened. Also accepts {"type":"dismiss","selector":"…","scope_selector":"…"}, which the sidecar records. Needs --evidence and --full-page. Repeatable, up to 8 |
--direct | Skip Fluid's endpoint and call Firecrawl with your own FIRECRAWL_API_KEY |
--evidence writes the bundle in the layout Mist's compare_preview_to_source reads, so
either Mist or fluid theme compare can compare it:
the full screenshot, the Markdown/HTML, the raw HTML, the page's own CSS, and a
.page-evidence.json sidecar with landmarks, computed styles, SHA-256 hashes, and receipts.
The JSON output lists every path (evidence.files). Inline content is capped at about
200KB, or a 16KB excerpt when the full documents are saved. The scrape times out after
60s. With --evidence, stylesheet recovery is bounded at 30s and the screenshot download
at 20s. Both downloads refuse localhost and private-network addresses.
Where the crawl runs. The CLI calls Fluid's crawl endpoint with your fluid login
token, so you do not need a Firecrawl key. If the endpoint is not deployed on your API
host (HTTP 404) or not configured (HTTP 503), and FIRECRAWL_API_KEY is set, the CLI
falls back to Firecrawl directly with that key. Create a key at
https://www.firecrawl.dev/app/api-keys. Errors are printed as JSON
({"ok": false, "error": {"code": …, "message": …}}), and the command exits 1.
fluid theme compare
Render the local fluid theme dev preview at a crawl bundle's exact viewport. It prints
the same banded pixel diff Mist's compare_preview_to_source reports: a bands[] array
and a worst-first summary, with exact-copy and media-parity checks.
fluid theme dev & # serves http://127.0.0.1:9292
fluid theme compare --source . # newest "/" capture in ./.mist-desktop/source-baselines
fluid theme compare --source .mist-desktop/source-baselines/<file>.page-evidence.json \
--route /collections/all --geometry diagnostic --media diagnostic
| Option | Default | Meaning |
|---|---|---|
--source <path> | (required) | A .page-evidence.json sidecar, its directory, or the --evidence dir |
--route <path> | / | Local route to render |
--source-route <path> | --route | Source pathname when it differs (for example /en-us for /) |
--url <url> | http://127.0.0.1:9292 | Base URL of the running preview |
--mode full|viewport | full | Whole page, or the top viewport only |
--copy exact|diagnostic | exact | exact fails on any ordered rendered-copy mismatch |
--geometry strict|diagnostic | strict | strict fails when document height differs by more than 5% |
--media strict|diagnostic | strict | strict fails on image/video parity differences |
--viewport WxH | Pick the capture at this viewport when --source holds several |
The command refuses mixed captures, silent resizing, failed routes, truncation, horizontal
overflow, unresolved media, and copy mismatches. On a refusal, ok is false and the
command exits 1. A successful run means the evidence is available. It does not mean the
page passes visually. Fix the worst band, then compare again. The local capture is saved
under .mist-desktop/screenshots/.
compare needs a headless browser. Playwright is an optional peer dependency, so a
theme-dev install never downloads browsers. Install it once with:
npm i -g playwright && npx playwright install chromium
Theme Directory Structure
A valid theme directory must contain at least one of: templates/, assets/,
config/, or the asset reference manifest .fluid-assets.json.
Use a .fluidignore file (same syntax as .gitignore) to exclude files from syncing.
Remote binary assets
fluid theme pull keeps binary assets such as images, fonts, video, and PDFs
remote rather than downloading them into assets/. Their ImageKit URL
reference metadata is recorded in .fluid-assets.json. The CLI uses that
manifest when it starts a dev theme or pushes to another theme, so existing
asset_url calls continue to resolve normally without local binary copies.
When a developer adds a new binary file during fluid theme dev, the CLI
uploads it once, records its ImageKit URL reference in the manifest, and
removes its local bytes after the theme resource has been saved. A later
fluid theme push writes that same ImageKit URL into the selected target theme
without a second binary upload.
Binary assets must be direct children of assets/ (for example,
assets/logo.png); nested asset directories are not supported by the theme
resource API.
Do not add .fluid-assets.json to .fluidignore; it is already excluded from
theme uploads and file watching. Commit it with the theme source so every
developer receives the same remote asset references.
Member sites (retired)
Theme member sites (members_sites.json at the theme root or under
config/, and members_page/<name>/ templates) are retired. Build member
sites with Sites instead: fluid sites (fluid member-site).
fluid theme skips these files in every direction and prints a warning that
names them:
push,devandstaging publishnever upload them, and never delete Fluid's copies, so member pages already on Fluid keep serving to members.pullandstaging pullnever write them; local copies are left alone.staging compareneither declares them nor counts them as a difference.lintlists them as warnings and does not check them.
You can delete the local files once your member site lives in Sites.
Native widgets
{% section 'fluid://native/widgets/<key>', id: '…' %} places a Fluid-owned
widget. It has no local file; fluid theme lint accepts known keys and warns
about unknown ones. Placing a new native widget needs the company to have
member sites enabled.
To customize a widget, create the theme's own copy with
POST /api/v202604/themes/<id>/native-widget-copies and
{"native_widget_key": "<key>"}. The copy replaces the widget at every
placement in that theme, and a later pull brings it down as
sections/fluid_native_<key>/index.liquid. Don't create that file by hand: a
hand-written sections/fluid_native_<key> is a plain section and does not
replace the widget.
Staging
Retired template types (account_page, members_dashboard and
members_login) are not theme files: their folders are never uploaded,
published or listed.
Publishing when a teammate published first
fluid theme staging publish sends every theme file it publishes (all but
the paths it skips and lists, such as files attached to a template), so it
would put this checkout's copy of each of those back on staging. To keep that from undoing a
teammate's work by accident, each successful publish records the staging
revision and the files it published in .fluid-theme/staging-baseline.json.
The next publish from the same directory compares staging with that record
first. When files changed on staging since then and this checkout has them
differently, the publish is refused with staging_moved, names those files
and the current revision, and changes nothing:
Staging has changes you don't have (revision 12). Publishing would replace them. Get those changes first, or publish with --force to replace them.
- sections/hero_section/index.liquid
- Bring their changes into this checkout and publish again; once your copies match staging's, nothing is replaced and the check passes.
--replace-at <revision>replaces them on purpose, only while staging is still at that revision. If someone published again meanwhile, the check runs again and names the new files. Mist's Replace anyway uses this.--forcereplaces them whatever the revision.
Paths are matched however a resource's path is spelled, so a case or
resource-kind difference doesn't hide a file. With no record (a new checkout,
or the file deleted), there is nothing to compare and the publish isn't
checked. With --json, the refusal's error.type is staging_moved and
error.paths lists the files.
Taking a teammate's staging changes
fluid theme staging pull writes into this directory the files someone else
published to staging since this directory last published, so the next
publish carries their work instead of being refused. It only writes files
this directory still has as they were at that publish; a file you changed too
is kept and named, never overwritten. Staging names its own copies of the
menus, so a file taken from staging has each one put back to the menu this
directory names in the same place (matched through the legacy
members_sites.json menu references, when both sides still have one); a file
that would still name a staging menu is kept. Retired member site files are
never taken. When the
directory then matches staging, its staging record moves to the current
revision. With --json it prints revision, taken, kept (each with its
reason), matches, and verified (false when the closing comparison
with staging couldn't be made, so matches is unconfirmed).
Promoting staging to live
fluid theme staging promote copies exactly what staging serves onto the
live theme, all at once. It lists the files it will write and remove and asks
first; pass --yes to skip the question (JSON mode always needs --yes). It
only promotes when the live theme hasn't changed since staging was based on
it; otherwise it refuses rather than overwrite that change. Images and other
binary files are copied to assets the live theme owns.
fluid theme staging undo-promote puts the live theme back as it was before
the latest promotion, while the live theme still serves exactly what that
promotion applied.
Comparing with staging
fluid theme staging compare reports how this directory's files differ from
what the theme's staging branch serves: files whose content changed, files
only you have, and files only staging has. It sends each file's SHA-256, never
its content, and changes nothing. Publishing to production (fluid theme push)
always sends your local files, so compare first when staging may hold work
that isn't in this checkout, such as a teammate's staging publish.
Development
For contributors working in this monorepo:
pnpm --filter @fluid-app/fluid-cli-theme-dev build
node packages/cli/core/dist/bin/fluid.mjs theme --help