> ## Documentation Index
> Fetch the complete documentation index at: https://help.decodo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Decodo CLI：面向 Decodo Web Data API 的开源命令行工具。可在终端中抓取 URL、运行 SERP 搜索并获取结构化数据。

Decodo CLI（`@decodo/cli`）是面向 Decodo API 的开源命令行工具。您可以直接在终端中抓取网站、搜索引擎、电商平台和社交媒体，无需编写 HTTP 客户端代码、构建自定义解析器或管理代理。

* 支持 JSON、NDJSON、Markdown 和 PNG 屏幕截图等结构化输出
* 服务端 JavaScript 渲染、反爬虫绕过和验证码处理
* 覆盖 195 多个地区的 1.15 亿多个住宅 IP
* 对管道友好，适用于 `jq`、CI/CD 和编程智能体

> [!NOTE]
>
> 最新的安装说明、示例和源代码请查看 [CLI GitHub 仓库](https://github.com/Decodo/cli)。

## 什么是 Decodo CLI？

Decodo CLI 将每个 [**Web Data API**](https://help.decodo.com/docs/cn/web-data-api-introduction.md) 目标封装为一个子命令，并增加了面向脚本、自动化和 AI 智能体工作流的 shell 原生输出模式。它基于 Node.js 和 TypeScript 构建，采用 MIT 许可证。

它提供统一的命令行接口来获取网络数据，您无需自行维护抓取基础设施。

## 为什么使用 CLI？

当您需要在 IDE 或 MCP 客户端之外进行网页抓取时，可以使用 CLI：

* **脚本和 CI/CD**：在 shell 脚本、cron 定时任务、GitHub Actions 和流水线中运行抓取。
* **Shell 管道**：将 JSON 或 NDJSON 输出通过管道传给 `jq`、`grep`、数据库或自定义工具。
* **编程智能体**：从 Cursor、Claude Code、Codex、Gemini CLI 或 Windsurf 中以子进程方式调用抓取功能。
* **终端快速访问**：用一条命令即可抓取网站、搜索网络或截取屏幕截图。

## 核心功能

* **在终端中进行网页抓取**。抓取网站（包括大量使用 JavaScript 的页面），而无需自行管理代理轮换、JavaScript 渲染、反爬虫处理或验证码破解。
* **面向自动化的结构化输出**。Markdown（便于人工阅读）、JSON 和 NDJSON（对管道友好）以及 PNG 屏幕截图，专为脚本、数据管道和 AI 智能体子进程设计。
* **内置常用目标支持**。为 scrape、search、map、crawl 和 screenshot 提供一级命令，并为 Google 搜索和 Bing、Amazon、Walmart、Target、TikTok、YouTube 等提供由 schema 驱动的子命令。运行 `decodo targets` 可列出所有可用目标。
* **全球代理基础设施**。覆盖 195 多个地区的 1.15 亿多个住宅 IP，支持 IP 轮换和地理定位，并由 Web Data API 99.99% 的成功率提供保障。
* **天生适合管道**。在管道中输出紧凑 JSON，在 TTY 中输出便于阅读的内容，并为身份验证、参数校验、速率限制和 API 错误提供明确的退出码。
* **快速上手**。一条命令即可安装，或使用 `npx` 而无需全局安装 CLI。

## 使用场景

* **Shell 脚本和 CI/CD**：在流水线中抓取或搜索，无需嵌入 SDK 逻辑。
* **数据管道**：将 NDJSON 结果以流的方式送入 `jq`、数据库或下游工具。
* **编程智能体子进程**：让 AI 智能体直接调用 `decodo search` 或 `decodo scrape`。
* **电商情报**：在终端中查询 Amazon、Walmart 和 Target。
* **社交媒体数据采集**：从 TikTok 和 YouTube 收集帖子和元数据。
* **SERP 监控**：以地理定位和解析后的输出搜索 Google 和 Bing。

## 快速开始

1. 在 [**dashboard.decodo.com**](https://dashboard.decodo.com/) **创建免费账户**——最多 10K 次免费请求，无需信用卡。
2. 在 [**Decodo 控制面板**](https://dashboard.decodo.com/web-data/playground)中，从您的 Web Data API 订阅**获取 Web Data API 密钥**。较旧的计划只有基本身份验证令牌，它同样可用。
3. 从 [**nodejs.org**](https://nodejs.org/) **安装 Node.js 22 及以上版本**（使用 npm 或 `npx` 所必需）。
4. 使用下文任一方式**安装 CLI**。
5. **完成身份验证并运行**您的第一次抓取：

```bash theme={null}
decodo setup
decodo scrape https://ip.decodo.com
decodo search "decodo web data api"
```

## 安装

> [!NOTE]
>
> 需要 [**Node.js**](https://nodejs.org/) 22 或更高版本。在更低版本上，安装脚本会以 `Node.js v<version> found, but v22+ is required.` 终止。

### macOS / Linux（推荐）

```bash theme={null}
curl -fsSL https://decodo.github.io/cli/install.sh | sh
```

### Windows（PowerShell）

```powershell theme={null}
irm https://decodo.github.io/cli/install.ps1 | iex
```

### npm（任意平台）

```bash theme={null}
npm install -g @decodo/cli
```

### 不安装直接运行

```bash theme={null}
npx @decodo/cli --version
npx @decodo/cli scrape https://ip.decodo.com --token "$DECODO_AUTH_TOKEN"
```

## 身份验证

请使用 [**Decodo 控制面板**](https://dashboard.decodo.com/web-data/playground)中订阅所对应的 Web Data API 密钥。较旧的计划只有基本身份验证令牌，其用法完全相同——CLI 会自动识别您提供的是哪一种，因此下文的每条命令两者皆可使用。

```bash theme={null}
# Interactive - saves the credential to config
decodo setup

# Non-interactive - useful in CI
decodo setup --token 'your-api-key'

# Environment variable - no saved config required
export DECODO_AUTH_TOKEN='your-api-key'

# Per-command override
decodo whoami --token 'your-api-key'
```

**优先级：** `--token` 参数 → `DECODO_AUTH_TOKEN` 环境变量 → 已保存的配置（`decodo setup`）。

```bash theme={null}
decodo whoami # Show the active auth source and masked credential
decodo reset  # Clear saved config
```

> [!WARNING]
>
> `search`、`map` 和 `crawl` 会调用 Web Data API，**需要 API 密钥**。使用基本身份验证令牌会被拒绝，并返回退出码 `3`：
>
> `This command needs a Web Data API key; a basic auth token cannot call it.`
>
> `scrape`、`screenshot` 和各目标命令则两种凭据皆可使用。

## 测试您的配置

完成安装和身份验证后，可以尝试：

```bash theme={null}
decodo scrape https://ip.decodo.com
decodo google-search "top articles hacker news" --page-count 5 --parse
```

您应当会看到 Markdown 或解析后的 JSON 输出。如果出现身份验证错误，请在控制面板中再次核对您的 API 密钥。

## 命令

### 一级命令

| 命令 | 说明 |
| - | - |
| `decodo scrape <url>` | 抓取 URL，默认输出 Markdown（`--country`、`--headers`、`--target`） |
| `decodo search <query>` | 网页搜索，返回解析后的 JSON 结果（`--geo`、`--locale`、`--page`） |
| `decodo map <url>` | 列出站点的 URL，每行一个（`--limit`、`--sitemap`、`--select-paths`） |
| `decodo crawl <url>` | 启动爬取并打印其 id；`--wait` 会以 NDJSON 形式打印页面 |
| `decodo screenshot <url>` | 截取 PNG 屏幕截图（`-o` 指定文件或目录） |
| `decodo targets` | 按分组列出所有抓取目标 |
| `decodo setup` | 保存您的 API 密钥或身份验证令牌（`--token` 用于非交互式） |
| `decodo whoami` | 显示当前使用的凭据来源和脱敏后的凭据 |
| `decodo reset` | 删除已保存的 CLI 配置 |

全局参数：`-V, --version`、`-v, --verbose` 和 `--token <token>`。

### search、map 和 crawl

这三个命令会调用 Web Data API，需要 API 密钥（详见上文的"身份验证"一节）。

```bash theme={null}
decodo search "rust web scraping" --geo DE | jq '.organic[].title'
decodo map https://example.com --limit 100 --select-paths "/blog/*"
decodo crawl https://example.com --limit 50 --wait --progress -o pages.ndjson
```

`decodo crawl <url>` 会立即返回并给出爬取 id。可用以下命令管理正在运行的爬取任务：

```bash theme={null}
decodo crawl status <id>
decodo crawl results <id> -o pages.ndjson
decodo crawl results <id> --wait -o pages.ndjson
decodo crawl cancel <id>
```

`crawl results --wait` 让智能体可以先启动爬取、继续处理其他工作，稍后再收集页面。使用 `--wait` 时，CLI 每隔 `--poll-interval` 秒（默认 `5`）轮询一次，并在 `--timeout` 秒（默认 `3600`，退出码 `6`）后放弃——而爬取任务会一直运行，直到您取消它。爬取 id 会在任务启动时立即输出到 stderr。状态为 `truncated` 或 `cancelled` 的爬取会打印警告；状态为 `faulted` 的爬取仍会打印其页面，然后以 `7` 退出。

| 命令 | 主要参数 |
| - | - |
| `decodo search <query>` | `--geo`、`--locale`、`--page`、`--pretty`、`-o` |
| `decodo map <url>` | `--limit`、`--sitemap <include\|only\|skip>`、`--domain-filter <domain\|subdomain\|all>`、`--select-paths`、`--exclude-paths`、`--js-rendering`、`--geo`、`--locale`、`--full`、`--pretty`、`-o` |
| `decodo crawl <url>` | `--max-depth`、`--max-duration`、`--content-format <markdown\|html>`、`map` 的全部站点参数，以及 `--wait`、`--progress`、`--poll-interval`、`--timeout`、`-o` |
| `decodo crawl status <id>` | `--pretty` |
| `decodo crawl results <id>` | `--no-content`、`--wait`、`--progress`、`--poll-interval`、`--timeout`、`-o` |
| `decodo crawl cancel <id>` | `--pretty` |

> [!NOTE]
>
> **从 1.x 升级：** `decodo search` 以前运行的是 `google_search` 抓取目标，并接受 `--engine` 和 `--limit`。现在它调用 Web Data API，且只接受 `--geo`、`--locale` 和 `--page`——传入 `--engine` 或 `--limit` 会被视为用法错误（退出码 `2`）。若需要此前的行为，请使用 `decodo google-search` 或 `decodo bing-search`。

### 由 schema 驱动的目标命令

每个 API 目标也都以自己的子命令形式提供，命令名为 `decodo targets` 所显示的短横线命名：

```bash theme={null}
decodo google-search "decodo web data api"
decodo universal https://ip.decodo.com
decodo universal --help
```

使用 `decodo <target> --help` 可查看特定目标的参数（`--parse`、`--geo` 以及 schema 中的其他参数）。

## 输出模式

默认情况下，抓取类命令会打印第一条结果的 `content`（当目标支持 `--parse` 时为解析后的 JSON，`decodo scrape` 则为 Markdown）。

| 参数 | 效果 |
| - | - |
| `--full` | 打印完整的 API 响应外层结构 |
| `--format ndjson` | 在 stdout 上每行输出一个 JSON 对象（对管道友好） |
| `--pretty` | 在 stdout 上输出带缩进的 JSON |
| `-o, --output <path>` | 写入文件而不是 stdout |
| `-v, --verbose` | 将调试日志打印到 stderr |

* **TTY 与管道的区别**：当 stdout 是终端时，CLI 会尽可能使用便于阅读的输出。当输出被重定向或通过管道传递时，它会写出原始字节或紧凑 JSON。屏幕截图必须通过 `-o` 写入文件或进行重定向，因为二进制 PNG 内容不会直接写入 TTY。
* **NDJSON 输出**：使用 `--format ndjson` 时，stdout 中每行对应一条 API 结果。不加 `--full` 时，每行包含该结果的 `content`；加上 `--full` 时，每行包含完整的结果条目（`content`、`status_code`、`url`）。单行中不存在外层的 `.results[]`——请逐行通过 `jq` 处理。

```bash theme={null}
# Parsed JSON from Google Search
decodo google-search "query" --parse

# Full envelope, pretty-printed
decodo google-search "query" --full --pretty

# NDJSON stream for jq / agents
decodo google-search "query" --format ndjson --full | jq -c '.url'
```

## 示例

### 适合管道的工作流

```bash theme={null}
# Search and extract titles
decodo google-search "rust web scraping" --page-count 3 --parse | jq '.results.results.organic[].title'

# Scrape a JSON API endpoint - --no-markdown keeps the response valid JSON
decodo universal https://ip.decodo.com/json --no-markdown | jq '.proxy.ip'

# Screenshot to file, then open
decodo screenshot https://example.com -o shot.png
```

> [!NOTE]
>
> `decodo scrape` 返回的是 Markdown，而 Markdown 转换器会转义下划线——因此 `zip_code` 会变成 `zip\_code`。这在 JSON 中是无效的转义，把它传给 `jq` 会失败并报 `parse error: Invalid escape`。当目标是 JSON 接口时，请改用 `decodo universal <url> --no-markdown`。

### 抓取有地区限制的内容

```bash theme={null}
# Request from a specific country
decodo scrape https://example.com --country US
decodo search "shoes" --geo DE
decodo google-search "shoes" --geo DE --parse
```

使用 `decodo <target> --help` 可查看 API schema 中全部的 geo、locale 和特定目标参数。

## 智能体工具

Decodo CLI 也可用于 AI 智能体和智能体工作流。Cursor、Claude Code、Codex、Gemini CLI 和 Windsurf 等编程智能体可以把 CLI 作为 shell 子进程调用，而无需嵌入抓取逻辑。

**推荐用法：**

```bash theme={null}
# No install – for CI runners and short-lived agent sandboxes
npx --yes @decodo/cli search "topic" --token "$DECODO_AUTH_TOKEN"

# Global install (faster repeat calls)
decodo search "topic"
decodo scrape https://example.com --full --format ndjson
```

**面向智能体的建议：**

1. 在抓取之前，要求设置 `DECODO_AUTH_TOKEN` 或运行 `decodo setup`。如果智能体需要使用 `search`、`map` 或 `crawl`，请使用 API 密钥。
2. 以编程方式解析多条结果时，优先使用 `--format ndjson --full`。
3. 使用 `decodo targets` 发现可用的目标命令。
4. 使用 `decodo <target> --help` 获取与 schema 一致的参数。
5. 检查退出码，以区分身份验证错误、用法错误和 API 错误。

### MCP 与 CLI：如何选择

当您的智能体需要在 shell、终端、CI/CD 流水线或子进程中抓取时，请使用 CLI。若需在 IDE 中通过模型上下文协议进行智能体抓取，请参阅 [**MCP 服务器**](https://help.decodo.com/docs/cn/mcp.md)。

## 环境变量

<table>
  <colgroup>
    <col width="170" />

    <col width="349" />
  </colgroup>

  <thead>
    <tr>
      <th>变量</th>
      <th>说明</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`DECODO_AUTH_TOKEN`</td>
      <td>API 密钥或基本身份验证令牌。优先级高于已保存的配置，但会被 `--token` 覆盖。</td>
    </tr>

    <tr>
      <td>`DECODO_CONFIG_HOME`</td>
      <td>覆盖配置目录。默认为 `$XDG_CONFIG_HOME/decodo`；若未设置 `$XDG_CONFIG_HOME`，则为 `~/.config/decodo`。</td>
    </tr>
  </tbody>
</table>

## 退出码

| 退出码 | 含义 |
| - | - |
| `0` | 成功 |
| `1` | 一般错误 |
| `2` | 用法错误（参数无效、缺少必填参数） |
| `3` | 身份验证错误——凭据缺失或无效，或在 `search`、`map`、`crawl` 上使用了基本身份验证令牌 |
| `4` | 校验错误（请求参数无效） |
| `5` | 速率限制 |
| `6` | 超时 |
| `7` | API 或网络错误 |

## 故障排查

* `No API key or auth token found.` 请运行 `decodo setup` 或导出 `DECODO_AUTH_TOKEN`。
* `This command needs a Web Data API key; a basic auth token cannot call it.` 您在 `search`、`map` 或 `crawl` 上使用了基本身份验证令牌。请从 [**Web Data API 演练场**](https://dashboard.decodo.com/web-data/playground)获取 API 密钥，然后重新运行 `decodo setup`。
* `command not found: decodo`。[安装脚本](https://decodo.github.io/cli/install.sh)会自动配置您的 `PATH`。如果 `decodo` 仍然不可用，请重启终端或重新运行安装脚本。您也可以使用 `npx @decodo/cli`。
* **校验或 API 错误**。请阅读 stderr 上的 `Error:` 消息。使用 `--full` 可查看原始 API 响应。
* **屏幕截图 TTY 错误**。请使用 `-o shot.png` 或进行重定向：`decodo screenshot <url> > shot.png`。

***

## 相关内容

* [**MCP 服务器**](https://help.decodo.com/docs/cn/mcp.md)：在兼容 MCP 的 AI 工具和 IDE 中使用 Decodo。
* [**TypeScript SDK**](https://help.decodo.com/docs/cn/typescript-sdk.md)：将 Decodo API 集成到 TypeScript 和 JavaScript 项目中。
* [**Python SDK**](https://help.decodo.com/docs/cn/python-sdk.md)：将 Decodo API 集成到 Python 项目中。
* [**Agent Skills**](https://help.decodo.com/docs/cn/agent-skills.md)：教会受支持的编程智能体何时以及如何使用 Decodo。
* [**pobear**](https://help.decodo.com/docs/cn/pobear.md)：开源的 Go 二进制文件，默认直接抓取，仅在请求被拦截时才升级到 Web Data API。
* [**GitHub 仓库**](https://github.com/Decodo/cli)：查看 CLI 的源代码、示例和最新版本。

***

> [card] [支持](https://direct.lc.chat/12092754)
>
> 需要帮助或只是想打个招呼？我们的支持团队全天候为您服务。 \
> 您也可以随时通过电子邮件 [support@decodo.com](mailto:support@decodo.com) 联系我们。

> [card] [反馈](mailto:feedback@decodo.com)
>
> 找不到您要找的内容？请求一篇文章！ \
> 有反馈意见？分享您对我们如何改进的想法。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.