vdomains

A CLI for the full Vercel Domains lifecycle — search, buy, manage, diagnose, transfer, and renew domains. Built with Ink for interactive terminal UI, with a --json mode for scripting and agentic workflows.

Install

npm install -g vdomains

Setup

vdomains needs a Vercel API token. You can provide it three ways (checked in this order):

# 1. Flag (per-command)
vdomains list --token vrc_xxx

# 2. Environment variable
export VERCEL_TOKEN=vrc_xxx

# 3. OS keychain (recommended)
vdomains login

Tokens are stored securely in your OS keychain (macOS Keychain, Windows Credential Vault, or Linux Secret Service) via keytar.

Commands

Discovery

# Search availability across TLDs with pricing
vdomains search mycoolapp

# Omit query to infer from nearest package.json
vdomains search

# Check a single domain
vdomains check mycoolapp.dev

# Check price and open Vercel to purchase
vdomains buy mycoolapp.dev

# Generate name variations from keywords
vdomains suggest cool app startup

The search command is interactive — use arrow keys to browse results, press Enter to open in browser, c to copy, q to quit.

Management

# List all domains in your account
vdomains list

# Domains expiring within N days (default: 90)
vdomains expiring
vdomains expiring 30

Lifecycle

# Renew a domain
vdomains renew mycoolapp.dev

# Toggle auto-renewal
vdomains auto-renew mycoolapp.dev on
vdomains auto-renew mycoolapp.dev off

# View or update nameservers
vdomains nameservers mycoolapp.dev
vdomains nameservers mycoolapp.dev ns1.example.com ns2.example.com

# Transfer a domain into Vercel
vdomains transfer-in mycoolapp.dev

# Get auth code for outbound transfer
vdomains transfer-out mycoolapp.dev

# Check order status
vdomains order ord_abc123

Transfer-in requires WHOIS contact info. Store it once with vdomains contact set and it's used automatically.

Diagnostics

# Full health check (DNS, SSL, HTTP, headers)
vdomains health mycoolapp.dev

# DNS record lookup (A, AAAA, CNAME, MX, NS, TXT)
vdomains dns mycoolapp.dev

# WHOIS lookup (registrar, dates, status)
vdomains whois mycoolapp.dev

# Compare live state against a domain config file
vdomains reconcile domains.json

The health command runs 7 checks: DNS resolution, nameservers, CNAME, SSL certificate, HTTPS connectivity, HTTP-to-HTTPS redirect, and security headers (HSTS, CSP, X-Frame-Options).

Auth & Contact

# Store Vercel token in OS keychain
vdomains login

# Remove stored token
vdomains logout

# Show current authenticated user
vdomains whoami

# View stored WHOIS contact info
vdomains contact

# Set WHOIS contact info (interactive)
vdomains contact set

# Remove stored contact info
vdomains contact rm

JSON Mode

Every command supports --json for structured output, making vdomains easy to script or use with AI agents:

# Pipe-friendly structured output
vdomains check mycoolapp.dev --json
vdomains list --json
vdomains health mycoolapp.dev --json

# Pipe domains between commands
echo "mycoolapp.dev" | vdomains check --json

# Set contact info from JSON
echo '{"firstName":"Jane","lastName":"Doe","email":"jane@example.com","phone":"+15551234567","address1":"123 Main St","city":"Portland","state":"OR","zip":"97201","country":"US"}' | vdomains contact set --json

Domain Config (Reconcile)

Define your expected domain state in a JSON file and detect drift:

{
  "domains": [
    {
      "domain": "myapp.com",
      "vercel": true,
      "dns": {
        "CNAME": ["cname.vercel-dns.com"]
      }
    },
    {
      "domain": "myapp.dev",
      "vercel": true
    }
  ]
}

vdomains reconcile domains.json

Reports ok, drift (with field-level diffs), or extra (domains in Vercel but not in config).

Exit Codes

Code	Meaning
0	Available / success / healthy
1	Taken / not available / drift detected / unhealthy
2	Error (auth, network, validation, usage)

Project-Aware Search

When you run vdomains search without a query inside a project directory, it infers a search term from the nearest package.json name field or the directory name. Useful for quickly checking if your project name is available as a domain.

Development

git clone https://github.com/brueshi/vdomains.git
cd vdomains
npm install
npm run build

# Run in development
npx tsx src/index.tsx search mycoolapp

# Type check
npm run typecheck

License

MIT