dataforseo-cli

适用于 AI 代理的 LLM 友好关键字研究 CLI。通过 DataForSEO API 检查搜索量、CPC、关键字难度和竞争情况。查找相关关键词，分析竞争对手排名。默认情况下输出 TSV（针对代理上下文窗口进行了优化）。在进行 SEO 研究、内容规划或竞争性关键词分析时使用。

# 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

---

## 中文说明

# 使用 dataforseo-cli 进行关键词研究

LLM 友好的关键词研究 CLI。它封装了 DataForSEO API，默认输出 TSV——紧凑、结构化，并针对代理上下文窗口进行了优化。

**npm:** https://www.npmjs.com/package/dataforseo-cli
**GitHub:** https://github.com/alexgusevski/dataforseo-cli

## 安装设置

### 1. 从 npm 安装

```bash
npm install -g dataforseo-cli
```

### 2. 检查凭据

```bash
dataforseo-cli status
```

如果凭据已配置，你就可以开始使用了。如果尚未配置，请进行认证：

```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
```

凭据存储在 `~/.config/dataforseo-cli/config.json` 中。`locations` 和 `languages` 命令无需凭据即可工作（使用本地数据）。

## 命令

### `status` — 检查凭据

在不发起任何 API 调用的情况下，检查 API 凭据是否已配置。

```bash
dataforseo-cli status
```

已配置时退出码为 0，未配置时退出码为 1。显示登录用户名（不显示密码）。

### `volume` — 关键词指标

获取搜索量、CPC、关键词难度（0–100）、竞争级别以及 12 个月的搜索趋势。

```bash
dataforseo-cli volume <keywords...> [options]
```

**参数：**
- `<keywords...>` — 一个或多个关键词（必填）。在一次调用中批量传入多个关键词可节省 API 请求次数。

**选项：**
- `-l, --location <code>` — 地区代码（默认：`2840` = 美国）
- `--language <code>` — 语言代码（默认：`en`）
- `--json` — 以 JSON 数组形式输出
- `--table` / `--human` — 以人类可读的表格形式输出

**示例：**
```bash
dataforseo-cli volume "seo tools" "keyword research" "backlink checker"
```

**输出（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 区间（0-30 容易，31-60 中等，61-100 困难）
- `cpc` — 每次点击成本（美元）
- `competition` — LOW / MEDIUM / HIGH
- `trend` — 12 个月度搜索量，最新的在前

### `related` — 关键词建议

从一个种子关键词出发，查找相关关键词创意。

```bash
dataforseo-cli related <seed> [options]
```

**参数：**
- `<seed>` — 种子关键词（必填，单个关键词）

**选项：**
- `-l, --location <code>` — 地区代码（默认：`2840` = 美国）
- `--language <code>` — 语言代码（默认：`en`）
- `-n, --limit <n>` — 最大结果数（默认：`50`）
- `--json` — 以 JSON 数组形式输出
- `--table` / `--human` — 以人类可读的表格形式输出

**示例：**
```bash
dataforseo-cli related "ai agents" -n 20
```

**输出（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` — 域名关键词分析

查看某个域名当前在哪些关键词上有排名。

```bash
dataforseo-cli competitor <domain> [options]
```

**参数：**
- `<domain>` — 目标域名（必填，例如 `ahrefs.com`）

**选项：**
- `-l, --