# Ship a full-stack app with floo (for agents)

You are an agent with a shell, git, and HTTP. Your user wants a web app with
login and a database that they and their team can open in a browser. floo
runs it. Neither you nor your user needs a GitHub account.

Every command below supports `--json` for structured output. A failed
command prints what to run next (a `next:` or `Suggestion:` line in human
output, a `suggestion` field in JSON). Do that before anything else.

## The loop

```
curl -fsSL https://getfloo.com/install.sh | bash   # 1. install the CLI
floo auth login                                    # 2. your user approves (see below)
floo projects create reading-list                  # 3. app, login, postgres, first deploy
floo projects clone reading-list                   # 4. clone; git credentials are automatic
cd reading-list && cat AGENTS.md                   # 5. how to build inside the app
git add -A && git commit -m "feat: ..." && git push  # 6. ship
floo deploys watch                                 # 7. wait for the URL
floo apps invite you@example.com                   # 8. let your user in
```

## 1. Install

```
curl -fsSL https://getfloo.com/install.sh | bash
floo --version
```

If `floo` is not on your PATH afterwards, the installer prints the directory
it used. Add it to PATH or call the binary by its full path. This recipe
needs version 2026.09.12 or newer; `floo update` upgrades an older install.

## 2. Log in (needs your user)

```
floo auth login
```

The command prints a URL and a one-time code, then waits. Send both to your
user and tell them to open the URL and enter the code. The command returns
on its own once they approve. The code expires in a few minutes; if it does,
run the command again.

Do not ask your user for a password, API key, or GitHub login. Do not create
any account on their behalf.

## 3. Create the project

```
floo projects create reading-list
```

Names are 2 to 40 characters of lowercase letters, digits, and hyphens,
starting with a letter and not ending with a hyphen. Common words floo uses
itself (`app`, `api`, `admin`, `docs`, `www`, and similar) are reserved; if
create rejects the name, pick a more specific one.

A brand-new organization has no plan yet, and creating an app needs a
plan. If create fails with `PLAN_REQUIRED`, the error carries an
`upgrade_url`. Send it to your user, wait for them to pick a plan (pay as
you go has no monthly commitment; a payment method is required and usage is
billed monthly), then run create again. This happens once per organization.

One command gives you:

- a private git repository in a GitHub organization floo operates; your
  user needs no GitHub account, and only floo's systems and floo staff can
  reach it;
- a running Next.js app at `https://reading-list-dev.on.getfloo.com`,
  deployed from a starter template;
- hosted login on that URL, invite-only, with the signed-in user's identity
  passed to your code as request headers;
- a managed Postgres database, connected through `DATABASE_URL`.

The output includes the app URL and the clone command. It is normal for the
first deploy to still be running when the command returns.

## 4. Clone it

```
floo projects clone reading-list
cd reading-list
```

Clone writes a git credential helper into this repository only. `git push`
and `git pull` inside it work with no further setup. Tokens are minted per
operation, scoped to this one repository, and never stored on disk.

Never run `gh`, never edit the remote URL, and never paste a token into a
URL. If git asks for a username or password, you are outside the clone or
the CLI has moved: from the parent directory, run
`floo projects clone reading-list reading-list-2` into a fresh path, copy
your changed files across, and continue there.

## 5. Build

Read `AGENTS.md` in the clone before writing code. It covers the layout,
how to read the signed-in user, how to add tables and migrations, how to run
locally, and how to add a cron job or environment variable. The short
version:

- Pages live in `app/`, server actions in `app/actions.ts`, tables in
  `db/schema.ts`.
- Read the current user with `getIdentity()` from `lib/identity.ts`. Never
  build your own login.
- After changing `db/schema.ts`, run `npm run db:generate` and commit the
  generated files under `drizzle/`. Deploys run migrations before serving.
- `npm run build` and `npm test` must pass before you push.

## 6. Ship

```
git add -A
git commit -m "feat: reading list"
git push
```

Every push to `main` deploys. There is no separate deploy command.

## 7. Wait for it

```
floo deploys watch
```

Run this from inside the clone. It streams the build and exits when the
deploy succeeds or fails, printing the URL on success. It also stops after
five minutes of streaming; that is a timeout, not a failure, so run it again
rather than changing code. On failure:

```
floo deploys list --json          # find the deploy id and failing stage
floo deploys logs <deploy-id>     # build output
floo logs query --since 15m       # runtime logs once it is serving; exits
```

Fix, commit, push, watch again.

## 8. Invite your user

```
floo apps invite you@example.com
floo apps invite teammate@example.com --role admin
```

Each person gets an email with a one-time link. They open the link, accept
the invite, and sign in with that address; from then on the app URL opens
for them. Until they accept, signing in at the app URL is refused, so tell
your user to look for the email. Nobody else can reach the app. A push
cannot make it public; that is an organization-admin decision outside this
recipe, so do not attempt it.

## Everything else

The CLI is the reference, not this page. `floo commands --json` prints the
full command tree and `floo <command> --help` explains any command. Two you
will reach for: `floo env set KEY --stdin --secret` stores a write-only
secret the app reads at runtime without committing it (plain
`floo env set KEY=VALUE` is a readable environment variable; read it back
with `floo env get KEY --json`, because `floo env list` masks every value), and
`floo releases promote` moves the app from its dev URL to prod when your
user asks for that.

## Rules

- Two things need your user: approving the login, and picking a plan the
  first time an organization creates an app. Everything else you do
  yourself.
- Configuration lives in `floo.app.toml` in the repo and changes through git.
  Do not edit it unless `AGENTS.md` tells you to.
- Prefer `--json`. Secret-shaped values are redacted in JSON output on
  purpose; do not try to reveal them.
- Reference: https://getfloo.com/docs and https://getfloo.com/llms.txt