Add floo to Your AI Tool

floo skills install --path .claude/skills/floo

# floo CLI

floo deploys web apps from the terminal. All management happens through `floo` commands.

## Getting Started

1. `floo auth login --api-key <key>` — authenticate (use `--api-key` for non-interactive/CI; omit for browser flow)
2. `floo init <app-name>` — scaffold config files in the current directory
3. `floo deploy` — detect runtime, build, deploy
4. `floo apps status <name>` — see your app's URL and status

## Config Files

Single-service app — `floo.service.toml` in project root:

\`\`\`toml
[app]
name = "my-app"

[service]
name = "web"
port = 3000
type = "web"          # web | api | worker
ingress = "public"    # public | internal
env_file = ".env"     # optional, synced on deploy
\`\`\`

Multi-service app — `floo.app.toml` in project root, plus a `floo.service.toml` in each service dir:

\`\`\`toml
[app]
name = "my-app"

[services.api]
path = "./api"

[services.web]
path = "./web"
\`\`\`

## Self-Discovery

The CLI is fully self-documenting:

- `floo --help` — all commands
- `floo <command> --help` — command details with examples
- `floo docs` — platform overview (services, deploys, config)
- `floo commands --json` — structured command tree for agents

## Agent Output

Every command supports `--json`. JSON goes to stdout, human output to stderr.

\`\`\`bash
floo deploy --json 2>/dev/null | jq '.data.deploy.url'
\`\`\`

Success: `{"success": true, "data": {...}}`
Error: `{"success": false, "error": {"code": "...", "message": "...", "suggestion": "..."}}`

## The `--app` Flag

Most commands infer the app name from config files in the current directory. Use `--app <name>` to override or when running outside the project directory.

## Dry Run

`--dry-run` previews what a command will do without executing it. Supported on: `deploy`, `env set/remove/import`, `apps delete`, `domains add/remove`, `deploy rollback`.

\`\`\`bash
floo deploy --dry-run --json    # preview deploy without executing
\`\`\`

## Common Workflows

### Environment Variables

\`\`\`bash
floo env set API_KEY=secret --app my-app              # set a var
floo env set DB_URL=... --app my-app --restart         # set and restart
floo env list --app my-app --json                      # list all vars
floo env import .env --app my-app                      # import from file
floo env remove SECRET --app my-app                    # remove a var
\`\`\`

### Logs and Debugging

\`\`\`bash
floo logs --app my-app                             # last 100 lines
floo logs --app my-app --since 1h --error          # errors in last hour
floo logs --app my-app --live                      # stream real-time
floo logs --app my-app --search "panic" --json     # search + JSON
\`\`\`

### Deploy Management

\`\`\`bash
floo deploy list --app my-app                      # deploy history
floo deploy logs <deploy-id> --app my-app          # build logs
floo deploy watch --app my-app                     # stream progress
floo deploy rollback my-app <deploy-id>            # rollback
floo deploy --restart --app my-app                 # restart without rebuilding
\`\`\`

### Custom Domains

\`\`\`bash
floo domains add app.example.com --app my-app
floo domains list --app my-app
\`\`\`

# floo Deployment

This project deploys to floo. Use the `floo` CLI for all deployment operations.

## Key Commands
- `floo deploy` — Deploy current directory to production
- `floo deploy --json` — Deploy with structured JSON output
- `floo apps list` — List all deployed apps
- `floo apps status <app>` — Get app details
- `floo env set KEY=value --app <app>` — Set environment variable
- `floo env list --app <app>` — List environment variables
- `floo logs --app <app>` — View runtime logs
- `floo logs --app <app> --error --json` — Get structured error logs
- `floo deploy rollback <app> <deploy-id>` — Rollback to previous deploy
- `floo domains add <domain> --app <app>` — Add custom domain

## JSON Output Contract
Every command supports `--json`. Output goes to stdout as:
- Success: {"success": true, "data": {...}}
- Error: {"success": false, "error": {"code": "...", "message": "...", "suggestion": "..."}}

Human-readable output (spinners, colors) goes to stderr.
Use `floo <command> --json 2>/dev/null` to get clean JSON.

## Error Handling
Parse the `error.code` field: NOT_AUTHENTICATED, APP_NOT_FOUND, DEPLOY_FAILED, INVALID_FORMAT, NO_RUNTIME_DETECTED.
Each error includes a `suggestion` field with the recommended fix.