Porkbun Domain Price Checker

A Python CLI tool for bulk querying domain pricing information from the Porkbun API.

Features

Bulk domain price queries from a file
Domain availability checking - Shows if domains are available for registration
JSON Lines output format
SQLite caching to avoid duplicate API calls
Progress bars by default - Visual feedback for all queries (disable with -q)
Aggressive 429 retry handling
Async implementation for performance
Multiple credential sources (CLI, env vars, config file)
Debug mode with detailed HTTP request/response logging
Single domain queries with -d flag

Installation

uv pip install -e .

Configuration

API credentials can be provided in three ways (in order of priority):

1. Command Line Arguments

porkbun test_domains.txt --api-key pk1_... --secret-key sk1_...

2. Environment Variables

export PORKBUN_API_KEY=pk1_...
export PORKBUN_SECRET_KEY=sk1_...
porkbun test_domains.txt

3. Config File

Create ~/.config/porkbun/cli.json:

{
  "api_key": "pk1_...",
  "secret_key": "sk1_..."
}

Then simply run:

porkbun test_domains.txt

Usage

Query from File

# Basic usage (shows progress bars by default)
porkbun test_domains.txt

# Quiet mode (disable progress bars, JSON only)
porkbun test_domains.txt --quiet
porkbun test_domains.txt -q

# Refresh data from API and update cache
porkbun test_domains.txt --refresh

# Clear cache before running
porkbun test_domains.txt --clear-cache

# Debug mode (shows full HTTP requests/responses and status)
porkbun test_domains.txt --debug

Query Single/Multiple Domains

# Single domain (shows progress bar by default)
porkbun -d example.com
porkbun --domain example.com

# Multiple domains (shows progress for each)
porkbun -d example.com -d test.net -d sample.org

# Quiet mode for clean JSON output (useful for piping)
porkbun -d example.com -q
echo "example.com\ntest.net" | porkbun --quiet

# Combined with other flags
porkbun -d example.com --refresh --debug

Debug Mode

When --debug is specified, the tool shows:

Status messages (to stderr): - [API] Fetching pricing for domain.com... - When making API calls - [CACHE] Using cached result for domain.com - When using cached data
Full HTTP details (to stderr): - Complete request headers and payload - Complete response headers and body - Rate limit retry information

Example output:

$ porkbun -d example.com -d test.net --debug

[API] Fetching pricing for example.com...
================================================================================
DEBUG: REQUEST
URL: POST https://api.porkbun.com/api/json/v3/pricing/get
Headers: {'accept': '*/*', 'accept-encoding': 'gzip, deflate', ...}
Payload: {"apikey": "pk1_...", "secretapikey": "sk1_..."}
================================================================================
DEBUG: RESPONSE
Status: 200 OK
Headers: {'date': '...', 'content-type': 'application/json', ...}
Body: {"status":"SUCCESS","pricing":{...}}
================================================================================
{"domain": "example.com", "tld": "com", "pricing": {"registration": "11.08", ...}}

[CACHE] Using cached result for test.net
{"domain": "test.net", "tld": "net", "pricing": {"registration": "12.52", ...}}

Note: JSON results always go to stdout, debug/status messages go to stderr for easy separation.

Progress Bars

By default, the tool shows real-time progress bars for each domain being processed. Use -q or --quiet to disable this for clean JSON-only output.

Features: - Overall progress bar showing total completion - Individual progress bars for each domain - Color-coded status indicators: - 🟡 Yellow: In progress (checking cache or fetching from API) - 🟢 Green: Complete or from cache - 🔴 Red: Error occurred - Shows whether data came from cache or API

Example output (default):

  Processing domains...      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%
  example.com - ✓ From cache ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%
  test.net - ✓ Complete      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%
  sample.org - ✓ Complete    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%

Disable progress bars for piping:

# Clean JSON output only (no progress bars)
porkbun domains.txt -q > results.jsonl
porkbun -d example.com --quiet | jq .

When to use quiet mode: - Piping output to other tools - Scripting and automation - When you only want the JSON output - Redirecting to files

Input Format

Create a text file with one domain per line:

example.com
google.com
test.net

Output Format

JSON Lines format with pricing and availability information:

{"domain": "example.com", "tld": "com", "pricing": {"registration": "11.08", "renewal": "11.08", "transfer": "11.08", "coupons": []}, "available": false}
{"domain": "myuniquedomain.com", "tld": "com", "pricing": {"registration": "11.08", "renewal": "11.08", "transfer": "11.08", "coupons": []}, "available": true}

Fields:

domain - The queried domain name
tld - Top-level domain (e.g., "com", "net", "org")
pricing - Pricing information from Porkbun
registration - Price to register the domain
renewal - Annual renewal price
transfer - Price to transfer the domain
coupons - Array of available coupons
available - Boolean indicating if the domain is available for registration at Porkbun
true - Domain is available
false - Domain is taken
null - Availability check failed
premium - (Optional) Set to true if domain is premium pricing

Cache

Pricing and availability data is cached in ~/.local/share/porkbun/cache.sqlite to avoid redundant API calls and speed up repeated queries.

Cache Behavior:

Default: Uses cached data when available (fast, no API calls)
--refresh: Fetches fresh data from API and updates the cache for queried domains
--clear-cache: Deletes all cached data before running

Example Workflow:

# First run - queries API and caches results
porkbun -d example.com

# Second run - uses cached data (instant)
porkbun -d example.com

# Update cached data - fetches fresh data and updates cache
porkbun -d example.com --refresh

# Future runs use the updated cache
porkbun -d example.com

The cache stores both pricing and availability information, so using --refresh is useful when you want to check if previously unavailable domains have become available.