ud-cli

name	ud-cli
description	Domain registrar CLI — search, register, and manage domains via Unstoppable Domains. Use when the user needs domain registration, DNS record management, marketplace listings, cart/checkout, domain transfers, or any domain management task.
allowed-tools	Bash(ud:*)

Domain Management with ud-cli

Prerequisites

ud auth signup               # Create account interactively
ud auth login                # OAuth sign-in (opens browser)
ud auth login -k <key>       # API key (ud_mcp_ + 64 hex chars)
ud auth status               # Check current auth

Account Creation

Interactive — ud auth signup with no arguments prompts for email, password, and verification code.

Headless (recommended for agents) — two-step flow, no TTY required:

# Step 1: Create account — prints the verify command to stdout
ud auth signup --email [e-mail] --password 'SecurePass1!'

# Step 2: Verify with the code from the user's email
ud auth signup --token <session_token> --code ABC123

Step 1 outputs a ready-to-run verify command with the session token pre-filled. Password requirements: min 8 chars, uppercase, lowercase, number, special character.

Global Options

--format json|table|csv      Output format (default: table)
--fields [cols]              Show available fields or select columns (e.g., name,expiresAt)
--data <json>                JSON request body for complex operations
--file <path>                Read JSON request body from file
--domains-file <path>        Read domain list from file (one per line)
--quiet                      Suppress output except errors
--env production|sandbox     Override environment

Commands

Search & Discovery

ud search <query>                        # Search for available domains
ud search <query> --tlds com,io --limit 20
ud tlds                                  # List available TLDs

Portfolio

ud domains list                          # List your domains
ud domains get <domains...>              # Detailed domain info
ud domains push <domains...>             # Transfer to another user (requires --otp-code)
ud domains operations show <domains...>  # Show pending operations

Domain Settings

ud domains tags add <domains...> --tags tag1,tag2
ud domains tags remove <domains...> --tags tag1,tag2
ud domains flags update <domains...>     # WHOIS privacy, transfer lock
ud domains auto-renewal update <domains...> --enabled true|false

DNS Records

ud domains dns records show <domain>
ud domains dns records add <domain> --type A --values 1.2.3.4
ud domains dns records update            # Update by record ID (use --data)
ud domains dns records remove            # Remove by record ID (use --data)
ud domains dns records remove-all <domains...> --confirm

DNS Nameservers

ud domains dns nameservers show <domain>
ud domains dns nameservers set-custom    # 2-12 hostnames (use --data)
ud domains dns nameservers set-default   # Re-enable UD DNS management

Hosting

ud domains hosting redirects show <domain>
ud domains hosting redirects add         # 301/302 redirects (use --data)
ud domains hosting redirects remove      # Remove redirect config
ud domains hosting landers generate <domains...>   # AI landing page
ud domains hosting landers show <domains...>       # Show lander status
ud domains hosting landers remove <domains...>     # Remove landing page

ICANN Contacts

ud domains contacts list                 # List contacts (needed for DNS domain checkout)
ud domains contacts create               # Create ICANN contact (use --data)

Cart

ud cart add [domain...]                  # Smart add — auto-detects source type
ud cart add registration <domains...>    # Fresh registration
ud cart add listed <domains...>          # UD marketplace listing
ud cart add afternic <domains...>        # Afternic marketplace
ud cart add sedo <domains...>            # Sedo marketplace
ud cart add renewal <domains...>         # Renew owned domains
ud cart list                             # View cart with pricing
ud cart remove                           # Remove items
ud cart checkout --confirm               # Complete purchase
ud cart url                              # Get browser checkout URL
ud cart payment-methods list              # List payment methods
ud cart payment-methods add              # Get URL to add payment method

Marketplace

ud marketplace listings create <domains...> --price 99.99
ud marketplace listings update           # Update price/settings (use --data)
ud marketplace listings cancel --confirm
ud marketplace offers list
ud marketplace offers respond            # Accept/reject offers (use --data)
ud marketplace leads list
ud marketplace leads open <domain>       # Inquire about a domain
ud marketplace leads messages list       # List messages (--conversation-id)
ud marketplace leads messages send       # Send message (--conversation-id --content)

Key Workflows

Search and Purchase (most common)

Search results include marketplace.source and marketplace.status — these determine which cart tool to use. See references/search-and-purchase.md for the full decision table.

Quick version with smart add:

ud search mybusiness --format json       # Check availability + marketplace info
ud cart add mybusiness.com mybusiness.io  # Auto-detects correct cart type
ud cart list                             # Review pricing
ud cart checkout --confirm               # Purchase

DNS Domain Registration

DNS domains (.com, .org, .net) require an ICANN contact before checkout.

ud domains contacts list                 # Check for existing contacts
ud domains contacts create --data '...'  # Create if needed
ud cart add registration example.com
ud cart checkout --confirm

DNS Setup

ud domains dns nameservers show example.com   # Verify UD nameservers
ud domains dns records show example.com
ud domains dns records add example.com --type A --values 1.2.3.4
ud domains operations show example.com        # Track propagation

See detailed guides:

• Search & Purchase
• DNS Management
• Cart & Checkout
• Marketplace

Key Constraints

Constraint	Limit
Max domains per bulk operation	50
Max search queries per request	10
Max TLDs per search	5 (default: com, net, org, ai, io)
Prices	In cents (USD) — 5000 = $50.00
Registration/renewal quantity	1–10 years
Custom nameservers	2–12 hostnames; disables DNS record management

Safety Confirmations

Operation	Required Flag
ud cart checkout	--confirm
ud domains dns records remove-all	--confirm
ud marketplace listings cancel	--confirm
ud domains push	--otp-code (6-digit MFA)

Error Handling

• 401/403: Re-authenticate with ud auth login
• Wrong cart tool: Most common error. Check marketplace.source from search results. Use ud cart add (smart) to avoid this.
• Missing ICANN contact: Required for DNS domains. Create with ud domains contacts create.
• DNS changes not appearing: Changes are async. Check with ud domains operations show.
• Checkout fails with no payment: Use ud cart payment-methods list to check, or ud cart payment-methods add to add one.