DFS Keyword Research

The dfs CLI wraps the DataForSEO API and returns only the fields that matter. Raw API responses are 15-30KB per query; dfs compresses them to 1-2KB. This keeps your context window clean when doing multi-step research.

Prerequisites

The CLI must be installed globally before any commands will work:

npm install -g data-4-seo-cli

Auth

Check if credentials are already stored:

dfs whoami

If not authenticated, set environment variables or store credentials permanently:

export DATAFORSEO_LOGIN=your_login
export DATAFORSEO_PASSWORD=your_password
# Or store permanently:
dfs login --login "$DATAFORSEO_LOGIN" --password "$DATAFORSEO_PASSWORD"

Choosing the right command

Pick the command based on what you need:

Commands

dfs volume

dfs volume "seo tools" "keyword research" "backlink checker"

Returns: keyword, volume, cpc, difficulty, competition, intent, trend

Accepts up to 50 keywords in one call. The trend column shows 12 months of search volume.

dfs suggestions

dfs suggestions "seo tools" -n 15

Returns: keyword, volume, cpc, difficulty, competition

Takes one seed keyword. Use -n to control how many suggestions.

dfs related

dfs related "keyword research" -n 15

Returns: keyword, volume, cpc, difficulty, competition

Semantically related terms, not just autocomplete matches. Good for finding angles you might miss.

dfs difficulty

dfs difficulty "seo tools" "keyword research" "backlink checker"

Returns: keyword, difficulty

Use this when you only need difficulty scores and want the smallest possible response.

dfs serp

dfs serp "best seo tools" --target yourdomain.com

Features and PAA questions go to stderr. Organic results go to stdout: position, domain, title, url

The --target flag highlights where a specific domain ranks. Use --json for the full structured result including features, snippets, and PAA questions.

dfs ranked

dfs ranked ahrefs.com -n 20

Returns: keyword, position, volume, cpc, url

Keywords sorted by volume. Use this to understand a competitor's keyword portfolio.

dfs overlap

dfs overlap ahrefs.com semrush.com -n 20

Returns: keyword, pos1, pos2, volume, cpc

Shows keywords both domains rank for with their respective positions. Great for finding where you're losing to a competitor.

dfs competitors

dfs competitors "seo tools" "keyword research tool" -n 10

Returns: domain, avg_position, visibility, keywords_count

Pass one or more keywords to discover which domains compete in those SERPs.

dfs content

dfs content "https://example.com/page"
dfs content "https://example.com/page" --full --json

TSV returns: url, title, word_count, headings_count (headings detail on stderr). JSON with --full returns the complete headings tree and content preview.

Output formats

Use --table when presenting results to the user. Use default TSV when processing data internally. Use --json when you need to parse specific fields programmatically.

Options

-l, --location <code>    Location code (default: 2840 = US)
    --language <code>     Language code (default: en)
-n, --limit <n>          Max results (default: 50)
    --no-cache           Force fresh API call

Look up location and language codes with dfs locations <search> and dfs languages <search>.

Caching

Results are cached automatically to avoid duplicate API costs. Repeated queries within the TTL are free:

Use --no-cache only when you need guaranteed fresh data.

Workflow references

For detailed workflows, step-by-step guides, and interpretation tips, read the relevant reference file:

Read only the reference you need for the current task.