> ## Documentation Index
> Fetch the complete documentation index at: https://getfloo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Overview

> Output modes, app inference, preflight, and the quickest way to find the right floo command.

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

```bash theme={null}
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.

```bash theme={null}
floo preflight --json
```

The current binary supports dry run for:

* `redeploy`
* `preflight`
* `env set`
* `env unset`
* `env import`
* `apps delete`
* `domains add`
* `domains remove`
* `cron run`
* `deploys rollback`
* `update` (preview the release that would be installed without overwriting the binary)

## Self-Discovery

Use the CLI itself when you want the most accurate picture of the shipped surface:

```bash theme={null}
floo --help
floo <command> --help
floo docs
floo commands --json
```

Built-in doc topics: `floo docs services`, `floo docs previews`, `floo docs config`, `floo docs cron`, `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 app-shape config file. Services are declared inline under `[services.<name>]`; managed service credential attachments live under service env blocks.
* `.floo/services.lock` — generated record of managed-service mutations. Commit it, but do not hand-edit it.
* `floo.service.toml` — optional per-service file used only in the delegated multi-service layout.
* `~/.floo/config.json` — auth and API settings.

See [Configuration](/docs/guides/configuration) for config shapes and [Config File Spec](/docs/reference/config-spec) for resolution rules.

## Most-Used Command Families

| Area                | Commands                                                                                                                                                                                                   |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| setup               | [`floo auth`](/docs/cli/auth), [`floo init`](/docs/cli/init), [`floo version`](/docs/cli/update#version)                                                                                                                  |
| deploys             | [`floo preflight`](/docs/cli/preflight), [`floo redeploy`](/docs/cli/redeploy), [`floo deploys watch`](/docs/cli/deploys#floo-deploys-watch), [`floo deploys rollback`](/docs/cli/deploys#floo-deploys-rollback-app-deploy_id) |
| local dev           | [`floo dev`](/docs/cli/dev), [`floo run`](/docs/cli/run)                                                                                                                                                             |
| app operations      | [`floo apps`](/docs/cli/apps), [`floo env`](/docs/cli/env), [`floo domains`](/docs/cli/domains), [`floo edge`](/docs/cli/edge), [`floo cron`](/docs/cli/cron), [`floo logs`](/docs/cli/logs)                                             |
| previews            | [`floo previews`](/docs/cli/previews), [`floo db branches`](/docs/cli/database#branches-list)                                                                                                                        |
| release and billing | [`floo releases`](/docs/cli/releases), [`floo billing`](/docs/cli/billing), [`floo analytics`](/docs/cli/analytics)                                                                                                       |
| discovery           | `floo docs`, `floo commands`, [`floo update`](/docs/cli/update)                                                                                                                                                 |

## Deploy Flow

Pushing to GitHub triggers a deploy automatically. Watch it with `floo deploys watch`:

```bash theme={null}
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:

```bash theme={null}
floo env set API_KEY=new-value --app my-app
floo redeploy --app my-app
```

## Agent Pattern

The most common agent flow is:

```bash theme={null}
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.

For branch sandboxes, push the branch first and create a preview:

```bash theme={null}
git push origin feat/foo
floo previews up --app my-app --branch feat/foo --wait --json 2>/dev/null
```