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.

Create a portal project

fluid portal create my-portal

Creation uses the bundled canonical starter by default. Pass --remote-template only when you intentionally want the GitHub mirror, or --skip-install when you want scaffold-only output. A current scaffold uses createPortal({ customPages }), keeps company widget packages in src/widgets.config.ts, and does not contain iframe preview entries.

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.
• For a verified non-interactive release, fluid portal push --yes --activate pushes the draft and creates/activates a live version only when every push phase succeeds. Partial pushes exit non-zero and are never activated.

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. Create a Remote DOM widget and register it in the single source package:

fluid portal widget create stock-ticker

The scaffold writes the widget under src/widgets/ and creates or updates src/widgets.config.ts using defineWidget and defineWidgetPackage from the worker-safe Portal SDK entry. portal.config.ts, customWidgets, and legacy manifest endpoints are not part of widget discovery.

The portal CLI publishes company-owned portal widget packages:

fluid portal deploy

• Builds defineWidgetPackage into widget.js, scoped CSS, manifest.json, and publish-manifest.json under .fluid/widget-dist by default.
• manifest.json uses the canonical Remote DOM descriptor. Its workerEntryUrl and CSS URLs are package-local artifact paths; the catalog resolves them to absolute public URLs before hosts consume the descriptor. Company and droplet package IDs remain fully qualified (company.* or droplet.*). The publish manifest records the artifact inventory and hashes.
• 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