init

Initialize a new floo project by creating a floo.app.toml config file with your service declared inline.

floo init [NAME]

Arguments

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

Flags

Flag	Description	Default
`--path PATH`	Project directory	`.` (current directory)

Behavior

In interactive mode (default), floo init prompts for app name, service name, port, and type. It auto-detects your runtime (Node.js, Python, Go, static) and suggests defaults. In non-interactive mode (--json), NAME is required. Detection runs automatically and defaults are applied without prompts. Creates:

floo.app.toml — app-level configuration with your services declared inline (name, port, type, build settings). The file leads with a header comment that points to the git push deploy contract and shows where access_mode lives, so you don’t have to leave the file to find either.
Dockerfile — when one isn’t already present and the detected runtime has a template
AGENTS.md — operating notes for AI coding assistants working in this repo (only when no AGENTS.md already exists)

What happens next

floo init doesn’t deploy. After the file is written:

Connect your GitHub repo: floo apps github connect <owner/repo>. This installs the webhook that auto-deploys on push.
git push to your default branch — that’s the deploy. Every subsequent push deploys to dev automatically.
Cut a GitHub release when you’re ready to promote a build to production.

You don’t need to run floo deploy in the regular flow. It exists for ad-hoc rebuilds (floo redeploy --rebuild) and edge cases.

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
`requirements.txt` / `pyproject.toml`	Python	FastAPI, Flask, Django
`go.mod`	Go	—
`index.html` (no backend)	Static	—

JSON output

{
  "success": true,
  "data": {
    "app_name": "my-app",
    "files_written": ["floo.app.toml", "Dockerfile"],
    "detection": {
      "runtime": "nodejs",
      "framework": "Next.js",
      "confidence": "high"
    },
    "service": {
      "name": "web",
      "type": "web",
      "port": 3000
    }
  }
}

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

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