# Setting up a custom domain

Use this guide to add a custom domain to your Vercel project from the CLI, configure DNS records, and verify that everything is working. To do the same from the dashboard instead (Settings → Domains on your project), see [Adding & Configuring a Custom Domain](/content/docs/domains/working-with-domains/add-a-domain/index.html).

This guide requires a [linked Vercel project](/content/docs/cli/project-linking/index.html). Run `vercel link` in your project directory if you haven't already.

## Quick reference

Use this block when you already know what you're doing and want the full command sequence. Use the steps below for context and checks.

### Command Sequence

```
# 1. Check your existing domains
vercel domains ls

# 2. Add the domain to your project (one arg when run from a linked project)
vercel domains add example.com

# 3. Check what DNS records are needed
vercel domains inspect example.com

# 4. Configure DNS records (apex domain)
vercel dns add example.com '@' A 76.76.21.21

# 4b. OR configure DNS records (subdomain)
vercel dns add example.com www CNAME cname.vercel-dns-0.com

# 5. Verify DNS configuration
vercel domains inspect example.com

# 6. Verify SSL certificate was provisioned
vercel certs ls

# 7. Test the domain
vercel httpstat /
vercel curl /
```

## 1. Check your existing domains

List the domains already configured on your team to avoid conflicts:

```
vercel domains ls
```

This shows all domains across your projects, including their DNS status and verification state.

## 2. Add the domain to your project

Add your custom domain. From a linked project, `vercel domains add` takes a single argument (the domain). To target a different project (or when running outside of a linked directory), pass the project name as a second argument.

```
vercel domains add example.com
```

If the domain is already assigned to another project in your team, use the `--force` flag to reassign it:

```
vercel domains add example.com --force
```

For a `www` subdomain, add that separately:

```
vercel domains add www.example.com
```

If you add both `example.com` and `www.example.com`, configure a redirect from one to the other in your [Vercel project settings](/content/docs/domains/working-with-domains/deploying-and-redirecting#redirecting-domains/index.html) to avoid duplicate content.

## 3. Check what DNS records are needed

After adding the domain, inspect it to see the required DNS configuration:

```
vercel domains inspect example.com
```

This shows the current DNS verification status and the exact records you need to configure. The output tells you whether the domain needs an A record, CNAME record, or nameserver delegation.

## 4. Configure DNS records

The records you add depend on whether you're configuring an apex domain (like `example.com`) or a subdomain (like `www.example.com`).

For an apex domain, add an A record:

```
vercel dns add example.com '@' A 76.76.21.21
```

For a subdomain, add a CNAME record:

```
vercel dns add example.com www CNAME cname.vercel-dns-0.com
```

The DNS values shown above (`76.76.21.21` and `cname.vercel-dns-0.com`) are Vercel's general-purpose values. Run `vercel domains inspect example.com` to see the exact records recommended for your domain. These commands work when your domain's nameservers are pointed to Vercel. If you manage DNS with an external provider, add these records through your provider's dashboard instead.

To verify your DNS records were added:

```
vercel dns ls
```

## 5. Verify DNS configuration

Run `inspect` again to check that the domain is properly configured and verified:

```
vercel domains inspect example.com
```

DNS propagation can take a few minutes. If the domain isn't verified yet, wait and run the command again.

## 6. Verify SSL certificate

Vercel automatically provisions an SSL certificate after DNS verification succeeds. Check that the certificate was issued:

```
vercel certs ls
```

Look for your domain in the output. The certificate typically provisions within a few minutes of DNS verification.

## 7. Test the domain

Verify your domain is serving traffic correctly:

```
vercel httpstat /
```

This shows a full timing breakdown for a request to your production deployment. If you need to check the response body:

```
vercel curl /
```

## When you're using an external DNS provider

If your domain's nameservers point to an external DNS provider (like Cloudflare or Route 53), you can't use `vercel dns add` to configure records. Instead:

1. Add the domain to your project with `vercel domains add example.com`
2. Run `vercel domains inspect example.com` to see the required records
3. Add those records through your external DNS provider's interface
4. Run `vercel domains inspect example.com` again to verify Vercel detected the records.