vd — the vybe.domains CLI

Search, check, and manage domains from your terminal. Built agent-first: every command emits a stable JSON envelope, exit codes are semantic, and the whole command surface is machine-discoverable.

Status: v0.1 (read-only slice). Design: syntax-ideas/2026-09-15-cli.md. Money-moving commands (buy, renew, offer, …) are designed but not shipped; invoking one exits 8 with a pointer.

Install

npm install -g vybe.domains   # installs the `vd` and `vybe` commands (Node ≥ 20)
vd check example.com

npx vybe.domains check example.com   # or zero-install

Heads-up: VisiData also installs a vd binary. If you have it, use the vybe bin name or your own alias.

From this repo (development)

Requires Node ≥ 23.6 (runs the TypeScript sources directly):

node cli/bin/vd.mjs check example.com     # from the repo root
cd cli && npm run build && npm link       # or: build dist/vd.mjs + put `vd` on PATH

Quickstart

vd                                  # dashboard (or welcome, if signed out)
vd example.com                      # smart card: availability or your entry
vd check example.com example.io     # exact availability + price
vd search revybe --tlds com,io,ai   # spread a name across TLDs
vd tlds                             # priced TLD pool
vd supported .dev && echo "buyable" # exit 0 = registrable, 5 = not
vd .dev                             # same check, dot-rule shorthand

vd login                            # email+password (account: vybed.vercel.app)
vd ls --expiring 30d                # your portfolio
vd info example.com                 # detail card
vd dns example.com                  # DNS records (stable rec_… ids)
vd wallet                           # credits, tier, budget
vd transactions                     # billing ledger
vd auth token create --save         # API key: enables `vd find`, agents, REST
vd find "fitness app for climbers"  # AI name ideas (needs API key)

v0.1 commands

| Command | Aliases / sugar | Auth | |---|---|---| | vd domain check <domain…> | vd check | — | | vd domain search <query> | vd search, vd s | — | | vd domain find "<idea>" | vd find | API key | | vd domain ls | vd ls, vd list | session | | vd domain get <domain> | vd info, vd <domain> (owned) | session | | vd dns ls <domain> | vd dns <domain>, vd <domain> dns | session | | vd tld ls [query] | vd tlds | — | | vd tld supported [tld] | vd supported, vd .dev | — | | vd tld unsupported [tld] | vd unsupported | — | | vd tx ls | vd transactions, vd tx | session | | vd wallet get | vd wallet | session | | vd auth login/logout/whoami | vd login, vd logout, vd whoami | — | | vd auth token ls/create/rm | — | session | | vd help / version / commands / schema | -h, -V | — |

The agent contract

• Output: human tables on a TTY; a single JSON envelope when piped or with -o json. Also -o ids (newline ids for piping) and -o ndjson. vd ls -o ids | xargs -n1 vd info composes.
• Envelope (stable, versioned vd/1):

  { "ok": true, "schema": "vd/1", "command": "dns.ls", "data": [...], "meta": { "ms": 214 } }
  { "ok": false, "schema": "vd/1", "command": "domain.ls",
    "error": { "code": "E_AUTH_REQUIRED", "message": "…", "fix": "vd login", "retryable": false } }

  error.fix is a runnable command whenever one exists.
• Exit codes: 0 ok · 1 internal · 2 usage · 3 auth · 4 forbidden · 5 not found · 6 conflict · 7 upstream (retry) · 8 precondition · 9 confirmation required · 10 payment required · 11 rate limited (retry).
• Discovery: vd commands -o json (full command tree, aliases, exit codes), vd schema <command> (JSON Schema per command).
• No prompts off-TTY, ever. Non-interactive login uses env vars; nothing hangs waiting for stdin.

Auth & environment

| Variable | Purpose | |---|---| | VD_EMAIL / VD_PASSWORD | Non-interactive vd login | | VD_TOKEN | Supabase access token — skips stored sessions (CI/agents) | | VD_API_KEY | vybe API key (vybe_live_…) for public endpoints (vd find) | | VD_OUTPUT | Default output mode (table/json/ids/ndjson) | | VD_CONFIG_DIR / VD_CACHE_DIR | Override ~/.config/vd / ~/.cache/vd | | VD_BASE_URL, VD_PROJECT_ID, VD_ANON_KEY, VD_AUTH_URL | Point at a different backend | | NO_COLOR, TERM=dumb | Disable color (also --no-color) |

Sessions are stored in ~/.config/vd/credentials.json (mode 0600) and refreshed automatically. vd auth token create --save stores an API key in ~/.config/vd/config.json.

Development

cd cli
npm test          # node:test, no deps, no network (fake fetch)
npm run build     # esbuild single-file bundle → dist/vd.mjs

Architecture (see design doc §8): src/registry.ts is the single source of truth — commands are data (args, flags, aliases, examples), and the parser, help, vd commands, vd schema, and the registry lint tests are all generated from it. Handlers are pure (ctx, invocation) → result functions in src/commands/; src/main.ts#run() is the composition root and the test entry. DNS record types and the supported-TLD catalog are imported from supabase/functions/server/ so the CLI cannot drift from the backend.