CLI - Introduction

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

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

最新的安装说明、示例和源代码请查看 CLI GitHub 仓库。

什么是 Decodo CLI？

Decodo CLI 将每个 Web Data API 目标封装为一个子命令，并增加了面向脚本、自动化和 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。

快速开始

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

decodo setup
decodo scrape https://ip.decodo.com
decodo search "decodo web data api"

安装

需要 Node.js 22 或更高版本。在更低版本上，安装脚本会以 Node.js v<version> found, but v22+ is required. 终止。

macOS / Linux（推荐）

curl -fsSL https://decodo.github.io/cli/install.sh | sh

Windows（PowerShell）

irm https://decodo.github.io/cli/install.ps1 | iex

npm（任意平台）

npm install -g @decodo/cli

不安装直接运行

npx @decodo/cli --version
npx @decodo/cli scrape https://ip.decodo.com --token "$DECODO_AUTH_TOKEN"

身份验证

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

# 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）。

decodo whoami # Show the active auth source and masked credential
decodo reset  # Clear saved config

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 和各目标命令则两种凭据皆可使用。

测试您的配置

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

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 密钥（详见上文的”身份验证”一节）。

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。可用以下命令管理正在运行的爬取任务：

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`

从 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 所显示的短横线命名：

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 处理。

# 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'

示例

适合管道的工作流

# 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

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

抓取有地区限制的内容

# 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 子进程调用，而无需嵌入抓取逻辑。 推荐用法：

# 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

面向智能体的建议：

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

MCP 与 CLI：如何选择

当您的智能体需要在 shell、终端、CI/CD 流水线或子进程中抓取时，请使用 CLI。若需在 IDE 中通过模型上下文协议进行智能体抓取，请参阅 MCP 服务器。

环境变量

变量	说明
`DECODO_AUTH_TOKEN`	API 密钥或基本身份验证令牌。优先级高于已保存的配置，但会被 `--token` 覆盖。
`DECODO_CONFIG_HOME`	覆盖配置目录。默认为 `$XDG_CONFIG_HOME/decodo`；若未设置 `$XDG_CONFIG_HOME`，则为 `~/.config/decodo`。

退出码

退出码	含义
`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 演练场获取 API 密钥，然后重新运行 decodo setup。
command not found: decodo。安装脚本会自动配置您的 PATH。如果 decodo 仍然不可用，请重启终端或重新运行安装脚本。您也可以使用 npx @decodo/cli。
校验或 API 错误。请阅读 stderr 上的 Error: 消息。使用 --full 可查看原始 API 响应。
屏幕截图 TTY 错误。请使用 -o shot.png 或进行重定向：decodo screenshot <url> > shot.png。

支持

需要帮助或只是想打个招呼？我们的支持团队全天候为您服务。
您也可以随时通过电子邮件 support@decodo.com 联系我们。

反馈

找不到您要找的内容？请求一篇文章！
有反馈意见？分享您对我们如何改进的想法。

​什么是 Decodo CLI？

​为什么使用 CLI？

​核心功能

​使用场景

​快速开始

​安装

​macOS / Linux（推荐）

​Windows（PowerShell）

​npm（任意平台）

​不安装直接运行

​身份验证

​测试您的配置

​命令

​一级命令

​search、map 和 crawl

​由 schema 驱动的目标命令

​输出模式

​示例

​适合管道的工作流

​抓取有地区限制的内容

​智能体工具

​MCP 与 CLI：如何选择

​环境变量

​退出码

​故障排查

​相关内容

支持

反馈

什么是 Decodo CLI？

为什么使用 CLI？

核心功能

使用场景

快速开始

安装

macOS / Linux（推荐）

Windows（PowerShell）

npm（任意平台）

不安装直接运行

身份验证

测试您的配置

命令

一级命令

search、map 和 crawl

由 schema 驱动的目标命令

输出模式

示例

适合管道的工作流

抓取有地区限制的内容

智能体工具

MCP 与 CLI：如何选择

环境变量

退出码

故障排查

相关内容