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

# floo previews

> Create, inspect, stream logs for, and delete preview sandboxes from remote GitHub branches.

`floo previews` manages isolated preview sandboxes for pushed GitHub branches. Use it when an agent needs a real deploy URL before opening a pull request or when you want to inspect and clean up existing previews from the terminal.

The command uses the same preview isolation contract as pull request previews. It deploys source from the app's connected GitHub repository; it does not upload local dirty files.

## up

Create or refresh a preview sandbox from a remote branch.

```bash theme={null}
git push origin feat/foo
floo previews up --app my-app --branch feat/foo
floo previews up --app my-app --branch feat/foo --wait --json
```

`--wait` watches the deploy returned by the create call. It exits non-zero if that deploy fails.

### Flags

| Flag           | Default              | Description                                             |
| -------------- | -------------------- | ------------------------------------------------------- |
| `--app`, `-a`  | inferred from config | App name or ID                                          |
| `--branch`     | required             | Remote GitHub branch to deploy into the preview sandbox |
| `--runtime`    | `auto`               | Runtime hint for the deploy request                     |
| `--commit-sha` | none                 | Specific remote commit SHA to deploy                    |
| `--ref`        | none                 | Remote Git ref to deploy                                |
| `--wait`       | off                  | Wait until the preview deploy finishes                  |

### JSON output

```json theme={null}
{
  "success": true,
  "data": {
    "app": {
      "id": "app_123",
      "name": "my-app"
    },
    "preview": {
      "slug": "feat-foo-abcde",
      "source_branch": "feat/foo"
    },
    "source_branch": "feat/foo",
    "deploy_id": "deploy_123",
    "status": "LIVE",
    "url": "https://my-app-preview-feat-foo-abcde.on.getfloo.com",
    "expires_at": "2026-06-30T18:30:00Z",
    "database_branches": [],
    "dev_prod_untouched": true
  }
}
```

Non-streaming preview commands emit one parseable JSON object. Log streaming is the exception: it may emit output over time.

## list

List active preview sandboxes for an app.

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

## status

Show one preview sandbox.

```bash theme={null}
floo previews status --app my-app feat/foo
floo previews status --app my-app https://my-app-preview-feat-foo-abcde.on.getfloo.com --json
```

The preview identifier can be an exact slug, preview URL, source branch, or `#123` when that PR number resolves to exactly one preview. If the identifier is ambiguous, pass the exact slug from `floo previews list`.

## logs

Read logs for the latest deploy associated with a preview.

```bash theme={null}
floo previews logs --app my-app feat/foo
floo previews logs --app my-app feat/foo --follow --tail 200
```

### Flags

| Flag             | Default | Description                  |
| ---------------- | ------- | ---------------------------- |
| `--follow`, `-f` | off     | Stream logs                  |
| `--tail`         | `100`   | Number of log lines to fetch |

## delete

Delete a preview sandbox and its preview-owned resources.

```bash theme={null}
floo previews delete --app my-app feat/foo
floo previews delete --app my-app feat/foo --yes --json
```

Delete tears down preview-owned Cloud Run services, managed resources, gateway routes, and env vars through the preview lifecycle API. Dev and prod resources are untouched.

### Flags

| Flag          | Default              | Description                  |
| ------------- | -------------------- | ---------------------------- |
| `--app`, `-a` | inferred from config | App name or ID               |
| `--yes`       | off                  | Skip the confirmation prompt |

## Failure Handling

| Symptom                                         | Meaning                                                         | What to do                                                             |
| ----------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------- |
| The preview deploy uses an old commit           | The branch was not pushed before `up` ran                       | Push the branch or pass a remote commit/ref                            |
| `PREVIEW_MANAGED_SERVICE_ISOLATION_UNAVAILABLE` | floo could not provision preview-owned managed resources        | Fix the managed-service state and retry                                |
| Identifier is ambiguous                         | More than one preview matched the branch, URL, or PR identifier | Use the exact slug from `floo previews list`                           |
| `--wait` exits non-zero                         | The returned deploy failed or timed out                         | Inspect `floo previews status ... --json` and `floo previews logs ...` |

## Related

* [Preview Environments](/guides/preview-environments)
* [`floo db`](/cli/database)
* [`floo logs`](/cli/logs)