@fluid-app/fluid-cli-mist

Fluid CLI plugin for Mist hosted extensions. The fluid CLI discovers it through the fluid-cli-* naming convention and adds the fluid mist commands. The full command surface is specified in features/mist/cli-spec.md.

Each command takes an optional mist slug. Without one, it reads the .mist file in the current directory, which fluid mist clone writes.

Commands

Pushing an approved commit

fluid mist push --expect-commit <full-sha> [--watch]

Pushes exactly that commit to refs/heads/<branch>. It refuses with exit code 5, before any network call, unless the sha is a full 40-character hex id (64 for sha256 repos; a 64-hex value in a sha1 repo is refused as head_mismatch), equals HEAD, the branch is a plain name (no refs/ prefix or :), and the working tree has no changes, untracked files or dirty submodules. It never auto-commits, pulls, or stashes, and it cannot be combined with -m. --watch matches the deployment for that sha.

Generating a secret

fluid mist env set WEBHOOK_AUTH_TOKEN --generate             # 32 bytes
fluid mist env set my-mist SESSION_SECRET --generate --bytes 64

--generate mints a cryptographically strong base64url secret (16 to 128 bytes, default 32), writes it to the key, and prints it once. Fluid stores env values encrypted and env list never shows them, so copy the secret immediately if you also need it in .env.local. It uses the same generator as Mist's set_mist_env_var tool. It refuses Mist-managed keys before generating anything. Redeploy with fluid mist push for the change to take effect.

Reaching Exigo through the egress proxy

fluid mist create --droplet --egress-proxy    # new mist + droplet, asking for egress
fluid mist attach-droplet --egress-proxy      # attach (or reuse) a droplet, asking for egress
fluid mist droplet egress-proxy on            # ask for egress for the attached Droplet
fluid mist droplet egress-proxy off           # withdraw the request (and any grant)

Fluid's egress proxy lets a Droplet's installations reach external systems such as Exigo from Fluid's fixed outbound IPs. These commands set the Droplet's egress_proxy_requested, and the proxy then admits the Droplet with no further approval, wherever the proxy honours Fluid's answer. Withdrawing the request also clears any grant a Fluid admin recorded (egress_proxy_enabled).

--egress-proxy works on create --droplet, create --kind droplet, create --hostable, attach --kind droplet and attach-droplet. On a Droplet that already exists it updates the request rather than ignoring the flag. Fluid accepts an egress request only from a company admin, for their own company's droplets. Otherwise it refuses the request: --egress-proxy then sets the droplet up without it and warns, and droplet egress-proxy fails with Fluid's reason without writing. A Fluid that predates the fields ignores them, and the commands warn or fail the same way. droplet egress-proxy off also clears a grant a Fluid admin gave without a request. Mist Desktop's Safe Mode treats droplet egress-proxy as a write.

Repairing the attached Droplet

fluid mist droplet repair --dry-run   # show the planned change
fluid mist droplet repair             # prompt, then apply
fluid mist droplet repair --yes       # apply without a prompt

This sets the Droplet's embed_url, install_webhook_url and uninstall_webhook_url from the mist's public_url as Fluid reports it. The local .mist file's copy of the URL is never used. The webhook paths come from dropletLifecycle in fluid.capabilities.json when you run it inside the project. Otherwise it uses /api/webhooks/installed and /api/webhooks/uninstalled. Only those three fields change, and the command re-reads the Droplet to verify them. Without a terminal to prompt in, it needs --yes.

A repair fixes future lifecycle delivery. It does not replay droplet.installed for an existing installation; for that, use reinstall.

Reinstalling the attached Droplet (irreversible)

fluid mist droplet reinstall --dry-run    # 1. show the exact plan
fluid mist droplet reinstall --confirm    # 2. execute it

reinstall repairs the lifecycle URLs and asks Fluid to replace the mist's own Droplet installation in one durable operation. In that operation Fluid revokes the installation, delivers the uninstall, terminalizes it and creates the replacement. The CLI never deletes and re-creates an installation itself. The rules match Mist's repair_and_reinstall_droplet tool:

• Plan first. --dry-run changes nothing. It prints the Mist, the Droplet, the installation and the replacement endpoint.

• Explicit approval. --confirm executes only when a --dry-run ran in the last 15 minutes for the same Droplet, installation and lifecycle URLs. --yes never approves a reinstall. --confirm uses up the plan whether or not it goes ahead, and two --confirm runs can't share one plan, so a retry needs a new --dry-run.

• Own Droplet only. The Droplet is always the one attached to the mist, and Fluid rejects installations of any other Droplet.

• Resumable watching. The CLI watches for 120 seconds by default (--watch-timeout <seconds>). A slower replacement returns "status": "still_running" together with the command that continues watching it:

  fluid mist droplet reinstall --resume <operationId> --installation <installationUuid>
  

  A resume starts nothing and needs no new plan, but it requires --installation and doesn't accept --dry-run. The reinstall is done only when status is "succeeded".

• Recovery. A failed attempt may already have terminalized the source installation, so it no longer appears in the list. In that case, plan and confirm with --installation <uuid>, using the uuid from the earlier plan. A named installation always takes precedence over the active one.

reinstall always prints JSON. A refusal prints {"status": "refused", "code": …} and exits 1. A failed replacement exits 1, and API errors use the CLI's usual codes: 2 for a 4xx, 3 for a 5xx and 4 for a network error. Plan receipts hold only ids, the planned URLs and a timestamp. They are stored in ~/.fluid/mist/reinstall-plans/.

Development

pnpm nx run-many -t test,typecheck,lint,build -p @fluid-app/fluid-cli-mist

Shared Mist logic (lifecycle URLs, Droplet repair planning, replacement rules, polling, secret generation) lives in the private @fluid-app/mist-core package. The build bundles it into this plugin.