Skip to main content
Initialize a new floo project by creating a floo.app.toml config file with your service declared inline. 
floo init [NAME]

​
Arguments

ArgumentDescription
NAMEApp name. Prompted interactively if omitted. Required in --json mode.

​
Flags

FlagDescriptionDefault
--path PATHProject 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:
  1. Connect your GitHub repo: floo apps github connect <owner/repo>. This installs the webhook that auto-deploys on push.
  2. git push to your default branch — that’s the deploy. Every subsequent push deploys to dev automatically.
  3. 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

FileRuntimeFramework
package.json + nextNode.jsNext.js
package.json + viteNode.jsVite
package.json + expressNode.jsExpress
requirements.txt / pyproject.tomlPythonFastAPI, Flask, Django
go.modGo—
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

CodeMeaning
INVALID_PATHPath is not a valid directory
CONFIG_EXISTSfloo.app.toml already exists in the target directory
MISSING_APP_NAMENAME argument is required in --json mode