Fluid CLI: Local Theme Development and Deployment Tool

The Fluid CLI is a command-line tool that brings your theme development workflow to your local machine. With it, you can pull your live theme down to edit in your preferred code editor, push changes back to the server, run a local development server with hot reload, and manage authentication across multiple company accounts. It is designed for developers who want full control over their theme files outside of the browser-based editor.

Installation

Install the Fluid CLI and its theme plugin from npm:

npm install -g @fluid-app/fluid-cli @fluid-app/fluid-cli-theme-dev

The fluid theme commands come from the theme plugin, so install both. After installation, verify it is available by running fluid --version.

Authentication

Before you can interact with any theme, you need to authenticate the CLI with your Fluid account.

fluid login

The CLI asks for your email address and sends you a one-time code. Enter the code to sign in; the CLI stores your credentials locally for future commands. To sign in with an API token instead, pass it in the FLUID_TOKEN environment variable so it stays out of your shell history:

FLUID_TOKEN=<your_token> fluid login

To check which account and company you are currently authenticated as:

fluid whoami

To sign out and remove the stored token:

fluid logout

Company Management

If you manage multiple companies in Fluid, you can switch between them without logging out. Run the interactive company switcher:

fluid switch

Or switch directly to a company or profile by name:

fluid switch mystore

After switching, all subsequent theme commands operate against the selected company’s theme.

Theme Commands

Use these commands to manage your theme files between your local machine and the Fluid platform.

Command	Description
`fluid theme init`	Initialize a new theme project in the current directory. `--clone-url` starts from another Git repository
`fluid theme pull`	Pull a theme from the server to your local directory, merging remote changes into local edits
`fluid theme pull --nodelete`	Pull from the server, but preserve any local files that don’t exist on the server
`fluid theme pull --resolve local`	Resolve merge conflicts automatically, keeping your local hunks (`remote` keeps the server’s) instead of writing conflict markers
`fluid theme pull --only-if-clean`	Skip the pull, exiting with code 3, when local work can’t be proven to be in sync
`fluid theme pull --force`	Overwrite local files without merging
`fluid theme pull --yes`	Skip the confirmation prompt
`fluid theme lint`	Validate theme files locally without uploading. Add `--json` for machine-readable output
`fluid theme push`	Push your local theme files to the target theme. Pushing to the live theme changes what shoppers see
`fluid theme push --publish`	Push, then publish the target theme
`fluid theme push --unpublished`	Create a new unpublished theme and push your files to it. It asks for the new theme’s name and has no flag for it, so run it in an interactive terminal
`fluid theme push --nodelete`	Push local files, but preserve any server files that don’t exist locally
`fluid theme push --auto-baseline`	When there’s no local baseline yet, record the server’s current state as the baseline and push only what differs locally
`fluid theme push --force`	Skip local Liquid validation and the server-side merge check
`fluid theme dev`	Start a local development server with live reload, on port 9292 by default. See Run the dev server
`fluid theme navigate`	Pick a storefront route and open it in the running dev server
`fluid theme skills install`	Install the bundled Fluid theme skills for coding agents
`fluid theme crawl <url>`	Capture a live page as Markdown, HTML, or a screenshot. See Capture a live page
`fluid theme staging request`	Create the theme’s staging branch, a private copy you can preview. See Theme branches
`fluid theme staging wait`	Wait until staging is ready or has failed
`fluid theme staging status`	Show staging’s state and its shareable preview link
`fluid theme staging publish`	Publish your local files to staging. The live theme isn’t changed
`fluid theme staging compare`	Show how your local files differ from what staging serves
`fluid theme staging promote`	Put what staging serves onto the live theme, all at once. `--dry-run` shows what would change
`fluid theme staging undo-promote`	Put the live theme back as it was before staging’s latest promotion

pull, push, and dev accept --theme (-t) with a theme name or ID. See Choose the theme a command uses for what each command targets without it. pull, push, dev, and lint accept --root to run against a theme directory other than the current one. fluid theme lint runs the same schema validation as fluid theme push, so it catches errors that would block a push before you upload. It also warns about each page type your theme has no template for, because the storefront shows your home page at those URLs. Native widget references such as fluid://native/widgets/chgoal and fluid://native/widgets/<key>/sections/<name> have no local file, so lint accepts them when <key> is in the native widget catalog. It warns about an unknown key, which may be newer than your CLI, without failing the lint. A malformed fluid://native/ reference is still an error. In .liquid files and assets/ scripts, it warns about cart code that misuses the SDK: cart/create-cart-for-data and cart/custom-add-without-drawer-open. See Common pitfalls. Warnings don’t fail lint. A clean lint result doesn’t prove every template renders: check the page in fluid theme dev as well.

Choose the theme a command uses

fluid theme push picks its target in this order:

With --unpublished, it asks you for a name, creates a new unpublished theme, and pushes to it.
With --theme, it pushes to the theme you name.
Otherwise, it pushes to the theme this directory is bound to in .fluid-theme.json, and prints Using theme from .fluid-theme.json with the theme’s name and ID. fluid theme pull writes that file, so a project pushes back to the theme you pulled it from.
With no .fluid-theme.json, it asks you to pick a theme.

fluid theme pull uses --theme, or asks you to pick a theme. It doesn’t read .fluid-theme.json to choose one. A push needs a baseline: the state of the theme the last time this directory synced with it. Without one, for example when you haven’t pulled the theme into this directory, the push stops before it changes anything. Run fluid theme pull -t <theme-id> first, or rerun the push with --auto-baseline, or with --force to overwrite the theme’s files with yours.

A push to your live theme changes your storefront straight away. There’s no draft step, whatever flags you add: --force only skips validation and the merge check, and --auto-baseline only records a baseline. To review changes before shoppers see them, push with --unpublished, work in fluid theme dev, or publish to the theme’s staging branch, share its preview link, and promote it when it’s right.

Development themes

fluid theme dev syncs your files to a development theme, a scratch copy named like Development (<host>-<random>). Your storefront never serves a development theme, so a push to one changes nothing live.

When your project is bound to a real theme, fluid theme push --theme <development-theme-id> updates this project’s development theme. The project stays bound to the real theme.
fluid theme push --publish refuses to publish a development theme, because that would make the scratch copy your live theme. Push without --publish, or publish the theme the project is bound to.
Push refuses a development theme that another project or teammate created, because the push would overwrite it with your files. To sync to one on purpose, run fluid theme dev --theme <id>.
fluid theme pull refuses to pull a development theme into a project bound to another theme. Pull it into a separate directory with --root.

Examples

Pull your current theme before making changes:

fluid theme pull

Push your local changes to a new unpublished theme so you can preview them before anything goes live:

fluid theme push --unpublished

Start the local dev server for active development:

fluid theme dev

Run the dev server

fluid theme dev serves your theme locally and syncs each saved file to a development theme of its own. The first run creates that theme, copying the theme you pulled when it can, and later runs in the same project reuse it. Your live theme doesn’t change.

Option	Effect
`--port <port>`	Serve on another port. The default is `9292`
`--host <host>`	Bind to another host. The default is `127.0.0.1`
`--live-reload off`	Turn off automatic page reloads. The default is `full-page`
`--navigate`	Open the route picker once the server starts
`--theme <name-or-id>`	Sync to an existing theme instead of the development theme
`--force`	Skip schema validation when syncing

--theme syncs your local edits into the theme you name. Point it at the live theme only when you mean to change what shoppers see.

Preview member pages

Member pages live on the account subdomain, not the storefront, so the dev server serves them under /_members:

Open http://127.0.0.1:9292/_members. It lists each member site in the theme with its pages, including drafts.
Choose a page. Its URL keeps the site you picked, for example http://127.0.0.1:9292/_members/rewards?members_site_id=<id>. The home page is /_members/?members_site_id=<id>.

A member page URL needs members_site_id. Without it, the dev server asks you to select a member site at /_members first. Opening /accounts returns not found, as it does on the storefront domain. The preview renders with sample data, as a guest. To preview as a sample member of one type, add member_type_id=<id>, which also applies that site’s access rules. country_id and language_id pick the country and language. The preview never signs in as a real member: forms, sign-in links, and native widget actions do nothing, and widgets show sample content. Saved files reload member pages the same way as storefront pages. To see a page with live data, use the member preview in the builder, or sign in on the account subdomain. See Test a member site.

Preview on a theme branch

fluid theme staging gives a theme a staging branch: a private copy that you publish your local files to and preview on your real storefront through a shareable link, without changing the live theme. When staging looks right, promote it to the live theme.

fluid theme staging request
fluid theme staging wait
fluid theme staging publish
fluid theme staging status
fluid theme staging promote --dry-run
fluid theme staging promote

status prints the preview link. promote --dry-run lists what promoting would change, and promote puts exactly what staging shows onto the live theme after you confirm. fluid theme staging undo-promote reverses the latest promotion. See Theme branches for the full workflow, how teammates’ changes are kept safe, and when to push instead.

MySite themes

MySite themes have their own commands, from the @fluid-app/fluid-cli-mysite plugin: fluid mysite list, fluid mysite pull --theme <id>, fluid mysite dev, and fluid mysite publish. A MySite publish has no draft and changes every MySite that uses the theme at once. See MySite themes.

Capture a live page

fluid theme crawl <url> loads a page in Fluid’s managed browser, runs its JavaScript, and prints a JSON report with the page’s content. Use it to capture a production page before you change it, so you can compare it with your version afterwards.

fluid theme crawl https://acme.fluid.app/home --format screenshot --viewport 1440x900 --evidence .

Option	Effect
`--format <format>`	`markdown`, `html`, or `screenshot`. Repeat the option or separate formats with commas. The default is `markdown`, or all three with `--evidence`
`--viewport <WxH>`	Capture at an exact viewport in CSS pixels, such as `1440x900` or `390x844`. Width runs from 320 to 3840 and height from 320 to 2160. Implies a screenshot
`--full-page`	Capture the whole page height, not only the first screen
`--quality <1-100>`	Screenshot quality
`--no-main-content-only`	Keep the navigation bar, announcement bar, and footer. Use it when you rebuild a whole site
`--evidence <dir>`	Save the capture under `<dir>/.mist-desktop/source-baselines/`. Needs `--viewport`
`--action <json>`	A browser action to run before the capture: `{"type":"wait","milliseconds":1000}`, `{"type":"click","selector":".tab-reviews"}`, or `{"type":"scroll","direction":"down"}`. Repeat it for up to 8 actions
`--post-evidence-action <json>`	An action to run after the evidence is collected and before the final screenshot, such as closing a cookie banner with `{"type":"dismiss","selector":".cookie-accept","scope_selector":".cookie-banner"}`. Needs `--evidence` and `--full-page`
`--direct`	Crawl with your own Firecrawl key, from `FIRECRAWL_API_KEY`, instead of through Fluid

Without --direct, the crawl runs through your Fluid sign-in, so run fluid login first. When the report says "ok": false, the command exits with code 1.

Install theme skills

Install the bundled theme-development skills so a compatible coding agent can use them:

fluid theme skills install

The default destination is .agents/skills/ in your current project. Existing skills remain untouched unless you approve the overwrite. Choose a different destination with --dir or -d:

fluid theme skills install --dir .claude/skills

Overwrite existing copies without a prompt with --force or -f:

fluid theme skills install --force

Restart your agent session after installation so it can discover the new skills.

Skill	Use it to
`themes-review`	Review a theme or a theme pull request against Fluid’s schema, Liquid, editor, and FairShare rules
`themes-settings-schema`	Write `config/settings_schema.json` so the Theme panel renders it and builds typography presets
`themes-cart-feedback`	Add cart toasts, button loading states, and cart operation event handling
`template-stylesheet-to-asset-migration`	Move deprecated `styles.css` and `global_styles.css` files into `assets/`

Getting Started Workflow

Follow these steps to go from a fresh install to an active local development environment:

Install the CLI

Install the CLI and its theme plugin from npm as shown above.

Run fluid login and enter the one-time code sent to your email.

Create a project directory

mkdir my-theme && cd my-theme

Initialize or pull your theme

To start a brand new theme:

fluid theme init

Or, to download your existing published theme:

fluid theme pull

Start the development server

fluid theme dev

The dev server proxies requests to your local theme files, so you can see changes in the browser instantly as you save.

Push your changes

Push your changes to the theme, and publish it when you’re ready:

fluid theme push --publish

Or push to a new unpublished theme first to review it in the admin:

fluid theme push --unpublished

Start here

Building blocks

Storefront features

Advanced

Member storefront

Fluid CLI: Local Theme Development and Deployment Tool

Installation

Authentication

Company Management

Theme Commands

Choose the theme a command uses

Development themes

Examples

Run the dev server

Preview member pages

Preview on a theme branch

MySite themes

Capture a live page

Install theme skills

Getting Started Workflow

​Installation

​Authentication

​Company Management

​Theme Commands

​Choose the theme a command uses

​Development themes

​Examples

​Run the dev server

​Preview member pages

​Preview on a theme branch

​MySite themes

​Capture a live page

​Install theme skills

​Getting Started Workflow

Installation

Authentication

Company Management

Theme Commands

Choose the theme a command uses

Development themes

Examples

Run the dev server

Preview member pages

Preview on a theme branch

MySite themes

Capture a live page

Install theme skills

Getting Started Workflow