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

# auth

> CLI reference: floo auth — authenticate and manage your account

Authenticate with the floo API and manage your account.

## login

Authenticate with the floo API. Opens your browser for device code OAuth by default.

```bash theme={null}
floo auth login
```

The CLI displays a one-time code, opens your browser, and waits for you to complete authentication. Your API key is stored at `~/.floo/config.json`.

### Flags

| Flag            | Description                                                              |
| --------------- | ------------------------------------------------------------------------ |
| `--api-key KEY` | Use an existing API key instead of browser auth (for scripts and agents) |
| `--force`       | Skip existing key validation and force re-authentication                 |

### Examples

```bash theme={null}
# Interactive (opens browser)
floo auth login

# Non-interactive (for scripts and CI)
floo auth login --api-key floo_abc123...

# Force re-authenticate even if already logged in
floo auth login --force
```

### JSON output

```json theme={null}
{
  "success": true,
  "data": {
    "email": "you@example.com"
  }
}
```

### Errors

| Code                  | Meaning                                                                               |
| --------------------- | ------------------------------------------------------------------------------------- |
| `DEVICE_CODE_EXPIRED` | The device code expired before authentication completed. Run `floo auth login` again. |
| `DEVICE_AUTH_DENIED`  | Authorization was denied in the browser.                                              |
| `WAITLISTED`          | Your account is on the waitlist. You'll be notified when access is granted.           |
| `CONFIG_ERROR`        | Failed to save credentials. Check `~/.floo/config.json` permissions.                  |

***

## logout

Clear stored credentials from `~/.floo/config.json`.

```bash theme={null}
floo auth logout
```

### JSON output

```json theme={null}
{
  "success": true,
  "data": null
}
```

***

## whoami

Show the currently authenticated user, including email, masked API key, and display name.

```bash theme={null}
floo auth whoami
```

```
✓ Logged in as Pat (pat@example.com, key: floo_abc1...ef23)
```

### JSON output

```json theme={null}
{
  "success": true,
  "data": {
    "user_id": "u1a2b3c4-...",
    "email": "pat@example.com",
    "name": "Pat",
    "effective_scope": "full"
  }
}
```

### Errors

| Code                | Meaning                                       |
| ------------------- | --------------------------------------------- |
| `NOT_AUTHENTICATED` | No stored credentials. Run `floo auth login`. |

***

## token

Print the raw API key to stdout. Useful for piping into other tools.

```bash theme={null}
floo auth token
```

In human mode, prints the raw key to stdout (no formatting). In `--json` mode:

```json theme={null}
{
  "success": true,
  "data": {
    "api_key": "floo_abc123..."
  }
}
```

### Errors

| Code                | Meaning                                       |
| ------------------- | --------------------------------------------- |
| `NOT_AUTHENTICATED` | No stored credentials. Run `floo auth login`. |

***

## register

Create a new floo account for the given email address. Used by `floo auth login` in the signup path; can also be called directly.

```bash theme={null}
floo auth register you@example.com
```

### JSON output

```json theme={null}
{
  "success": true,
  "data": {
    "email": "you@example.com"
  }
}
```

***

## update-profile

Update your display name.

```bash theme={null}
floo auth update-profile --name "Pat"
```

### Flags

| Flag          | Description      |
| ------------- | ---------------- |
| `--name NAME` | New display name |

### JSON output

```json theme={null}
{
  "success": true,
  "data": {
    "name": "Pat"
  }
}
```