What changed: registrar lookup now lives next to a production deploy
Domain search, availability checks, registrar pricing, and purchase are now subcommands of vercel domains, the same command family that lists and assigns the domains a deploy targets. The canonical vercel domains reference enumerates list, inspect, add, remove, buy, move, transfer-in, and verify, all scoped to “the current scope,” meaning whatever team the CLI resolves to in the working directory. The vercel/vercel skills reference fills in the registrar-discovery subcommands (search, check, price) that turn the surface into a full lookup-to-purchase pipeline. And vercel buy folds domain purchase into a purchase family that also sells credits, addons, and subscriptions: vercel buy domain example.com explicitly “delegates to the vercel domains buy command.”
That is the architectural shift worth naming. A registrar used to be an out-of-band dependency: a separate API, separate credentials, separate billing relationship. Here it is in-band, sharing a scope, an auth token, and a working directory with the deploy command.
How the search, check, price, and buy pipeline works
vercel domains search <term> returns availability, purchase pricing, and renewal pricing in bulk, and the rest of the pipeline narrows from there. Search accepts --available (filter to registerable domains), --tld (repeatable TLD filter), --order (relevance, alphabetical, or length), --limit (default 20, with a higher ceiling than listing), --next (a pagination cursor), and --format=json for structured output, per the vercel domains reference.
Two narrower subcommands cap at 50 domains per request: vercel domains check for availability and vercel domains price for registrar quotes. The skills reference encodes a useful shortcut: if domains price emits no purchase price for a domain, that domain is unavailable, so price doubles as an availability probe when you need both fields in one call. If you only need availability, check is the cheaper hit.
Purchase itself is one call, vercel domains buy example.com, and attachment collapses into the same step with a second argument: vercel domains add example.com my-project both registers the domain to the team and assigns it to a project. One argument adds to the team only; two arguments adds and assigns. That arity difference is the line between an inventory entry and a live production binding.
How the purchased domain gets attached to a deploy
Once bought, the domain still has to reach a deployment, and Vercel offers two paths: nameserver delegation with auto-assign on the next production deploy, or an explicit vercel alias. The typical flow in the skills reference is to point nameservers at Vercel at the registrar, then run vercel --prod, after which the domain is auto-assigned to the deployment. The manual alternative is vercel alias set <deployment-url> example.com, which maps a specific deployment URL to the custom domain without a redeploy. DNS records, when you are on Vercel nameservers, move through vercel dns (ls, add, rm).
The skills reference is blunt about which path matters: “Most users only need vercel alias; domains and DNS are auto-configured when using Vercel nameservers.” The buy step changes ownership and nothing else. Attachment is a separate, explicitly scoped operation, which is the part that determines who pays and which project serves traffic.
How CI drives purchase and deploy from one token
The same authentication path a deploy pipeline uses also authorizes domain purchase, because the CLI is explicitly designed to be driven “through an automated system.” The vercel CLI overview recommends VERCEL_TOKEN over --token to avoid leaking the credential in process lists, and that token works for deploys and domain purchases alike. On the buy side, vercel buy documents two flags that make the difference for scripting: --yes skips the confirmation prompt and is “required when running in non-interactive environments like CI,” and --json returns the purchase result as structured JSON instead of plain text, which is what lets a script chain the buy step into the next operation without parsing prose. Strung together, a single token can search, buy, attach, and --prod deploy in one pipeline run.
The buy surface is not uniformly complete, and that is worth flagging before you script against it. The buy docs state plainly that “v0 subscription purchase is not yet available via the CLI.” Domains, credits, addons, and Pro are wired; v0 subscriptions are not. A provisioning script that assumes every vercel buy subcommand is implemented hits a wall on v0.
There is a second, subtler scoping wrinkle in the same docs. “All subcommands except domain require a team scope,” so vercel buy domain is the one purchase subcommand exempted from the explicit --scope requirement that credits, addons, and subscriptions carry. Domain purchase can resolve its scope from the local directory where a credits purchase would demand --scope. Inconsistent scoping rules across sibling subcommands is exactly the kind of thing that bites a script run from the wrong working directory.
The v50.40.0 footgun: read-only inventory now follows the working directory
Under CLI v50.40.0 (changelog dated 2026-04-06), read-only commands including vc domains ls resolve against the locally linked project’s team scope instead of the global team, so a scripted search can silently query a different team’s inventory than the one the subsequent buy bills. --scope (-S) or --team (-T) override the local resolution. Project targeting resolves through a precedence chain: the --project flag, then the VERCEL_PROJECT_ID environment variable, then .vercel/project.json written by vercel link, which auto-detects a project by slugifying the current directory name. The v50.40.0 scoping change did not alter that mutation chain, according to Groundy’s analysis.
The second-order risk is specific to a scripted loop. The read-only search and ls calls inherit the cwd’s team, so if the working directory is linked to Team A, the script shops Team A’s inventory. If a subsequent purchase is routed differently, or run from a different cwd, the billing team and the shopping team diverge. That is not a security hole; it is a billing-correctness footgun, and --scope or --team is the documented mitigation.
What the docs do not say about automated registration
The CLI reference publishes no rate limits, spend caps, or per-team registration ceilings for programmatic domains buy. The --yes confirmation bypass is the only documented friction on automated purchase. The pages are CLI reference docs, not a security or billing advisory, and they do not state how many domains a token can register per minute, whether a team can hit a registration ceiling, or whether anomalous programmatic purchase triggers a review.
That gap is where the angle turns. Vercel markets a Platforms tier for teams that “host multi-tenant products that isolate every customer, provision custom domains, and serve millions of sites,” and ships a vercel/vercel-plugin installable via npx plugins add “for agents,” per the homepage. That is precisely the audience that will script the search-buy-attach loop. The tooling invites the workflow; the billing guardrails for it are not in the reference.
The takeaway for an operator is to treat the domain-buy surface the way you would treat any spend-bearing mutation in CI. Scope the token narrowly, pass --scope or --team explicitly so cwd resolution cannot redirect billing, and put a purchase approval step outside the loop when the cost is non-trivial. The convenience of one tool for search, buy, attach, and deploy is real. So is the fact that the same session running vercel --prod can now spend money on domains with a single --yes.
Frequently Asked Questions
Why would a 200-result domain search break at the check or price step?
vercel domains search accepts --limit up to 200, but domains check and domains price cap at 50 domains per request, so a loop that pulls a full 200-name result has to split it into four batches before it can quote or verify availability.
Why do search and buy use different JSON output flags?
vercel domains search emits structured output via --format=json, while vercel buy returns the purchase result through --json, so a script that pipes search results into a buy step has to handle two different flag names for the same kind of structured output.
When does vercel alias force a re-alias that nameserver delegation avoids?
vercel alias set pins a custom domain to one specific deployment URL, so each new production build needs a fresh alias to point at the current deployment. Nameserver delegation with vercel --prod auto-assigns the domain to whichever deployment is live, which is why the skills reference says most users only need alias for one-off mappings.
How can vercel link’s auto-detection silently target the wrong project?
vercel link writes .vercel/project.json by slugifying the current directory name, so a domain command run from a directory whose name slug-matches an unrelated project will target that project without warning. Passing --project, setting VERCEL_PROJECT_ID, or relinking is the only way to override the cwd-derived match.
What does a dedicated registrar API offer that vercel domains buy does not?
A traditional registrar exposes a separate API with its own documented rate limits and billing controls, whereas vercel domains buy shares the deploy token and team scope. The CLI reference publishes no per-token registration rate limit or spend cap the way a registrar API typically documents, so a provisioning loop has to enforce those externally.
