Skip to main content
The Floo CLI is the primary operational surface for the deployment platform. Use this page to understand how the binary behaves before you dive into command-specific reference pages.

​
Output Contract

Every command supports two modes:

​
Human mode

  • human-oriented output goes to stderr
  • tables, progress, warnings, and success messages stay readable in a terminal
  • stdout is kept clean unless a command intentionally prints raw data

​
JSON mode

floo apps list --json
  • JSON goes to stdout
  • human-oriented progress still goes to stderr
  • success responses use { "success": true, "data": ... }
  • failures use { "success": false, "error": { "code": "...", "message": "...", "suggestion": "..." } }
This split is why floo ... --json 2>/dev/null works well for agents.

​
App Inference

Most app-scoped commands can infer the app from local config. The shipped CLI resolves app context in this order:
  1. --app <name>
  2. nearest floo.service.toml
  3. nearest floo.app.toml
If you are outside the repo, targeting a different app, or dealing with multiple configs, pass --app explicitly.

​
Dry Run

Use --dry-run when you want to validate without mutating anything. 
floo preflight --json
The current binary supports dry run for:
  • redeploy
  • preflight
  • env set
  • env remove
  • env import
  • apps delete
  • domains add
  • domains remove
  • deploys rollback

​
Self-Discovery

Use the CLI itself when you want the most accurate picture of the shipped surface: 
floo --help
floo <command> --help
floo docs
floo commands --json
Built-in doc topics: floo docs services, floo docs config, floo docs deploy. Use floo commands --json for the full machine-readable command tree.

​
Configuration Files

The CLI reads these files:
  • floo.app.toml — primary config file. Services are declared inline under [services.<name>]; managed services (Postgres, Redis, Storage) are top-level sections.
  • 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

AreaCommands
setupfloo auth, floo init, floo version
deploysfloo preflight, floo redeploy, floo deploys watch, floo deploys rollback
local devfloo dev, floo run
app operationsfloo apps, floo env, floo domains, floo logs
release and billingfloo releases, floo billing, floo analytics
discoveryfloo docs, floo commands, floo update

​
Deploy Flow

Pushing to GitHub triggers a deploy automatically. Watch it with floo deploys watch: 
git push origin main
floo deploys watch --app my-app
Use floo redeploy only to force a redeploy without a code change — for example, after updating env vars: 
floo env set API_KEY=new-value --app my-app
floo redeploy --app my-app

​
Agent Pattern

The most common agent flow is: 
floo commands --json 2>/dev/null | jq '.data.commands'
git push origin main && floo deploys watch --app my-app --json 2>/dev/null
Use the command tree for capability discovery, then push and watch in JSON mode.