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

# logs

> CLI reference: floo logs — view runtime logs

View runtime logs for an app. Filter by count, time range, severity, service, or text. Stream in real-time with `--live`.

```bash theme={null}
floo logs --app my-app
```

## Flags

| Flag                         | Description                                                                                                 | Default |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------- | ------- |
| `--app APP`                  | App name or UUID (reads from config if omitted)                                                             | —       |
| `--tail N` / `-t N`          | Number of log lines                                                                                         | `100`   |
| `--since SINCE` / `-s SINCE` | Time filter (`1h`, `30m`, `2d`, or ISO timestamp)                                                           | —       |
| `--error` / `-e`             | Errors only (shorthand for `--severity ERROR`)                                                              | —       |
| `--severity LEVEL`           | Exact severity: DEFAULT, DEBUG, INFO, WARNING, ERROR, CRITICAL                                              | —       |
| `--services SVC`             | Filter to specific services (repeatable)                                                                    | —       |
| `--cron NAME`                | Filter to a specific cron job by name                                                                       | —       |
| `--search TEXT`              | Filter log messages by text (case-insensitive)                                                              | —       |
| `--live` / `-f`              | Stream logs in real-time (poll every 2s). Cannot combine with `--output`. Works with `--requests` too.      | —       |
| `--output PATH` / `-o PATH`  | Write logs to file                                                                                          | —       |
| `--env ENV`                  | Environment to query: `dev` or `prod`                                                                       | `dev`   |
| `--requests`                 | Show HTTP requests captured by floo's gateway (public URL, status, latency) instead of app-level log output | —       |

## Examples

```bash theme={null}
floo logs --app my-app                          # Last 100 lines
floo logs --app my-app --tail 20               # Last 20 lines
floo logs --app my-app --since 1h              # Last hour
floo logs --app my-app --error                 # Errors only
floo logs --app my-app --severity WARNING      # Only warning logs
floo logs --app my-app --services api          # Only the "api" service
floo logs --app my-app --cron daily-report     # Only the "daily-report" cron job
floo logs --app my-app --search "timeout"      # Text search
floo logs --app my-app --live                  # Stream in real-time
floo logs --app my-app --env prod              # Production logs (default is dev)
floo logs --app my-app --requests              # Gateway request logs (URL, status, latency)
floo logs --app my-app --output errors.json --json --error   # Save errors to file
```

## JSON output

```json theme={null}
{
  "success": true,
  "data": {
    "app_name": "my-app",
    "logs": [
      {
        "timestamp": "2026-02-18T10:30:00Z",
        "severity": "ERROR",
        "message": "Connection refused: postgres://..."
      },
      {
        "timestamp": "2026-02-18T10:30:01Z",
        "severity": "INFO",
        "message": "Server started on port 3000"
      }
    ]
  }
}
```

## Agent debugging workflow

```bash theme={null}
# Get errors
floo logs --app my-app --error --json 2>/dev/null | jq '.data.logs[0].message'

# Fix the issue
floo env set DATABASE_URL=postgres://correct-url --app my-app --json

# Redeploy
floo redeploy --app my-app --json
```

## Errors

| Code                | Meaning                         |
| ------------------- | ------------------------------- |
| `NOT_AUTHENTICATED` | Run `floo auth login` first     |
| `APP_NOT_FOUND`     | No app with that name or ID     |
| `PARSE_ERROR`       | Invalid `--since` format        |
| `FILE_ERROR`        | Cannot write to `--output` path |