Fluid Portal CLI — Pull & Push App Manifests

The Fluid CLI lets you pull a Fluid OS definition (your app manifest — screens, themes, navigations, profiles) into local JSON files, edit them, and push them back to production.

One-time setup

• Build the CLI (from the repo root):

  pnpm --filter @fluid-app/fluid-cli --filter @fluid-app/fluid-cli-portal build

• The fluid binary is then at packages/cli/core/dist/bin/fluid.mjs. Optionally alias it:

  alias fluid="node /path/to/repo/packages/cli/core/dist/bin/fluid.mjs"

  (All examples below assume this alias. Without it, replace fluid with node packages/cli/core/dist/bin/fluid.mjs.)

Authenticate

• Email + MFA flow:

  fluid login

• Or skip MFA with an API token:

  FLUID_TOKEN="<your-api-token>" fluid login

Pull a definition

fluid portal pull

• Interactive picker, or target one directly: fluid portal pull --app "<definition name>"
• Writes portal/ (screens/, themes/, navigations/, profiles/, definition.json) plus a .portal-sync/ folder that tracks sync state.
• Switching to a different definition with unpushed local changes? Add --force to overwrite.

Edit & preview

• Edit the JSON files under portal/.

• Preview locally (serves the manifest from your local files):

  fluid portal dev

Push changes back

fluid portal push

• Shows a diff and asks for confirmation (add --yes to skip).
• Push does NOT publish — it updates the definition's working/draft state. End users keep seeing the currently-active published version.

Publish portal versions (only when you want manifest changes live)

fluid portal version create --activate     # snapshot current state + make it live
fluid portal version list                  # see all versions
fluid portal version activate <version-id> # promote a specific version

Publish widget runtime artifacts

Portal widget packages are published separately from the hosted portal shell. The portal CLI only publishes company-owned portal widget packages:

fluid portal deploy

• Builds defineWidgetPackage runtime artifacts (widget.js, manifest.json, CSS, source maps) into .fluid/widget-dist by default.
• Publishes a company-owned portal widget package for Fluid OS usage.
• Defaults to --environment production (an output/reporting label) and --out-dir .fluid/widget-dist.
• Add --dry-run to build and print the upload payload without creating an upload session.
• This publishes widget runtime artifacts only; it does not deploy the hosted portal shell.

For droplet-owned marketplace widget packages, use the dedicated widget CLI (@fluid-app/fluid-cli-widget) instead:

fluid widget create my-widget --droplet <uuid>
fluid widget link --droplet <uuid>
fluid widget publish

Droplets are managed outside the widget CLI and must already exist before you link or publish a droplet-owned widget package.

Handy commands

• fluid whoami — show the active profile
• fluid switch — switch between profiles
• fluid logout — clear stored credentials
• fluid portal doctor — diagnose portal project issues