CLI

Drive Floom from your terminal: the floom command.

Install

The CLI ships as @floomhq/floom. Use floom as the primary binary; workeros is installed as a compatibility alias. It needs Node.js 20+.

For agent clients, mcp install is the full hosted setup: it uses Floom Cloud by default, opens login only when needed, and writes the client config for your active workspace.

$ npx -y @floomhq/floom mcp install --target claude

$ 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.

Pair the CLI with your Floom Cloud account using the browser-approved device flow (see Authentication). Credentials are stored at ~/.config/floom/credentials.json. Hosted Cloud is the default; use local mode only when you are running your own Floom API.

floom login --cloud

Pair with Floom Cloud via the device flow.

--cloudTarget the hosted product (default).

floom login --local

Pair with a local or self-hosted Floom API.

--localTarget a local/self-hosted API.

floom logout

Clear saved credentials.

floom whoami

Show the current identity: user, active workspace, and API base.

--jsonMachine-readable.

floom auth list

List saved accounts.

--jsonMachine-readable.

floom auth login

Add or refresh a saved account via the device flow.

--cloud, --localChoose hosted cloud or local/self-hosted auth.

floom auth switch <account>

Set the active saved account.

floom auth status

Show the current auth identity.

--jsonMachine-readable.

floom auth logout [account]

Remove one saved account, or all credentials if no account is supplied.

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.

--jsonMachine-readable.

floom workers contract

Print the canonical worker authoring contract for agents.

--jsonMachine-readable.

floom workers templates list

List golden worker templates.

--jsonMachine-readable.

floom workers templates get <id>

Show a worker template.

--jsonMachine-readable.

floom workers validate <dir>

Validate a local worker directory before pushing (checks worker.yml and the entrypoint).

--jsonMachine-readable.

floom workers push <dir>

Create or update a worker from a local directory.

floom workers delete <id>

Permanently delete a worker and its runs/artifacts. workers rm is an alias.

-y, --yesSkip confirmation.

--jsonMachine-readable.

floom workers disable <id>

Disable a worker while keeping it in the workspace.

--jsonMachine-readable.

floom workers enable <id>

Re-enable a disabled worker.

--jsonMachine-readable.

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. There is no separate approvals command: a run that needs your sign-off shows up in runs list, and you resolve it with runs approve <id>, runs reject <id>, or runs cancel <id>.

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.

Contexts

Manage brain pack context folders and the files workers can read at run time.

floom contexts list

List brain packs.

--jsonMachine-readable.

floom contexts create <name>

Create a brain pack.

--writeableAllow workers to write to this brain pack.

--no-sensitiveEnable git version history for this brain pack.

--jsonMachine-readable.

floom contexts read <name> <path>

Read a UTF-8 file from a brain pack.

--jsonMachine-readable.

floom contexts write <name> <path>

Write a UTF-8 file into a brain pack.

--content <text>Text content to write.

--file <path>Read text content from a local file.

--jsonMachine-readable.

floom contexts upload <name> <file>

Upload a local file into a brain pack.

--path <path>Destination path inside the brain pack.

--jsonMachine-readable.

floom contexts delete <name>

Delete a brain pack.

--forceDelete even when workers reference this brain pack.

--jsonMachine-readable.

floom contexts delete-file <name> <path>

Delete one file from a brain pack.

--jsonMachine-readable.

floom contexts versions <name>

List brain pack version history.

--limit <n>Number of versions.

--jsonMachine-readable.

floom contexts rollback <name> <version-id>

Restore a brain pack to a previous version.

--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>

--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. On hosted Cloud, install reuses saved credentials or starts login if none are valid. 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.

--show-tokenPrint live credentials in generic output.

floom mcp add --target <client>

Alias for mcp install.

--show-tokenPrint live credentials in generic output.

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.

Support & feedback

floom support file

File a support ticket.

--subject <subject>Ticket subject.

--body <body>First message body.

--severity <severity>low | normal | high.

--operation <op>Operation that failed.

--error-code <code>Error code.

--jsonMachine-readable.

floom support list

List your support tickets.

--status <status>Filter by status: open | resolved.

--limit <n>Max rows.

--jsonMachine-readable.

floom support get <ticketId>

Show a ticket and its message thread.

--jsonMachine-readable.

floom support reply <ticketId>

Reply to a ticket and reopen it if it was resolved.

--body <body>Reply text.

--jsonMachine-readable.

floom support ack <ticketId>

Clear the unread flag on a ticket.

--jsonMachine-readable.

floom feedback

Send feedback as a support ticket with an optional transcript.

--message <message>Your feedback.

--severity <severity>low | normal | high.

--transcript <path>Path to the session transcript to attach.

--no-transcriptDo not attach the session transcript.

--jsonMachine-readable.

Utility

floom completion <shell>

Print a shell completion script (bash, zsh, fish, or powershell).

floom install

Deprecated alias for mcp install.

Install

Login & identity

Workers

Runs

Contexts

Secrets

Connections

Workspaces

MCP

Support & feedback

Utility