# Domains

> Your hostnames on app and site targets — DNS verification, certificates, renewal

URL: https://pier.run/docs/resources/domains

```yaml title="pier.yaml"
environments:
  prod:
    apps:
      - name: api
        targets:
          - name: primary
            domains:
              - host: api.acme.example
    sites:
      - name: www
        targets:
          - name: primary
            domains:
              - host: www.acme.example
```

```bash
pier ls domains
```

```text title="output"
→  No custom domains.

```

A domain is one hostname attached to one app or site target. Pier verifies that DNS
points at the target and that you control the name, then issues and renews the
certificate. The target's generated hostname continues to work as well.

## Configuration

| Key                        | Meaning      |
| -------------------------- | ------------ |
| `targets[].domains[].host` | The hostname |

## Verification

| Record  | Name               | Value                                                                               | Proves    |
| ------- | ------------------ | ----------------------------------------------------------------------------------- | --------- |
| `CNAME` | the hostname       | app: the target's hostname; site: the shared site target shown by `pier add domain` | routing   |
| `TXT`   | `_pier.<hostname>` | `pier-verify=<token>`                                                               | ownership |

`pier ls domains` shows `verification` (`pending` → `verified`) and `tls` (`pending` →
`active`). Verification is retried with backoff until both records resolve, and
re-checked periodically afterwards.

## Commands

| Command                                                                                        | Does                                    |
| ---------------------------------------------------------------------------------------------- | --------------------------------------- |
| `pier add domain api.acme.example --app api` / `--site www`, `pier rm domain api.acme.example` | attach, detach                          |
| `pier ls domains`, `pier info api.acme.example`                                                | state, the records to create, the token |

## Tasks

[Add a custom domain](/docs/guides/add-a-custom-domain)