preflight - floo

Validate your project config, detect runtimes, and check deploy readiness. Local checks require no authentication. For an authenticated existing app, preflight also returns the read-only server plan, including tier-aware runtime defaults. The command has no side effects.

Pushing is the deploy. After floo apps github connect, every git push to your default branch deploys to dev automatically. floo preflight is the local check you run before that push. There is no separate CLI deploy step in the everyday flow. See git-push deploys for the full 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 on-demand, warm, fixed, or paused posture; configured and locally resolved scaling values; CPU allocation; and whether server resolution is still required. With authentication, plan.runtime_services contains the exact tier-aware 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. This is tier-3. Review is required only under an explicit approval policy. The default retains the resource without a 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",
        "environment": "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 guess organization-plan clamps. When authenticated, data.plan.runtime_services contains effective values and their sources after applying plan limits. After deploy, use floo services show <name> --env dev|prod --json to verify the applied contract. A null source means the field does not apply to that service type. 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`

​Arguments

​Flags

​Examples

​What it checks

​JSON output

​Errors

Arguments

Flags

Examples

What it checks

JSON output

Errors