vercel domains

The vercel domains command manages domains under the current scope. With it, you can list, inspect, verify, add, remove, purchase, renew, move, transfer in, search, price, check the availability of, and manage automatic renewal for domains.

vercel domains ls

vercel domains inspect [domain]

vercel domains verify [domain]

vercel domains add [domain] [project]

vercel domains rm [domain]

vercel domains buy [domain]

vercel domains search [query]

vercel domains price [domain] [...domain]

vercel domains check [domain] [...domain]

vercel domains move [domain] [scope-name]

vercel domains transfer-in [domain]

vercel domains renew [domain]

vercel domains auto-renew [domain] [on|off]

With Vercel CLI 63.1.0 and later, scripts and agents can use domains buy and domains renew without an interactive terminal. The commands also skip prompts in CI when you pass --json.

Before charging a team, pass --scope <team> or set VERCEL_ORG_ID to that team's ID. A saved team selection or vercel.json scope alone isn't sufficient. If VERCEL_ORG_ID names a different team, the command refuses the charge.

1. Run the command without --amount to get the current price and required action:

   terminal

   vercel domains buy example.com --scope my-team --json
   vercel domains renew example.com --scope my-team --json

   Without --amount, these non-interactive commands charge nothing and exit with a non-zero status. The response identifies the paying team, price, term, and next command. For a purchase, it also reports renewal terms and missing registrant details.

   For example, a renewal priced at $20 for one year returns these fields on stdout. This excerpt omits the message and hint fields. The amount is illustrative; always use the price returned for your domain:

   Approval response (excerpt)

   {
     "status": "action_required",
     "reason": "confirmation_required",
     "action": "confirmation_required",
     "userActionRequired": true,
     "data": {
       "domain": "example.com",
       "team": "my-team",
       "amount": 20,
       "currency": "USD",
       "years": 1
     },
     "missing": ["--amount"],
     "next": [
       {
         "command": "vercel domains renew example.com --scope my-team --amount 20.00 --json",
         "when": "Only after a human approves: charges $20.00 now"
       }
     ]
   }

   Human-readable guidance may also appear on stderr. Parse stdout for the JSON response; don't combine the two streams.

2. Review the refund policy before approval. The CLI warns that domain registrations are non-refundable. Some purchases qualify for limited exceptions; see domain refund eligibility. Domain renewals are never refundable.

3. Ask a person to approve the price, paying team, and, for a purchase, automatic renewal. Then run the returned command with --amount <approved-price-in-USD> and any missing details. The amount must match the current price; it isn't a spending limit. If the price changes, the CLI charges nothing and asks for approval again.

For supported flags and required fields, see purchase options and renewal options.

The CLI doesn't automatically retry a purchase or renewal. In non-interactive mode or with --json, a failed or unconfirmed charge returns a JSON error. If the outcome is unknown, inspect the domain before retrying:

vercel domains inspect example.com --scope my-team --json

An unknown outcome can mean the charge succeeded even though the CLI couldn't confirm it. Retrying immediately can charge you twice.

These are options that only apply to the vercel domains command.

Use these options with the prompt-free purchase procedure. Approved billing details can supply available valid email and address fields, but never the registrant's first name, last name, or phone:

Contact flags override billing details. Replacing an existing billing address field with a flag discards the remaining billing address fields, so supply the complete replacement address. Adding a field missing from billing details keeps the other billing address fields.

Pass exactly one of --auto-renew and --no-auto-renew. These flags don't take values such as false. To stop automatic renewal after a purchase, use vercel domains auto-renew <domain> off.

domains renew accepts --amount <USD>, --json, and --format json. The amount approves the current renewal price for the reported term. Renewal doesn't require new registrant details or change the domain's automatic-renewal setting.

Use the --yes option to bypass the confirmation prompt when removing a domain.

vercel domains rm [domain] --yes

Use the --limit option to specify the maximum number of domains that ls returns. The default value is 20 and the maximum is 100.

vercel domains ls --limit 100

You can also use the --limit option with search to specify the number of domain candidates to check per page. The default value is 20 and the maximum is 200.

vercel domains search acme --limit 200

The --next option enables pagination when listing domains. Pass the timestamp (in milliseconds since the UNIX epoch) from a previous response to get the next page of results.

vercel domains ls --next 1584722256178

You can also use the --next option with search to fetch the next page of candidates. Pass the cursor returned in the previous search response or printed in the continuation command.

vercel domains search acme --next [cursor]

The --force option forces a domain on a project, removing it from an existing one.

vercel domains add my-domain.com my-project --force

Use the --available option with search to show only domain candidates that are available to register.

vercel domains search acme --available

Use the --order option with search to order candidates by relevance, alphabetical, or length. The default value is relevance.

vercel domains search acme --order alphabetical

Use the --tld option with search to filter candidates by exact top-level domain. Repeat the option to search multiple TLDs.

vercel domains search acme --tld com --tld dev

Use the --format=json option with search to return structured JSON output.

vercel domains search acme --format=json

You can also use the --format=json option with verify to return structured JSON output describing the current and expected DNS records for the domain.

vercel domains verify my-domain.com --format=json

You can also use the --format=json option with buy or renew to return structured JSON without prompts. Without --amount, the command charges nothing and returns the current price and approval instructions. To complete the charge, follow Buy or renew without prompts.

vercel domains renew my-domain.com --scope my-team --format=json

You can also use the --format=json option with auto-renew to return a structured JSON result describing the domain's new automatic renewal state.

vercel domains auto-renew my-domain.com on --format=json

Use the --project option with verify to check the DNS configuration against the records expected by a specific Vercel Project.

vercel domains verify my-domain.com --project my-project

Use the --strict option with verify to check DNS for the exact domain only, without falling back to the parent zone's configuration.

vercel domains verify my-domain.com --strict

The following global options can be passed when using the vercel domains command:

• --cwd
• --debug
• --global-config
• --help
• --local-config
• --no-color
• --non-interactive
• --scope
• --team
• --token
• --version

For more information on global options and their usage, refer to the options section.