OverviewAuthenticationCLIMCP serverREST API
CLI

CLI

Drive Floom from your terminal — the floom command.

Install

The CLI ships as @floomhq/floom and installs two equivalent binaries, floom and workeros. It needs Node.js 20+.

$ npm install -g @floomhq/floom$ floom --version

No install step? Run any command through npx:

$ npx -y @floomhq/floom workers list
Output format
Most read commands accept --json for machine-readable output — ideal in scripts and CI. Without it you get a compact human-readable table.

Login & identity

Pair the CLI with your Floom Cloud account using the browser-approved device flow (see Authentication). Credentials are stored at ~/.config/floom/credentials.json.

floom login --cloud
Pair with Floom Cloud via the device flow.
--cloudTarget the hosted product (omit for a self-hosted/OSS server).
floom logout
Clear saved credentials.
floom whoami
Show the current identity — user, active workspace, and API base.
--jsonMachine-readable.
floom doctor
Diagnose setup: API reachability, auth validity, MCP install, and the runs endpoint.
--jsonMachine-readable.

Workers

List, inspect, validate, push, and run workers. A worker directory is a folder with a worker.yml and a run.py or SKILL.md.

floom workers list
List workers in the active workspace.
--jsonMachine-readable.
floom workers show <id>
Print a worker’s full record.
--jsonMachine-readable.
floom workers info <id>
A readable summary: description, trigger, connections, last run.
floom workers validate <dir>
Validate a local worker directory before pushing (checks worker.yml and the entrypoint).
floom workers push <dir>
Create or update a worker from a local directory.
floom workers run <id>
Start a manual run and stream it to completion.
--input k=vSet an input value (repeatable).
-f, --inputs-file <path>Load inputs from a JSON file.
--output-dir <path>Download run artifacts into this directory.
--jsonMachine-readable result.
floom run <id>
Alias for workers run.
example
floom run inbox-cleaner --input limit=20 --input label=Support --json

Runs

Inspect run history, follow logs, download bundles, and resolve approvals.

floom runs list
List recent runs.
--worker <id>Filter by worker.
--status <status>Filter by status (queued, running, success, failed, …).
--limit <n>Cap the number of rows.
--jsonMachine-readable.
floom runs show <id>
Show a run’s detail — status, outputs, timings.
--jsonMachine-readable.
floom runs logs <id>
Print a run’s logs.
-f, --followStream new log lines live.
floom runs download <id>
Download the run bundle (a run-<id>.zip).
floom runs approve <id>
Approve a run waiting on approval.
--comment <text>Attach a note.
--edit <json>Approve with edited output.
--jsonMachine-readable.
floom runs reject <id>
Reject a run waiting on approval.
--reason <text>Attach a reason.
--jsonMachine-readable.
floom runs cancel <id>
Cancel a queued or running run.
--jsonMachine-readable.

Secrets

Store encrypted credentials that workers reference by name. Values are write-only — they’re never printed back.

floom secrets list
List secret names and their status (values redacted).
--jsonMachine-readable.
floom secrets set <key>
Create or update a secret.
--value <value>Provide inline (otherwise you’re prompted, so it stays out of shell history).
floom secrets delete <key>
Delete a secret.
-y, --yesSkip the confirmation prompt.

Connections

Authorize third-party apps (OAuth via Composio) or import custom MCP servers your workers can call.

floom connections list
List saved connections.
--jsonMachine-readable.
floom connections add <app>
Start an OAuth flow for an app (e.g. gmail, github, googlecalendar).
--openOpen the OAuth URL in your browser automatically.
--jsonMachine-readable.
floom connections import-mcp-config <path>
Register MCP servers from a client config file.
--jsonMachine-readable.

Workspaces

Switch between the workspaces you belong to; the active one is inherited by every later command.

floom workspaces list
List your workspaces (the active one is marked).
--jsonMachine-readable.
floom workspaces create <name>
Create a workspace and make it active.
--jsonMachine-readable.
floom workspaces show
Show the active workspace.
--jsonMachine-readable.
floom workspaces switch <name-or-id>
Set the active workspace. workspaces use is an alias; workspace (singular) aliases the whole group.

MCP

Install Floom’s MCP server into your agent, or manage which Floom server is active. See the MCP reference for the full tool list.

floom mcp install --target <client>
Add Floom to an MCP client config. Targets: claude, cursor, vscode, windsurf, continue, generic. mcp add is an alias.
floom mcp uninstall --target <client>
Remove Floom from a client config.
floom mcp list
List configured MCP servers (the active one is marked).
--jsonMachine-readable.
floom mcp switch <name>
Set the active MCP server (for multi-server setups).
floom mcp test [name]
Probe a server (initialize + list its tools). Defaults to the active server.
--jsonMachine-readable.

Utility

floom completion <shell>
Print a shell completion script (bash, zsh, or fish).
floom install --target <client>
Deprecated alias for mcp install.