CLI overview

An agent drives floo through the CLI (every command takes --json) or the HTTP API at https://api.getfloo.com/v1, starting from getfloo.com/agents.md. This reference documents the CLI; this page covers behavior shared by every command.

Output contract

Every command supports two modes:

Human mode

tables, progress, warnings, and success messages go to stderr
stdout stays clean unless a command prints raw data (for example floo auth token)

JSON mode

floo apps list --json

JSON goes to stdout
progress still goes to stderr
success responses use { "success": true, "data": ... }
failures use { "success": false, "error": { "code": "...", "message": "...", "suggestion": "..." } }

So floo ... --json 2>/dev/null leaves an agent only the JSON.

App inference

App-scoped commands infer the app from local config, in this order:

--app <name>
The nearest directory containing either config file, walking up to a .git boundary.
If that directory contains both files, floo.service.toml wins; conflicting app names are an error.

Outside the repo, for a different app, or with multiple configs, pass --app.

Preflight

--preflight previews a mutation without applying it. A command’s --help lists the flag only when that command implements a preview. --dry-run is a hidden compatibility alias; use --preflight.

floo preflight --json

floo preflight is a separate command that validates the project config; see preflight.

Self-discovery

The installed CLI describes its own surface:

floo --help
floo <command> --help
floo docs
floo commands --json

floo docs lists the topics; floo commands --json returns the full command tree. See commands and docs for both output shapes and the discovery order.

Configuration files

floo.app.toml: the app config. Services are declared inline under [services.<name>]; managed-service credential attachments live under service env blocks.
floo.service.toml: optional per-service file, used only in the delegated multi-service layout.
~/.floo/config.json: auth and API settings.

See Configuration for config shapes and Config File Spec for resolution rules.

Most-used command families

Area	Commands
setup	`floo auth`, `floo init`, `floo version`
deploys	`floo preflight`, `floo redeploy`, `floo deploys watch`, `floo deploys rollback`
local dev	`floo dev`, `floo run`
app operations	`floo apps`, `floo env`, `floo domains`, `floo edge`, `floo cron`, `floo logs`
preferences and support	`floo notifications`, `floo feedback`
stateful recovery	`floo storage`, `floo db`, `floo events`
previews	`floo previews`, `floo previews resources`
release and billing	`floo releases`, `floo billing`, `floo analytics`
discovery	`floo commands` and `floo docs`, `floo version` and `floo update`

Deploy flow

Push to GitHub to deploy. Use floo redeploy only to redeploy without a code change. See CLI commands: Ship changes.

Agent pattern

floo commands --json 2>/dev/null | jq '.data.commands'
git push origin main
floo deploys status --app my-app --json 2>/dev/null

Discover commands from the tree, then push and inspect the latest deploy in JSON mode. Check its commit SHA against the commit you pushed; repeat the status read until that deploy finishes. For a branch sandbox, push the branch first, then create a preview:

git push origin feat/foo
floo previews up --app my-app --branch feat/foo --wait --json 2>/dev/null

​Output contract

​Human mode

​JSON mode

​App inference

​Preflight

​Self-discovery

​Configuration files

​Most-used command families

​Deploy flow

​Agent pattern