> ## 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.

# releases

> CLI reference: floo releases — manage releases and promote apps to production

Manage releases and promote apps to production via GitHub releases.

## list

List releases for an app.

```bash theme={null}
floo releases list --app my-app
```

### Flags

| Flag        | Description      |
| ----------- | ---------------- |
| `--app APP` | App name or UUID |

### JSON output

```json theme={null}
{
  "success": true,
  "data": {
    "releases": [
      {
        "id": "r1a2b3c4-...",
        "tag": "v1.2.0",
        "commit_sha": "abc1234",
        "promoted_by": "you@example.com",
        "deploy_id": "d5e6f7g8-...",
        "created_at": "2026-03-01T14:00:00Z"
      }
    ]
  }
}
```

***

## show

Show details for a specific release (tag, commit, promoted by, deploy ID, image digest).

```bash theme={null}
floo releases show r1a2b3c4 --app my-app
```

### Flags

| Flag        | Description      |
| ----------- | ---------------- |
| `--app APP` | App name or UUID |

### JSON output

```json theme={null}
{
  "success": true,
  "data": {
    "id": "r1a2b3c4-...",
    "tag": "v1.2.0",
    "commit_sha": "abc1234",
    "promoted_by": "you@example.com",
    "deploy_id": "d5e6f7g8-...",
    "image_digest": "sha256:abcdef123456...",
    "created_at": "2026-03-01T14:00:00Z"
  }
}
```

***

## promote

Promote the latest live dev deploy to production. Creates a GitHub release if GitHub is connected.

```bash theme={null}
floo releases promote --app my-app
```

### What happens during promote

Promote copies dev images to prod Cloud Run without rebuilding (fast path), or rebuilds with prod build-time env vars if any `VITE_*` / `NEXT_PUBLIC_*` vars differ. In addition to deploying the images, promote also:

1. **Runs database migrations** — for each service with a `migrate_command` set in `floo.app.toml`, runs the command as a Cloud Run Job against the prod schema. Migration failures are logged but do not block the promote from going live.
2. **Creates gateway routes for all environments** — both the shared app host (`{app}.on.getfloo.com`) and per-service hosts (`{app}-{svc}.on.getfloo.com`) are upserted on every promote, so stale routes from before service renaming are corrected automatically.
3. **Grants IAM** — gateway SA run.invoker is granted on all public services; the app SA is granted on internal services.

### Flags

| Flag        | Description                                             |
| ----------- | ------------------------------------------------------- |
| `--app APP` | App name or UUID                                        |
| `--tag TAG` | Release tag (auto-generated if omitted, e.g., `v1.2.1`) |

### Examples

```bash theme={null}
# Promote with auto-generated tag
floo releases promote --app my-app

# Promote with explicit tag
floo releases promote --app my-app --tag v2.0.0

# Agent workflow: promote and extract tag
floo releases promote --app my-app --json 2>/dev/null | jq -r '.data.tag'
```

### JSON output

```json theme={null}
{
  "success": true,
  "data": {
    "id": "r9a8b7c6-...",
    "tag": "v1.2.1",
    "commit_sha": "def5678",
    "deploy_id": "d1e2f3g4-...",
    "release_url": "https://github.com/you/my-app/releases/tag/v1.2.1"
  }
}
```

***

## rollback

Roll back to a previous live deploy by re-pointing gateway routes at its image — no rebuild. This is the release-scoped equivalent of [`floo deploys rollback`](/docs/cli/deploys#floo-deploys-rollback-app-deploy-id).

```bash theme={null}
floo releases rollback --app my-app --to d1e2f3g4
```

### Flags

| Flag        | Description                                                                  |
| ----------- | ---------------------------------------------------------------------------- |
| `--app APP` | App name or UUID                                                             |
| `--to ID`   | Deploy ID to roll back to (the previous live deploy). Aliased as `--deploy`. |
| `--yes`     | Skip the `y/N` prompt. Required in non-interactive contexts.                 |

Rollback is **tier-2 destructive**: interactive mode prompts `y/N`; non-interactive runs require `--yes`.

***

## Errors

| Code                 | Meaning                                                         |
| -------------------- | --------------------------------------------------------------- |
| `NOT_AUTHENTICATED`  | Run `floo auth login` first                                     |
| `APP_NOT_FOUND`      | No app with that name or ID                                     |
| `NO_DEV_DEPLOY`      | Deploy to dev first before promoting                            |
| `RELEASE_TAG_EXISTS` | A release with that tag already exists. Use a different `--tag` |
| `RELEASE_NOT_FOUND`  | No release with that ID                                         |