@fluid-app/fluid-cli

The Fluid Commerce CLI. Provides authentication, profile management, and a plugin system for extending with domain-specific commands.

Installation

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

Authentication

# Email MFA flow
fluid login

# API token (avoids shell history exposure)
FLUID_TOKEN=your-token-here fluid login

# Manage profiles
fluid whoami            # Show active profile
fluid switch            # Switch between profiles
fluid logout            # Remove stored authentication

Profiles are stored at ~/.fluid/config.json.

Plugins

Install plugins alongside the core CLI to add commands:

| Package | Commands | Description | | -------------------------------- | ------------------ | ------------------------------------ | | @fluid-app/fluid-cli-theme-dev | fluid theme * | Theme dev server, push, pull, init | | @fluid-app/fluid-cli-portal | fluid portal * | Portal app build, deploy, push, pull | | @fluid-app/fluid-cli-themes | fluid themes * | Theme management API commands | | @fluid-app/fluid-cli-assets | fluid assets * | Digital asset management commands | | @fluid-app/fluid-cli-droplets | fluid droplets * | Droplet management commands |

Example:

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

Plugins are auto-discovered from:

1. node_modules/@fluid-app/ in the current working directory
2. node_modules/@fluid-app/ where the CLI itself is installed (global installs)
3. Sibling packages in a pnpm workspace (monorepo development)

Discovering commands

fluid commands                 # every installed command, one line each
fluid commands domains         # only `fluid domains` and its subcommands
fluid commands --json          # the full catalog, for agents and doc generators

The JSON catalog lists every command with its arguments, flags (and the parent commands whose flags it also accepts), whether it changes data, and the API endpoints it calls. writes is true or false when the plugin declares it or the command confirms with --yes, and null when unknown. endpoints is null until a plugin declares them: unknown, not "calls no API". Plugins declare endpoints with describeCommand:

import { describeCommand } from "@fluid-app/fluid-cli";

describeCommand(parent.command("status <domain>"), {
  endpoints: [{ method: "GET", path: "/api/domains/{id}" }],
  writes: false,
});

Shell completion

echo 'eval "$(fluid completion bash)"' >> ~/.bashrc
fluid completion zsh > "${fpath[1]}/_fluid"
fluid completion fish > ~/.config/fish/completions/fluid.fish

Completion asks the installed CLI on each tab, so new plugins complete without reinstalling the script. It completes commands, aliases, flags and values that have a fixed set of choices. The scripts pipe the typed words to the CLI on stdin rather than as arguments, so a typed --token never shows in the process list.

Updates

Once a day an interactive run starts a detached background check of npm for a newer @fluid-app/fluid-cli; no command waits on it. When the last check found one, a short notice prints on stderr after the command finishes. A failed check is retried the next day. It never runs in CI, when output is piped, or for a workspace build. Set FLUID_NO_UPDATE_CHECK=1 (or NO_UPDATE_NOTIFIER=1) to turn it off.

Environment Variables

| Variable | Description | | ----------------------- | ------------------------------------------------ | | FLUID_TOKEN | API token (alternative to fluid login) | | FLUID_API_BASE | API base URL (default: https://api.fluid.app) | | FLUID_CONFIG_DIR | Override config directory (default: ~/.fluid/) | | FLUID_NO_UPDATE_CHECK | Turn off the daily update notice |

Development

For contributors working in this monorepo:

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