init

Write a floo.app.toml with your service declared inline.

floo init [NAME]

Arguments

Argument	Description
`NAME`	App name. Prompted interactively if omitted. Required in non-interactive mode.

Flags

Flag	Description	Default
`--path PATH`	Project directory	`.` (current directory)
`--preflight`	Print the files and scaffold `init` would write, without writing them. Never prompts; generates a name if `NAME` is omitted.	off

Behavior

In a terminal, floo init prompts for app name, service name, port, and type, with defaults from runtime detection. With --json or without a TTY, NAME is required and detected defaults are applied without prompts. Creates:

floo.app.toml: app config with your services declared inline (name, port, type, build settings). A header comment points to the git push deploy contract and shows where access_mode lives.
AGENTS.md: operating notes for agents working in this repo, only when none exists

floo init does not write a Dockerfile. When the project has none, it says so and links Dockerfiles, which has one to copy for each common stack.

What happens next

floo init doesn’t deploy. Next:

Edit floo.app.toml and run floo preflight.
Commit and git push the generated files to your default branch.
Run floo apps github connect <owner/repo>. It creates the app, installs the webhook, and deploys the pushed source.
Publish to production with gh release create <tag> --repo <owner/repo>. See Releases for dev validation and migration behavior.

floo redeploy --rebuild is only for an ad-hoc rebuild from connected GitHub source.

Examples

# Interactive: prompts for name, port, type
floo init

# Non-interactive with explicit name
floo init my-app --json

# Initialize in a specific directory
floo init my-app --path ./my-project

# Agent workflow: init and extract detected runtime
floo init my-app --json 2>/dev/null | jq -r '.data.detection.runtime'

Runtime auto-detection

File	Runtime	Framework
`package.json` + `next`	Node.js	Next.js
`package.json` + `vite`	Node.js	Vite
`package.json` + `express`	Node.js	Express
`package.json` + `fastify`	Node.js	Fastify
`requirements.txt` / `pyproject.toml`	Python	FastAPI, Flask, Django
`go.mod`	Go	none
`index.html` (no backend)	Static	none
`Dockerfile` (checked first)	Docker	none

JSON output

{
  "success": true,
  "data": {
    "app_name": "my-app",
    "files_written": ["floo.app.toml", "AGENTS.md"],
    "detection": {
      "runtime": "nodejs",
      "framework": "Next.js",
      "version": "^14.0.0",
      "confidence": "high",
      "reason": "..."
    },
    "service": {
      "name": "web",
      "type": "web",
      "port": 3000
    },
    "agents_md_written": true,
    "hint": "Edit floo.app.toml to configure your services — run 'floo docs config' for the schema",
    "next_step": "Run 'floo preflight --json', commit and push the generated files, then connect GitHub with 'floo apps github connect <owner/repo>'."
  }
}

When the project has no Dockerfile, data adds a suggestion with the link to Dockerfiles.

Errors

Code	Meaning
`INVALID_PATH`	Path is not a valid directory
`CONFIG_EXISTS`	`floo.app.toml` already exists in the target directory
`MISSING_APP_NAME`	`NAME` argument is required in `--json` mode

CLI

Config and runtime

Errors

API

Arguments

Flags

Behavior

What happens next

Examples

Runtime auto-detection

JSON output

Errors

​Arguments

​Flags

​Behavior

​What happens next

​Examples

​Runtime auto-detection

​JSON output

​Errors

Arguments

Flags

Behavior

What happens next

Examples

Runtime auto-detection

JSON output

Errors