DataForSEO API CLI (d4s)

A single, zero-dependency CLI for the DataForSEO API — 84 endpoints covering keyword research, SERP, backlinks, on-page audits, competitors, and the 2026 LLM/AI-mentions module (track how often domains/keywords appear in ChatGPT & AI answers).

Direct HTTPS calls — no MCP server required. Works as a standalone CLI and as a pi / Codex agent skill.

The endpoint definitions are extracted from the official dataforseo-mcp-server (Apache-2.0), so coverage tracks the MCP server without the MCP transport overhead.

Why

The official DataForSEO MCP server is great inside MCP-aware agents (Claude Code, Codex), but:

• many agent harnesses (e.g. pi) have no MCP support by design,
• MCP adds a stdio handshake + process spawn per call,
• sometimes you just want d4s volume --keywords p0420 in a shell script or CI.

d4s gives you the same 84 endpoints as a plain CLI, pipeable, scriptable, and auto-loadable as an agent skill.

Install

Option A — npm (recommended)

npm install -g dataforseo-api-cli

Option B — git clone (zero-build — dist/ is committed)

git clone https://github.com/catorch/dataforseo-api-cli.git
cd dataforseo-api-cli
npm install -g .          # links the `d4s` binary

Option C — as a pi / Codex skill

Add this repo (or its npm package) to your agent's skill paths. The bundled skills/dataforseo/SKILL.md auto-loads. The agent then calls the installed d4s binary via bash.

Requires Node ≥ 18 (uses native fetch).

Credentials

The CLI resolves credentials in this order:

1. Flags: --username login@you --password SECRET
2. Env vars: DATAFORSEO_USERNAME / DATAFORSEO_PASSWORD
3. File (default ~/.config/dataforseo/env, chmod 600):

   export DATAFORSEO_USERNAME='login@you'
   export DATAFORSEO_PASSWORD='your-api-password'

The default env file is optional. If you explicitly set --env-file PATH or DATAFORSEO_ENV_FILE, that file must exist and contain valid export KEY='value' lines.

Get credentials at app.dataforseo.com. Some modules (Backlinks, AI Optimization) require their subscriptions to be activated.

Usage

d4s <command> [--params-as-flags] [--tsv | --json | --raw]
d4s list [module]            # list all 84 tools / one module
d4s help <command>           # show params + endpoint for a command
d4s --version

Every command accepts its full snake_case name (d4s kw_data_google_ads_search_volume ...) or a short alias.

Cheat sheet

| Want | Command | |---|---| | Search volume for keywords | d4s volume --keywords "a,b,c" --tsv | | Volume + difficulty + intent + CPC | d4s keyword-overview --keywords "a,b" --tsv | | Bulk organic keyword difficulty | d4s difficulty --keywords "a,b" --tsv | | Keyword ideas / related / suggestions | d4s ideas --keywords "seed" · d4s related --keyword "seed" · d4s suggestions --keyword "seed" | | Live Google SERP (incl. AI Overview) | d4s serp --keyword "x" --lang en --tsv | | Keywords a domain ranks for | d4s ranked-keywords --target "example.com" --tsv | | Domain competitors | d4s competitors --target "example.com" | | Backlinks summary | d4s backlinks --target "example.com" | | On-page Lighthouse audit | d4s lighthouse --url "https://example.com" | | Mentions in AI/LLM answers (2026) | d4s llm-mentions-search --target '[{"keyword":"x"}]' |

Passing parameters

• Scalars: --keyword "p0420 code" --depth 100
• Arrays of strings: --keywords a,b,c (comma-split) or repeatable --keywords a --keywords b
• Arrays of objects (e.g. LLM-mentions targets): pass JSON — --target '[{"keyword":"p0420"}]'
• Intersection targets: pass arrays normally. For endpoints whose API payload requires numbered objects, d4s converts them automatically:

  d4s backlinks-domain-intersection \
    --targets moz.com,ahrefs.com \
    --exclude-targets semrush.com \
    --limit 5

• Booleans: --include-subdomains (true) / --no-include-subdomains (false)
• Shortcuts: --location "United States" and --lang en map to the tool's location/language fields
• DataForSEO defaults are applied automatically; required params are validated up front

Output modes

• default — pretty JSON of tasks[0].result
• --tsv — tab-separated view (curated columns for list-shaped tools; generic for others). Pipe to column -t or a spreadsheet.
• --raw — full raw API response envelope
• D4S_DEBUG=1 — print the request method/path/body to stderr

Modules (84 tools)

| Module | Tools | Highlights | |---|---:|---| | dataforseo-labs | 21 | keyword-overview, difficulty, ideas, related, suggestions, ranked-keywords, competitors, search-intent, top-searches, traffic-estimation | | backlinks | 20 | summary, backlinks, referring-domains, anchors, competitors, intersections, bulk-* | | ai-optimization | 13 | LLM-mentions (search, top-domains, top-pages, metrics), ChatGPT scraper, AI keyword volume | | keywords-data | 7 | Google Ads search volume, DataForSEO/Google Trends | | serp | 7 | Google + YouTube organic, video info, locations | | domain-analytics | 4 | technologies, WHOIS | | merchant | 4 | Amazon ASIN/products/sellers/locations | | onpage | 3 | Lighthouse, instant pages, content parsing | | content-analysis | 3 | content search | | business-data-api | 2 | business listings search |

Run d4s list to see every tool, its alias, endpoint, and required params.

How it works

registry.json is committed and used at runtime, so normal CLI users do not need the MCP server installed. extract.mjs is a maintainer script that regenerates that registry from the exact dataforseo-mcp-server dev dependency. It imports each tool class, calls getName() / getDescription() / getParams(), and captures the real /v3/... endpoint via a mock client. It also detects handler-level array-to-numbered-object payload conversions used by intersection endpoints. The CLI is a thin generic executor: validate params → build task → POST/GET → format.

Development

npm install            # installs the pinned extractor dependency
bun run build          # bundle src/*.ts → dist/main.js (single file, zero deps)
npm run extract        # regenerate registry.json from the installed MCP server
./dist/main.js list    # smoke test

Limitations

• A few tools (e.g. merchant_amazon_locations) do client-side filtering inside the MCP server; d4s returns the raw API result and leaves filtering to your jq/TSV pipeline.
• Output schemas follow DataForSEO's live responses, which occasionally change. Curated --tsv columns have fallbacks; use --json if a column resolves empty.
• Not affiliated with DataForSEO. You pay your own API usage.

License

MIT. Endpoint/param definitions derived from DataForSEO's public API and the Apache-2.0 dataforseo-mcp-server.