@fluid-app/fluid-cli-theme-dev

Fluid CLI plugin for theme development. Adds fluid theme commands for local dev server, push, pull, and scaffolding.

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:

1. Create (or reuse) an isolated development theme
2. Preserve pulled binary assets as ImageKit URL references without downloading or re-uploading their bytes
3. Keep editable source files (Liquid, CSS, JS, SVG, JSON) locally
4. Upload a newly added binary once, save its ImageKit URL reference, and remove its local bytes
5. Watch for source-file changes and sync them automatically
6. Proxy requests to {company}.fluid.app with 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 |

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 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).

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.

Development

For contributors working in fluid-mono:

pnpm --filter @fluid-app/fluid-cli-theme-dev build
node packages/cli/core/dist/bin/fluid.mjs theme --help