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 deploy --dry-run --json
The current docs and binary support dry run for:
  • deploy
  • env set
  • env remove
  • env import
  • apps delete
  • domains add
  • domains remove
  • deploy 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.service.toml for single-service apps
  • floo.app.toml for multi-service apps, app-level overrides, and managed services
  • ~/.floo/config.json for 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 deploy, floo deploy watch, floo deploy rollback
local devfloo dev
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 deploy watch: 
git push origin main
floo deploy watch --app my-app
Use floo deploy (without watch) 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 deploy --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 deploy watch --app my-app --json 2>/dev/null
Use the command tree for capability discovery, then push and watch in JSON mode.