@unstoppabledomains/ud-cli 0.1.17 → 0.1.18

package/skills/ud-cli/SKILL.md

@@ -0,0 +1,189 @@
+---
+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
+
+```bash
+ud auth login                # OAuth (opens browser)
+ud auth login -k <key>       # API key (ud_mcp_ + 64 hex chars)
+ud auth status               # Check current auth
+```
+
+## 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
+
+```bash
+ud search <query>                        # Search for available domains
+ud search <query> --tlds com,io --limit 20
+ud tlds                                  # List available TLDs
+```
+
+### Portfolio
+
+```bash
+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 <domains...>       # Check pending operations
+```
+
+### Domain Settings
+
+```bash
+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
+
+```bash
+ud domains dns records list <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
+
+```bash
+ud domains dns nameservers list <domain>
+ud domains dns nameservers set-custom    # 2-12 hostnames (use --data)
+ud domains dns nameservers set-default   # Re-enable UD DNS management
+```
+
+### Hosting
+
+```bash
+ud domains hosting redirects list <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 status <domains...>     # Check generation
+ud domains hosting landers remove <domains...>     # Remove landing page
+```
+
+### ICANN Contacts
+
+```bash
+ud domains contacts list                 # List contacts (needed for DNS domain checkout)
+ud domains contacts create               # Create ICANN contact (use --data)
+```
+
+### Cart
+
+```bash
+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 get                              # 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 payment methods
+ud cart add-payment-method               # Get URL to add payment method
+```
+
+### Marketplace
+
+```bash
+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 get <domain>        # Get or create conversation
+ud marketplace leads messages            # List messages (--conversation-id)
+ud marketplace leads 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](references/search-and-purchase.md) for the full decision table.
+
+Quick version with smart add:
+```bash
+ud search mybusiness --format json       # Check availability + marketplace info
+ud cart add mybusiness.com mybusiness.io  # Auto-detects correct cart type
+ud cart get                              # Review pricing
+ud cart checkout --confirm               # Purchase
+```
+
+### DNS Domain Registration
+
+DNS domains (.com, .org, .net) require an ICANN contact before checkout.
+```bash
+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
+
+```bash
+ud domains dns nameservers list example.com   # Verify UD nameservers
+ud domains dns records list example.com
+ud domains dns records add example.com --type A --values 1.2.3.4
+ud domains operations example.com             # Track propagation
+```
+
+See detailed guides:
+- [Search & Purchase](references/search-and-purchase.md)
+- [DNS Management](references/dns-management.md)
+- [Cart & Checkout](references/cart-and-checkout.md)
+- [Marketplace](references/marketplace.md)
+
+## 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`.
+- **Checkout fails with no payment**: Use `ud cart payment-methods` to check, or `ud cart add-payment-method` to add one.

package/skills/ud-cli/references/cart-and-checkout.md

@@ -0,0 +1,108 @@
+# Cart & Checkout
+
+## Cart Operations
+
+```bash
+ud cart get                    # View cart contents and pricing
+ud cart remove                 # Remove items (use --data for item IDs)
+ud cart url                    # Get browser checkout URL
+ud cart payment-methods        # List saved cards and account balance
+ud cart add-payment-method     # Get URL to add a payment method
+```
+
+## Adding to Cart
+
+### Smart Add (Recommended)
+
+`ud cart add` auto-detects the domain source and routes to the correct subcommand:
+
+```bash
+ud cart add mybusiness.com mybusiness.io
+```
+
+### Explicit Subcommands
+
+```bash
+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
+```
+
+### Options
+
+- `--quantity <years>`: Registration or renewal period (1–10 years, default: 1)
+- `--domains-file <path>`: Read domain list from file (one per line)
+- Max 50 domains per cart-add call
+
+## ICANN Contact Requirement
+
+DNS domains (.com, .org, .net, etc.) **require an ICANN contact before checkout**. Checkout fails without one.
+
+```bash
+# Check for existing contacts
+ud domains contacts list
+
+# Create if needed
+ud domains contacts create --data '{
+  "firstName": "Jane",
+  "lastName": "Doe",
+  "email": "jane@example.com",
+  "phone": {"dialingPrefix": "+1", "number": "5551234567"},
+  "street": "123 Main St",
+  "city": "Austin",
+  "stateProvince": "TX",
+  "postalCode": "78701",
+  "countryCode": "US"
+}'
+```
+
+Using the account email for the contact enables instant verification. Otherwise, the contact enters `draft` state — wait a few seconds and re-check with `ud domains contacts list`.
+
+## Checkout
+
+```bash
+# Requires --confirm
+ud cart checkout --confirm
+```
+
+- Uses account credits by default
+- If balance is insufficient, pass a payment method: `--data '{"paymentMethodId":"pm_xxx"}'`
+- `contactId` auto-selects the most recent ICANN contact if omitted
+- Cart is cleared after successful checkout
+
+### Browser Checkout
+
+For users who prefer to review and pay in the browser:
+
+```bash
+ud cart url
+```
+
+## Pricing
+
+All prices are in **cents (USD)**: `5000` = $50.00.
+
+## Renewals
+
+```bash
+# Check expiration dates
+ud domains list --fields name,expiresAt
+
+# Add renewals (1–10 years per domain)
+ud cart add renewal mysite.com --quantity 2
+ud cart add renewal mysite.com othersite.com
+
+# Check payment and complete
+ud cart payment-methods
+ud cart checkout --confirm
+```
+
+## Troubleshooting
+
+- **Wrong cart tool**: Check `marketplace.source` from search results. Use smart `ud cart add` to avoid this.
+- **Missing ICANN contact**: Create one with `ud domains contacts create` before checkout.
+- **Contact in draft**: ID starts with `draft-`. Wait a few seconds and re-check with `ud domains contacts list`.
+- **No payment method**: Use `ud cart payment-methods` to verify, or `ud cart add-payment-method` to add one.
+- **Insufficient balance**: Pass `paymentMethodId` in checkout `--data`.

package/skills/ud-cli/references/dns-management.md

@@ -0,0 +1,141 @@
+# DNS Management
+
+## Prerequisites
+
+DNS record management only works when the domain uses UD default nameservers. Always check first:
+
+```bash
+ud domains dns nameservers list example.com
+```
+
+If the domain uses custom nameservers, switch back to UD defaults to manage records:
+
+```bash
+ud domains dns nameservers set-default --data '{"domains":["example.com"]}'
+```
+
+## Listing Records
+
+```bash
+ud domains dns records list example.com
+ud domains dns records list example.com --format json
+```
+
+## Adding Records
+
+### Single Record (shorthand flags)
+
+```bash
+# A record
+ud domains dns records add example.com --type A --values 1.2.3.4
+
+# CNAME with subdomain
+ud domains dns records add example.com --type CNAME --sub-name www --values example.com
+
+# MX record
+ud domains dns records add example.com --type MX --values "10 mail.example.com"
+
+# TXT record
+ud domains dns records add example.com --type TXT --values "v=spf1 include:_spf.google.com ~all"
+```
+
+### Bulk Records (--data)
+
+```bash
+ud domains dns records add example.com --data '{
+  "records": [
+    {"domain": "example.com", "type": "A", "values": ["1.2.3.4"]},
+    {"domain": "example.com", "type": "CNAME", "subName": "www", "values": ["example.com"]},
+    {"domain": "example.com", "type": "MX", "values": ["10 mail.example.com"]}
+  ]
+}'
+```
+
+### Upsert Modes
+
+If a record already exists, use `--upsert-mode`:
+
+```bash
+# Append new values alongside existing ones
+ud domains dns records add example.com --type A --values 5.6.7.8 --upsert-mode append
+
+# Replace existing values entirely
+ud domains dns records add example.com --type A --values 5.6.7.8 --upsert-mode replace
+```
+
+Without `--upsert-mode`, adding a duplicate record type returns a `NO_CHANGE` error.
+
+## Updating Records
+
+Get the record ID from `ud domains dns records list` first:
+
+```bash
+ud domains dns records update --data '{
+  "records": [{"recordId": "rec_abc123", "values": ["5.6.7.8"]}]
+}'
+```
+
+## Removing Records
+
+```bash
+# Remove specific record by ID
+ud domains dns records remove --data '{
+  "records": [{"recordId": "rec_abc123"}]
+}'
+
+# Remove ALL records (requires --confirm)
+ud domains dns records remove-all example.com --confirm
+```
+
+## Tracking Changes
+
+DNS changes are asynchronous. Track propagation:
+
+```bash
+ud domains operations example.com
+```
+
+## Custom Nameservers
+
+```bash
+# Set custom nameservers (disables DNS record management)
+ud domains dns nameservers set-custom --data '{
+  "domains": ["example.com"],
+  "nameservers": ["ns1.custom.com", "ns2.custom.com"]
+}'
+
+# Reset to UD defaults (re-enables DNS record management)
+ud domains dns nameservers set-default --data '{"domains":["example.com"]}'
+```
+
+Custom nameservers require 2–12 hostnames. DNSSEC DS records are optional.
+
+## Hosting & Redirects
+
+```bash
+# List hosting config
+ud domains hosting redirects list example.com
+
+# Add a redirect
+ud domains hosting redirects add --data '{
+  "records": [{"domain": "example.com", "type": "redirect-301", "target": "https://newsite.com"}]
+}'
+
+# Remove redirect
+ud domains hosting redirects remove --data '{
+  "records": [{"domain": "example.com"}]
+}'
+```
+
+## AI Landing Pages
+
+```bash
+# Generate an AI landing page (async)
+ud domains hosting landers generate example.com
+
+# Check status (pending → generating → hosted)
+ud domains hosting landers status example.com
+
+# Remove (destructive — deletes content and hosting config)
+ud domains hosting landers remove example.com
+```

package/skills/ud-cli/references/marketplace.md

@@ -0,0 +1,113 @@
+# Marketplace
+
+## Listing Domains for Sale
+
+```bash
+# List a domain with a price
+ud marketplace listings create mydomain.com --price 99.99
+
+# Bulk listing with --data
+ud marketplace listings create mydomain.com otherdomain.com --price 50.00
+
+# Update listing price
+ud marketplace listings update --price 75.00 --data '{
+  "listings": [{"listingId": "l123"}]
+}'
+
+# Cancel listings (requires --confirm)
+ud marketplace listings cancel --confirm --data '{
+  "listingIds": ["l123"]
+}'
+```
+
+### Listing Options
+
+Prices are specified in dollars via `--price` (converted to cents automatically). For advanced settings, use `--data`:
+
+```bash
+ud marketplace listings create mydomain.com --data '{
+  "domains": [{
+    "name": "mydomain.com",
+    "priceInCents": 9999,
+    "acceptOffers": true,
+    "validityInDays": 365
+  }]
+}'
+```
+
+## Offers
+
+```bash
+# List incoming offers
+ud marketplace offers list
+
+# Filter by status
+ud marketplace offers list --data '{"status": "pending"}'
+
+# Accept an offer
+ud marketplace offers respond --data '{
+  "offers": [{"offerId": "o123", "action": "accept"}]
+}'
+
+# Reject an offer
+ud marketplace offers respond --data '{
+  "offers": [{"offerId": "o123", "action": "reject"}]
+}'
+```
+
+## Domain Conversations (Leads)
+
+Leads are buyer-seller conversations about domains.
+
+```bash
+# List all conversation leads
+ud marketplace leads list
+
+# Get or create a conversation for a domain
+ud marketplace leads get mydomain.com
+
+# List messages in a conversation
+ud marketplace leads messages --conversation-id 42
+
+# Send a message
+ud marketplace leads send --conversation-id 42 --content "Thanks for your interest!"
+```
+
+### When to Use Leads
+
+- When a domain is `registered-listed-for-offers`, direct users to the `purchaseUrl` or use leads to contact the seller.
+- When a domain is `registered-not-for-sale` and `listingSettings.contactSellerEnabled` is true, use `ud marketplace leads get <domain>` to contact the owner.
+
+## Workflow: List → Sell
+
+```bash
+# 1. Verify ownership
+ud domains list --fields name
+
+# 2. Create listing
+ud marketplace listings create mydomain.com --price 99.99
+
+# 3. Monitor offers
+ud marketplace offers list
+
+# 4. Respond to offers
+ud marketplace offers respond --data '{
+  "offers": [{"offerId": "o123", "action": "accept"}]
+}'
+```
+
+## Workflow: Browse → Buy via Marketplace
+
+```bash
+# 1. Search for listed domains
+ud search premium-name --format json
+
+# 2. Check marketplace.source and marketplace.status
+
+# 3. Add to cart (use smart add)
+ud cart add premium-name.com
+
+# 4. Checkout
+ud cart get
+ud cart checkout --confirm
+```

package/skills/ud-cli/references/search-and-purchase.md

@@ -0,0 +1,144 @@
+# Search & Purchase Domains
+
+The most common workflow: search for domains, add to cart, and purchase.
+
+## Quick Path (Smart Add)
+
+`ud cart add` auto-detects the marketplace source, so you can skip the decision table:
+
+```bash
+ud search mybusiness --format json
+ud cart add mybusiness.com mybusiness.io
+ud cart get
+ud cart checkout --confirm
+```
+
+## Full Decision Table
+
+After `ud search`, each result includes `marketplace.source` and `marketplace.status`. These determine which cart command to use:
+
+| `marketplace.source` | `marketplace.status` | Cart command |
+|---|---|---|
+| `unstoppable_domains` | `available` | `ud cart add registration <domain>` |
+| `unstoppable_domains` | `registered-listed-for-sale` | `ud cart add listed <domain>` |
+| `unstoppable_domains` | `registered-listed-for-offers` | Cannot cart. Direct user to `purchaseUrl` to make an offer. |
+| `afternic` | `registered-listed-for-sale` | `ud cart add afternic <domain>` |
+| `sedo` | `registered-listed-for-sale` | `ud cart add sedo <domain>` |
+| any | `registered-not-for-sale` | Not purchasable. Contact seller via `ud marketplace leads get <domain>`. |
+| any | `unavailable` or `invalid` | Not purchasable. Suggest alternatives. |
+
+Using the wrong cart command is the most common error. Smart `ud cart add` avoids this.
+
+## Step-by-Step
+
+### 1. Search
+
+```bash
+# Basic search
+ud search mybusiness
+
+# With options
+ud search mybusiness --tlds com,io,org --limit 20
+
+# JSON for scripting
+ud search mybusiness --format json
+```
+
+Default TLDs when none specified: com, net, org, ai, io. Max 5 TLDs, max 10 queries per request.
+
+### 2. Add to Cart
+
+```bash
+# Smart add (recommended) — auto-detects source
+ud cart add mybusiness.com mybusiness.io
+
+# Or explicit type
+ud cart add registration mybusiness.com
+ud cart add listed premium-domain.com
+ud cart add afternic afternic-domain.com
+ud cart add sedo sedo-domain.com
+
+# Renewals (domains you already own)
+ud cart add renewal mysite.com --quantity 2   # 2-year renewal
+
+# Multi-year registration
+ud cart add registration mybusiness.com --quantity 3
+```
+
+### 3. Review Cart
+
+```bash
+ud cart get
+```
+
+All prices are in **cents (USD)**: `5000` = $50.00.
+
+### 4. Payment
+
+```bash
+# Check available payment methods
+ud cart payment-methods
+
+# Add a payment method if needed
+ud cart add-payment-method    # Returns URL to add card in browser
+```
+
+### 5. Checkout
+
+```bash
+# Complete purchase (requires --confirm)
+ud cart checkout --confirm
+
+# Or get a browser checkout URL
+ud cart url
+```
+
+If using account credits but the balance is insufficient, pass `--data '{"paymentMethodId":"pm_xxx"}'` to use a card.
+
+## Lease-to-Own (LTO)
+
+Only UD marketplace listings (`ud cart add listed`) support LTO. Check search results for `listingSettings.leaseToOwnOptions`:
+
+```bash
+ud cart add listed premium.com --data '{
+  "domains": [{
+    "name": "premium.com",
+    "leaseToOwnOptions": {
+      "type": "equal_installments",
+      "termLength": 12
+    }
+  }]
+}'
+```
+
+- `type`: `equal_installments` or `down_payment_plus_equal_installments`
+- `termLength`: 2–120 months (must not exceed `maxTermLength` from search results)
+- `downPaymentPercentage`: 10–90% (only for `down_payment_plus_equal_installments`)
+
+## DNS Domain Registration
+
+DNS domains (.com, .org, .net, etc.) require an ICANN contact before checkout. Checkout will fail without one.
+
+```bash
+# Check for existing contacts
+ud domains contacts list
+
+# Create one if needed (use account email for instant verification)
+ud domains contacts create --data '{
+  "firstName": "Jane",
+  "lastName": "Doe",
+  "email": "jane@example.com",
+  "phone": {"dialingPrefix": "+1", "number": "5551234567"},
+  "street": "123 Main St",
+  "city": "Austin",
+  "stateProvince": "TX",
+  "postalCode": "78701",
+  "countryCode": "US"
+}'
+
+# Then add and checkout
+ud cart add registration example.com
+ud cart checkout --confirm
+```
+
+Contacts created with the user's account email are auto-verified. Otherwise the contact enters `draft` state — wait a few seconds and re-check with `ud domains contacts list`.