dataforseo-cli

# Keyword Research with dataforseo-cli LLM-friendly keyword research CLI. Wraps the DataForSEO API and outputs TSV by default — compact, structured, and optimized for agent context windows. **npm:** https://www.npmjs.com/package/dataforseo-cli **GitHub:** https://github.com/alexgusevski/dataforseo-cli ## Setup ### 1. Install from npm ```bash npm install -g dataforseo-cli ``` ### 2. Check credentials ```bash dataforseo-cli status ``` If credentials are already configured, you're good to go. If not, authenticate: ```bash # With login + password dataforseo-cli --set-credentials login=YOUR_LOGIN password=YOUR_PASSWORD # Or with base64 token (from DataForSEO email) dataforseo-cli --set-credentials base64=YOUR_BASE64_TOKEN ``` Credentials are stored in `~/.config/dataforseo-cli/config.json`. The `locations` and `languages` commands work without credentials (local data). ## Commands ### `status` — Check credentials Check if API credentials are configured without making any API calls. ```bash dataforseo-cli status ``` Exits 0 if configured, exits 1 if not. Shows login username (not password). ### `volume` — Keyword metrics Get search volume, CPC, keyword difficulty (0–100), competition level, and 12-month search trend. ```bash dataforseo-cli volume <keywords...> [options] ``` **Arguments:** - `<keywords...>` — One or more keywords (required). Batch multiple keywords in one call to save API requests. **Options:** - `-l, --location <code>` — Location code (default: `2840` = US) - `--language <code>` — Language code (default: `en`) - `--json` — Output as JSON array - `--table` / `--human` — Output as human-readable table **Example:** ```bash dataforseo-cli volume "seo tools" "keyword research" "backlink checker" ``` **Output (TSV):** ``` keyword volume cpc difficulty competition trend seo tools 12500 2.35 45 HIGH 14800,13900,12500,12100,11800,12000,12500,13000,12800,12500,12200,11900 ``` - `difficulty` — 0–100 scale (0-30 easy, 31-60 medium, 61-100 hard) - `cpc` — Cost per click in USD - `competition` — LOW / MEDIUM / HIGH - `trend` — 12 monthly search volumes, newest first ### `related` — Keyword suggestions Find related keyword ideas from a seed keyword. ```bash dataforseo-cli related <seed> [options] ``` **Arguments:** - `<seed>` — Seed keyword (required, single keyword) **Options:** - `-l, --location <code>` — Location code (default: `2840` = US) - `--language <code>` — Language code (default: `en`) - `-n, --limit <n>` — Max results (default: `50`) - `--json` — Output as JSON array - `--table` / `--human` — Output as human-readable table **Example:** ```bash dataforseo-cli related "ai agents" -n 20 ``` **Output (TSV):** ``` keyword volume cpc competition difficulty best ai agents 8100 3.10 0.82 52 ai agent framework 2400 1.85 0.65 38 ``` ### `competitor` — Domain keyword analysis See what keywords a domain currently ranks for. ```bash dataforseo-cli competitor <domain> [options] ``` **Arguments:** - `<domain>` — Target domain (required, e.g. `ahrefs.com`) **Options:** - `-l, --location <code>` — Location code (default: `2840` = US) - `--language <code>` — Language code (default: `en`) - `-n, --limit <n>` — Max results (default: `50`) - `--json` — Output as JSON array - `--table` / `--human` — Output as human-readable table **Example:** ```bash dataforseo-cli competitor semrush.com -n 10 ``` **Output (TSV):** ``` keyword position volume cpc difficulty url backlink checker 1 33100 4.50 72 https://ahrefs.com/backlink-checker ``` ### `locations` — Look up location codes List all available location codes, or filter by name. Works offline — no API credentials needed. ```bash dataforseo-cli locations [search] [--json] ``` **Arguments:** - `[search]` — Optional filter by name (e.g. `sweden`, `new york`) **Without search** — lists all locations: ```bash dataforseo-cli locations ``` **With search** — filters by name: ```bash dataforseo-cli locations sweden ``` **Output (TSV):** ``` code name country type 2752 Sweden SE Country ``` ### `languages` — Look up language codes List all available language codes, or filter by name. Works offline — no API credentials needed. ```bash dataforseo-cli languages [search] [--json] ``` **Without search** — lists all languages: ```bash dataforseo-cli languages ``` **With search** — filters by name: ```bash dataforseo-cli languages swedish ``` **Output (TSV):** ``` name code Swedish sv ``` ## Output Formats All data commands default to TSV (tab-separated values) — the most token-efficient structured format for LLMs. | Flag | Description | |------|-------------| | *(default)* | TSV — fewest tokens, best for agent pipelines | | `--json` | JSON array — use when you need structured parsing | | `--table` / `--human` | Human-readable aligned table — for human review | ## Caching Results are cached in `~/.config/dataforseo-cli/cache/` to avoid duplicate API calls and save costs. Same query + location + language = cache hit. ```bash dataforseo-cli --print-cache ``` ## Workflow: SEO Article Research 1. **Start with seed keyword:** `dataforseo-cli volume "your topic"` 2. **Expand:** `dataforseo-cli related "your topic" -n 30` 3. **Filter:** Pick keywords with volume > 100, difficulty < 60 4. **Check competitors:** `dataforseo-cli competitor competitor-domain.com -n 20` 5. **Write article** targeting the best keyword cluster ## Tips - Batch keywords in `volume` — DataForSEO charges per API request, not per keyword - Default location is USA (2840). Always set `--location` for local/international SEO - Use `locations` and `languages` without arguments to see all available options - Difficulty scale: 0-30 easy, 31-60 medium, 61-100 hard