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

# AI Agent Setup

> Use the Floo CLI as the canonical agent surface for deploy, operations, and debugging.

Today, the Floo CLI is the canonical agent surface. It is self-documenting, every output-producing command supports `--json`, and config lives in the repo where agents can read and write it safely.

## Install the skill

```bash theme={null}
floo skills install
```

Your agent now has the Floo command reference, config shapes, and common workflows.

## What agents should treat as the source of truth

* `floo.app.toml` defines app shape in git
* GitHub is the source of code for deploys
* the CLI is the primary control plane
* the dashboard is a window into live state, not a second config system

## Allow safe read-only commands

Add Floo to your agent's allowed commands so it can inspect state without prompting you every time.

**Claude Code** (`.claude/settings.json`):

```json theme={null}
{
  "permissions": {
    "allow": [
      "Bash(floo apps *)",
      "Bash(floo env list *)",
      "Bash(floo logs *)",
      "Bash(floo deploys list *)",
      "Bash(floo releases *)",
      "Bash(floo domains list *)",
      "Bash(floo services list *)",
      "Bash(floo analytics *)",
      "Bash(floo auth whoami *)"
    ]
  }
}
```

## Give other tools the same rules

**Cursor** (`.cursorrules`):

```text theme={null}
# floo deployment

Use the `floo` CLI for deployment and operations.
Config in `floo.app.toml` is the source of truth.
GitHub is the deploy source of code.
Every output-producing command supports `--json`.

Key commands:
- floo apps status <app>
- floo env set KEY=value --app <app>
- floo logs --app <app>
- floo deploys rollback <app> <deploy-id>
- floo redeploy --app <app>
```

**Other tools**:

| Tool           | File                              |
| -------------- | --------------------------------- |
| Windsurf       | `.windsurfrules`                  |
| GitHub Copilot | `.github/copilot-instructions.md` |

## Parse the output contract

Use JSON mode whenever the agent needs structured data:

```bash theme={null}
floo apps list --json 2>/dev/null
floo logs --app my-app --error --json 2>/dev/null
floo redeploy --app my-app --json 2>/dev/null
```

Success shape:

```json theme={null}
{"success": true, "data": {...}}
```

Error shape:

```json theme={null}
{"success": false, "error": {"code": "...", "message": "...", "suggestion": "..."}}
```

## Recommended agent workflow

1. Read or update config in the repo.
2. Use `floo commands --json` or `floo <command> --help` for capability discovery.
3. Trigger or observe deploys from the CLI.
4. Use logs, analytics, releases, and rollbacks from the same surface.

For the control-plane split, see [Dashboard vs CLI](/docs/guides/dashboard-vs-cli).