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

# domains

> CLI reference: floo domains add, list, show, verify, watch, remove

Manage custom domains for your apps.

## add

Add a custom domain to an app. Returns the traffic and claimant-control DNS instructions.

```bash theme={null}
floo domains add myapp.com --app my-app
```

### Flags

| Flag             | Description                                           |
| ---------------- | ----------------------------------------------------- |
| `--app APP`      | App name or UUID (reads from config if omitted)       |
| `--services SVC` | Target service name (required for multi-service apps) |

### JSON output

```json theme={null}
{
  "success": true,
  "data": {
    "hostname": "myapp.com",
    "status": "pending",
    "claim_verified_at": null,
    "dns_instructions": "Add a CNAME record: myapp.com -> edge.getfloo.com\nAdd a TXT record: _floo-verify.myapp.com with value <claim token>"
  }
}
```

***

## list

List all custom domains for an app.

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

### Flags

| Flag             | Description                                     |
| ---------------- | ----------------------------------------------- |
| `--app APP`      | App name or UUID (reads from config if omitted) |
| `--services SVC` | Filter to a single target service               |

### JSON output

```json theme={null}
{
  "success": true,
  "data": {
    "domains": [
      {
        "hostname": "myapp.com",
        "status": "pending",
        "claim_verified_at": null,
        "dns_instructions": "Add a CNAME record: myapp.com -> edge.getfloo.com\nAdd a TXT record: _floo-verify.myapp.com with value <claim token>"
      }
    ]
  }
}
```

***

## show

Show detailed status for a single custom domain, including claimant-control proof state.

```bash theme={null}
floo domains show myapp.com --app my-app
```

### Flags

| Flag        | Description                                     |
| ----------- | ----------------------------------------------- |
| `--app APP` | App name or UUID (reads from config if omitted) |

### JSON output

```json theme={null}
{
  "success": true,
  "data": {
    "hostname": "myapp.com",
    "status": "pending",
    "claim_verified_at": null,
    "dns_instructions": "Add a CNAME record: myapp.com -> edge.getfloo.com\nAdd a TXT record: _floo-verify.myapp.com with value <claim token>"
  }
}
```

### Errors

| Code               | Meaning                                  |
| ------------------ | ---------------------------------------- |
| `DOMAIN_NOT_FOUND` | No domain with that hostname on this app |

***

## verify

Confirm DNS control for a pending domain or an active grandfathered domain. A
pending activation checks both the traffic record and the exact per-domain
`_floo-verify` TXT token. A grandfathered domain is already serving, so staged
reproof checks only its missing TXT evidence and leaves its live route untouched.

```bash theme={null}
floo domains verify myapp.com --app my-app
```

### Flags

| Flag        | Description                                     |
| ----------- | ----------------------------------------------- |
| `--app APP` | App name or UUID (reads from config if omitted) |

### JSON output

```json theme={null}
{
  "success": true,
  "data": {
    "hostname": "myapp.com",
    "status": "active",
    "claim_verified_at": "2026-07-30T12:00:00Z",
    "dns_instructions": "Add a CNAME record: myapp.com -> edge.getfloo.com\nAdd a TXT record: _floo-verify.myapp.com with value <claim token>"
  }
}
```

### Errors

| Code                         | Meaning                                                                 |
| ---------------------------- | ----------------------------------------------------------------------- |
| `DOMAIN_NOT_FOUND`           | No domain with that hostname on this app                                |
| `DOMAIN_ALREADY_VERIFIED`    | Claimant-control proof is already recorded                              |
| `DOMAIN_VERIFICATION_FAILED` | A required traffic or `_floo-verify` TXT record is missing or incorrect |

An active domain with `claim_verified_at: null` predates claimant-specific proof.
It stays live if reproof fails, but service and environment rebinding remain
blocked until this command succeeds.

***

## watch

Poll a pending domain until it goes `active`, reports a terminal failure, or the timeout expires. Useful in CI or while waiting on DNS propagation.

```bash theme={null}
floo domains watch myapp.com --app my-app
```

### Flags

| Flag             | Description                                                 | Default |
| ---------------- | ----------------------------------------------------------- | ------- |
| `--app APP`      | App name or UUID (reads from config if omitted)             | —       |
| `--timeout SECS` | Maximum seconds to wait before exiting with a timeout error | `300`   |

The command polls the verify endpoint every 5 seconds. Exits `0` when the domain reaches `active`, non-zero on DNS verification failure or timeout.

### JSON output (on success)

```json theme={null}
{
  "success": true,
  "data": {
    "hostname": "myapp.com",
    "status": "active"
  }
}
```

***

## remove

Remove a custom domain from an app.

```bash theme={null}
floo domains remove myapp.com --app my-app
```

### Flags

| Flag             | Description                                           |
| ---------------- | ----------------------------------------------------- |
| `--app APP`      | App name or UUID (reads from config if omitted)       |
| `--services SVC` | Target service name (required for multi-service apps) |

### JSON output

```json theme={null}
{
  "success": true,
  "data": {
    "hostname": "myapp.com"
  }
}
```

### Errors

| Code                | Meaning                     |
| ------------------- | --------------------------- |
| `NOT_AUTHENTICATED` | Run `floo auth login` first |
| `APP_NOT_FOUND`     | No app with that name or ID |