Skip to main content
The floo CLI is the primary operational surface. This page covers behavior shared by every command.

​
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

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

​
Preflight

Use --preflight when you want to preview a supported mutation without applying it. A command’s help lists the flag only when that command implements a preview. --dry-run remains a hidden compatibility alias; use --preflight in new work.
Run floo <command> --help to check whether a mutation supports --preflight. The shipped command tree is the source of truth, so new preview-capable commands appear there without waiting for this page to change.

​
Self-discovery

Use the CLI itself when you want the most accurate picture of the shipped surface:
floo docs lists the topics and floo commands --json returns the full machine-readable command tree. See commands and docs for both output shapes and the discovery order to use them in.

​
Configuration files

The CLI reads these files:
  • floo.app.toml: primary app-shape config file. 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

​
Deploy flow

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

​
Agent pattern

The most common agent flow is:
Use the command tree for capability discovery, then push and watch in JSON mode. For branch sandboxes, push the branch first and create a preview: