preflight

Validate the project config, detect runtimes, and check deploy readiness, with no side effects. Local checks need no authentication. For an authenticated existing app, preflight also returns the read-only server plan, including the runtime values floo will apply.

Pushing is the deploy. After floo apps github connect, every git push to your default branch deploys to dev. Run floo preflight before that push. See git-push deploys for the trigger table.

floo preflight [PATH]

Arguments

Argument	Description	Default
`PATH`	Project directory to validate	`.` (current directory)

Flags

Flag	Description
`--app APP`	Existing app name to validate against
`--service NAME`	Validate only specific services (repeatable or comma-separated)
`--env ENV`	Resolve runtime defaults for `dev`, `prod`, or `preview` (default: `dev`)

Examples

# Validate current directory
floo preflight

# Validate with JSON output (for agents)
floo preflight --json

# Validate a specific directory
floo preflight ./my-project

# Validate specific services only
floo preflight --service api --service web

# Inspect locally resolved production defaults
floo preflight --env prod --json

What it checks

Config files: reads floo.app.toml (and any per-service floo.service.toml in a delegated layout) and validates structure
Service discovery: resolves all services, checks for duplicates and naming rules
Port validation: verifies ports are set and match Dockerfile EXPOSE directives
Runtime detection: scans project files to determine language and framework
Env file check: verifies referenced env_file paths exist on disk
Env injection plan: shows each service’s managed attachments, generated env keys, required keys, and optional keys
Runtime plan: shows the on-demand, warm, fixed, or paused mode; configured and locally resolved scaling values; CPU allocation; and whether server resolution is still required. With authentication, plan.runtime_services contains the exact result for --env.
Managed services: reconciles config declarations against platform state:
- to_provision: declared, no row yet. The next deploy creates it.
- to_retain: declared and present. Safe declared fields are reconciled.
- to_retry: declared, but the row is failed. The next deploy retries it.
- to_deprovision: previously config-declared, now removed, so floo proposes deleting it. Review is required only under an explicit approval policy; by default the resource is retained with no teardown schedule. Deploy never deletes its data.
- to_orphan: present but never config-declared, such as a CLI-added row. It stays live until explicitly removed.
- in_flight_deprovisioning: terminal deletion is in progress.

JSON output

{
  "success": true,
  "data": {
    "app": "my-app",
    "services": [
      {
        "name": "web",
        "path": ".",
        "port": 3000,
        "type": "web",
        "ingress": "public",
        "runtime": "nodejs",
        "framework": "Next.js",
        "confidence": "high"
      }
    ],
    "runtime_plan": [
      {
        "service": "web",
        "service_type": "web",
        "env": "dev",
        "availability": "on_demand",
        "configured": {
          "min_instances": null,
          "max_instances": null,
          "instances": null
        },
        "locally_resolved": {
          "min_instances": 0,
          "max_instances": 3,
          "instances": null
        },
        "sources": {
          "min_instances": "platform_default",
          "max_instances": "platform_default",
          "instances": null
        },
        "cpu_allocation": "request_based",
        "cpu_allocation_reason": "http_request_scoped",
        "server_resolution_required": true,
        "notes": []
      }
    ],
    "managed_services": [
      {
        "name": "postgres",
        "tier": "basic"
      }
    ],
    "env_injection_plan": {
      "mode": "explicit",
      "services": [
        {
          "service": "web",
          "managed": [],
          "required": [],
          "optional": []
        },
        {
          "service": "api",
          "managed": [
            {
              "handle": "postgres",
              "keys": ["DATABASE_URL", "PGHOST", "PGPORT", "PGDATABASE", "PGUSER", "PGPASSWORD"]
            }
          ],
          "required": ["STRIPE_SECRET_KEY"],
          "optional": []
        }
      ],
      "notes": []
    },
    "cron": [],
    "findings": [],
    "plan": null,
    "valid": true
  }
}

findings lists every error and warning the local checks produced. plan is the read-only server plan and is null without authentication or an existing app. When the config is invalid the payload is {"success": false, "error": {...}, "data": {...}} with the same data keys, so agents read findings either way. An omitted HTTP minimum resolves locally to 0 with source platform_default in every environment, including --env prod, with no note. The local plan does not apply server-side maximums; when authenticated, data.plan.runtime_services holds effective values and sources after those maximums. A null source means the field does not apply to that service type. After deploy, verify the applied contract with floo services show <name> --env dev|prod --json. See Scaling and Availability.

Errors

Code	Meaning
`INVALID_PATH`	Path is not a valid directory
`NO_CONFIG_FOUND`	No `floo.app.toml` found. Run `floo init` first
`CONFIG_INVALID`	Validation failed (duplicate service names, invalid ports, etc.)
`SERVICE_CONFIG_MISSING`	A delegated service declared in `floo.app.toml` is missing its `floo.service.toml`

CLI

Config and runtime

Errors

API

Arguments

Flags

Examples

What it checks

JSON output

Errors

​Arguments

​Flags

​Examples

​What it checks

​JSON output

​Errors

Arguments

Flags

Examples

What it checks

JSON output

Errors