> ## Documentation Index
> Fetch the complete documentation index at: https://getfloo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# init

> CLI reference: floo init — initialize a new floo project

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

```bash theme={null}
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:

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

```bash theme={null}
# 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

```json theme={null}
{
  "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           |