Skip to main content
An agent drives floo through either of two equal surfaces: the floo CLI, where every output-producing command supports --json, or the HTTP API at https://api.getfloo.com/v1. Config lives in the repo, where the agent reads and writes it either way.
  • CLI agents install the CLI and run floo auth login. The CLI is self-documenting.
  • API agents start at getfloo.com/agents.md and sign in with the device flow in its step 1. Every operation is in the spec at https://api.getfloo.com/openapi.json, which generates the API group of the Reference tab.
Both sign in through the same device flow: the user approves on their own device.

​
Install the skill

For CLI agents. This installs one short floo skill that points here, to the quickstart, and to the documentation index. Platform guidance lives on this website; installed command help owns version-matched syntax. Connecting through floo auth login delegates your existing workspace authority by default, including production and explicit destructive operations, on every account and plan. Existing roles, deliberately restricted keys, and explicit org/app approval policies still apply. Your agent can use the CLI’s non-interactive confirmation flags within the work you delegate; its host may have separate approval settings.

​
What agents treat as the source of truth

  • floo.app.toml defines app shape in git
  • GitHub is the source of code for deploys
  • the CLI and the HTTP API are the control plane
  • the dashboard is a window into live state, not a second config system

​
Allow floo commands

For CLI agents. To let Claude carry out delegated floo work without repeated host prompts, allow floo commands in its settings. floo still enforces your account permissions and any explicitly configured approval policy. Claude Code (.claude/settings.json):

​
Give other tools the same rules

For tools that read a project instruction file, add a link to this guide:
Keep project-specific instructions in that file and platform guidance here.

​
Parse the output contract

CLI agents use JSON mode for structured data:
Success shape:
Error shape:
Over the HTTP API, a failed call’s detail.code names the error and detail.message the next step. Give agents floo deploys status --app my-app --json, not floo deploys watch. watch, deploys logs --follow, and logs tail stream build and runtime output, which can carry secret-shaped values into a transcript. status returns the deploy id, commit, phase booleans, gateway URL, and the next command without build logs. watch is for a human reader. API agents follow the same loop in agents.md. CLI agents follow the quickstart’s GitHub handoff: confirm the intended floo organization, have the user install the GitHub App on the repository’s owner and select the repo, then run floo apps github setup --no-browser. Give its link to the user to authorize floo with GitHub and wait for confirmation. After pushing the config, run connect --no-browser and verify the repository and deploy. Installation, linking the floo organization, and connecting the repository are separate steps.
  1. Run floo commands --json, then exact command help, then floo docs <topic> --json. See commands and docs.
  2. Read or update floo.app.toml and run floo preflight --json.
  3. Commit and push config before the first floo apps github connect; connect creates the app and deploys pushed GitHub source.
  4. Observe deploys and use logs, analytics, releases, and rollbacks from the CLI.
For the control-plane split, see Dashboard vs CLI.

​
Verify changes

Resolve the app, environment, and resource before a mutation. Use --preflight where supported, review the proposed change, and confirm the result with the resource’s read-only command. After config changes, run floo preflight --json and inspect the Git diff. After a deploy, use floo deploys status --json, check the intended revision, and verify the authenticated app URL. A successful deploy does not prove the app works. For service changes, follow service lifecycle verification. For custom domains, follow DNS verification. Stop and investigate when the resulting state differs from intent. Existing delegation authorizes work within its scope. Use supported confirmation flags for an explicitly delegated destructive operation; ask when the target or operation is outside that scope or the host requires approval. Explicit platform approval policies still apply. Removing a declaration alone does not authorize provider-data deletion. See managed-service removal.

​
Protect credentials and application boundaries

Keep secrets out of source, committed .env files, floo TOML, browser bundles, logs, errors, and transcripts. Use stdin or a value file with write-only secret mode, then verify keys and metadata. Read required credentials from the runtime environment and fail closed if they are absent. See environment variables. Consume managed connection values as provided. Use parameterized queries and least-privilege application roles, never platform or database administrator credentials. Keep dev, prod, and preview credentials separate. Return generic client errors with sanitized diagnostics internally. Use the hosted identity contract for gateway-managed accounts; do not add a second password or session system. If the app owns its sessions, use secure, HTTP-only cookies with bounded lifetimes and server-side validation. Keep bearer tokens out of browser local storage, restrict CORS to intended origins, and keep TLS verification enabled. For managed projects, use the managed-project workflow. Never cache GitHub tokens or configure global Git credentials. The internal Git credential helper emits a plaintext password protocol; keep its output out of logs and transcripts. A push applies access changes in floo.app.toml, including making a route or the app public. If your org or app has an approval policy that gates access broadening, repository write access alone cannot broaden access: after pushing the dev change, an authorized floo org-admin agent runs floo redeploy --app <app> --rebuild with an admin-scoped credential to apply the current GitHub default-branch HEAD. Explicit infrastructure-review policies still apply.