dfseo-cli — DataForSEO CLI for AI Agents

SEO data from your terminal. JSON-first for agents, human-friendly for you.

# Auto-detects your terminal — outputs table for humans, JSON for pipes
dfseo serp google "best crm software" --location "United States"

Installation

pip install dfseo

Quick Start

Set your DataForSEO credentials:

# Via environment variables (recommended for agents)
export DATAFORSEO_LOGIN="your@email.com"
export DATAFORSEO_PASSWORD="your_api_password"

# Or via interactive setup
dfseo auth setup

Test your setup:

dfseo auth status

Usage Examples

Google SERP

# Basic search — auto-detects output format (table in terminal)
dfseo serp google "email hosting provider"

# With location and language
dfseo serp google "email hosting" --location "United States" --language "English"

# Force JSON for scripting
dfseo serp google "email hosting" --output json | jq '.organic_results[0].url'

# CSV for Excel import
dfseo serp google "email hosting" --output csv > results.csv

# Autocomplete suggestions
dfseo serp autocomplete "best crm"

Example output:

Query: email hosting provider
Location: United States | Language: English | Device: desktop
Results: 100 | Cost: $0.0020

SERP Features: featured_snippet, people_also_ask

┏━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃  # ┃ Domain         ┃ Title / Description                            ┃
┡━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│  1 │ example.com    │ Best Email Hosting Provider 2026               │
│    │                │ Compare the top email hosting services...      │
│  2 │ another.com    │ Email Hosting for Small Business               │
│    │                │ Affordable and reliable email solutions...     │
└────┴────────────────┴────────────────────────────────────────────────┘

Keyword Research

# Get search volume and keyword difficulty
dfseo keywords volume "email hosting" "smtp provider" "email server" \
  --location "United States"

# Find long-tail keyword suggestions
dfseo keywords suggestions "email hosting" \
  --min-volume 100 \
  --max-difficulty 40 \
  --limit 50

# Bulk keyword difficulty (up to 1000 keywords)
dfseo keywords difficulty --from-file keywords.txt --location "United States"

# Find all keywords a domain ranks for
dfseo keywords ranked-keywords "competitor.com" --limit 100

# Historical search volume trends
dfseo keywords historical-volume "email hosting"

# Find keyword overlap between domains
dfseo keywords domain-intersection "site1.com" "site2.com"

# Get trending searches
dfseo keywords top-searches

Site Audit

# Full site audit (crawls up to 100 pages)
dfseo site audit "example.com" --max-pages 100

# Quick single-page check
dfseo site audit "https://example.com/page" --max-pages 1

# With JavaScript execution
dfseo site audit "example.com" --enable-javascript --load-resources

Backlink Analysis

# Backlink profile summary
dfseo backlinks summary "example.com"

# List backlinks with filters
dfseo backlinks list "example.com" --dofollow-only --sort rank --limit 50

# Referring domains
dfseo backlinks referring-domains "example.com" --min-backlinks 5

# Link gap analysis (find competitor backlinks you're missing)
dfseo backlinks gap "your-site.com" "competitor1.com" "competitor2.com"

Content Analysis

# Search web content mentioning a keyword
dfseo content search "email hosting"

# Get aggregate content metrics
dfseo content summary "email hosting"

# Analyze sentiment of content
dfseo content sentiment "email hosting"

Domain Analytics

# Detect technologies used by a domain
dfseo domain technologies "example.com"

Compare Search Engines

dfseo serp compare "email hosting" --engines google,bing --location "United States"

Available Locations & Languages

# List all locations
dfseo serp locations

# Search for specific location
dfseo serp locations --search "united states"

# List languages
dfseo serp languages --search "english"

Output Formats

The CLI auto-detects your environment:

• Interactive terminal → table (human-readable, uses rich)
• Pipe/redirect → json (compact, machine-readable)

Override with --output:

dfseo serp google "keyword" --output json        # Force JSON
dfseo serp google "keyword" --output json-pretty  # Indented JSON
dfseo serp google "keyword" --output table        # Human table
dfseo serp google "keyword" --output csv          # CSV export

Configuration

Set defaults to avoid repeating flags:

# Set defaults
dfseo config set location "United States"
dfseo config set language "English"
dfseo config set device desktop

# Show current config
dfseo config show

Now you can run:

dfseo serp google "keyword"  # Uses your configured defaults automatically

Authentication Priority

Credentials are resolved in this order:

1. CLI flags — --login and --password
2. Environment variables — DATAFORSEO_LOGIN and DATAFORSEO_PASSWORD
3. Config file — ~/.config/dfseo/config.toml

Exit Codes

Code	Meaning
0	Success
1	Generic error
2	Authentication error (check credentials)
3	Rate limit exceeded (wait and retry)
4	Invalid parameters
5	Insufficient balance (add funds)

API Coverage

API	Commands	Count
SERP	google, bing, youtube, compare, autocomplete, locations, languages	7
Keywords	volume, suggestions, ideas, difficulty, search-intent, for-site, ads-volume, ads-suggestions, ranked-keywords, domain-rank, historical-rank, historical-volume, serp-competitors, competitors-domain, domain-intersection, relevant-pages, subdomains, top-searches, categories-for-domain, page-intersection	20
On-Page	audit, instant, crawl, summary, pages, links, duplicates, redirects, non-indexable, resources, lighthouse, tasks, keyword-density, microdata, waterfall	15
Backlinks	summary, list, anchors, referring-domains, history, competitors, gap, pages, bulk ranks, bulk backlinks, bulk spam-score, bulk referring-domains, bulk new-lost	13
Content	search, summary, sentiment	3
Domain	technologies	1
Utility	auth setup, auth status, config set, config show, describe	5

For AI Agents

# JSON output for parsing
dfseo serp google "keyword" --output json | jq -r '.organic_results[0].url'

# Quiet mode (no progress bars)
dfseo serp google "keyword" --quiet

# Check SKILL.md for integration examples

License

MIT