内容
# Decodo CLI
[](https://discord.gg/Ja8dqKgvbZ)
[](https://www.npmjs.com/package/@decodo/cli)
<p align="center">
<a href="https://dashboard.decodo.com/integrations?utm_source=github&utm_medium=social&utm_campaign=cli"> <img src="https://github.com/user-attachments/assets/a1e52a9e-3da1-4081-b3c6-053aafb8f196"/></a>
</p>
从终端或 shell 脚本中抓取网站、搜索引擎、电子商务平台和社交媒体。Decodo CLI 连接您到 [Decodo Web Scraping API](https://decodo.com)，无需从头开始构建代理轮换、解析器或重试逻辑。
- 以 JSON、Markdown、NDJSON 和截图形式输出结构化数据
- 服务器端 JavaScript 渲染和反机器人处理
- 覆盖 195+ 个位置的 1.25 亿+ IP 地址
- 适用于 `jq`、CI 和编码代理的管道友好型
## 什么是 Decodo CLI？
Decodo CLI 是 Decodo Web Scraping API 的命令行界面。它包装了每个 API 目标作为子命令，并为脚本、自动化和代理工作流添加了 shell 原生输出模式。
您无需维护爬取基础设施，只需一个二进制文件即可从终端可靠地访问网络数据。
## 为什么使用 CLI？
在 IDE 或 MCP 客户端之外需要网页抓取时，请使用 CLI：
- **脚本和 CI** — 在管道、cron 作业和 GitHub Actions 中运行抓取任务
- **Shell 管道** — 将结果输送到 `jq`、`grep` 或自定义工具
- **编码代理** — 调用抓取任务作为子进程（Cursor、Claude Code、Codex、Windsurf）
- **快速终端访问** — 一个命令即可抓取、搜索或截图
有关在 IDE 中基于 MCP 的抓取，请参阅 [Decodo MCP 服务器](https://github.com/Decodo/mcp-server)。当您需要直接 shell 访问或脚本时，CLI 是合适的工具。
## 主要功能
**无需基础设施的终端网页抓取。** 抓取任何网站，包括 JavaScript 密集型页面，无需处理代理轮换、CAPTCHA 解答或反机器人系统。
**用于自动化的结构化输出。** Markdown（人类可读）、JSON 和 NDJSON（管道友好）以及 PNG 截图 — 适用于脚本、数据管道和代理子调用。
**热门目标的内置支持。** 顶级命令用于抓取、搜索和截图，以及 Google 和 Bing、Amazon、Walmart、Target、Reddit、TikTok、YouTube 等模式驱动的子命令。运行 `decodo targets` 以列出所有可用目标。
**全局代理基础设施。** 1.25 亿+ 住宅 IP 地址，195+ 地理位置，99.99% 的成功率，甚至针对最受保护的目标 — 所有这些都通过 Decodo API 实现。
**管道友好设计。** 紧凑的 JSON 数据通过管道传输，人类可读的输出在 TTY 中显示，明确的退出代码用于身份验证、验证、速率限制和 API 错误。
**快速实现价值。** 从 API 令牌到首次抓取仅需几分钟 — 通过一条命令安装或使用 `npx` 零设置。
## 用例
在需要从 shell 进行网页抓取、结构化数据提取自动化、动态网站的可靠访问或从头开始构建抓取基础设施的替代方案时，请使用 Decodo CLI。常见场景：
- **Shell 脚本和 CI** — 在管道中抓取或搜索，无需嵌入 SDK 逻辑
- **数据管道** — 将 NDJSON 结果流式传输到 `jq`、数据库或下游工具
- **编码代理子进程** — 让代理直接调用 `decodo search` 或 `decodo scrape`
- **电子商务情报** — 从终端查询 Amazon、Walmart 和 Target 目标
- **社交媒体数据收集** — 从 Reddit、TikTok 和 YouTube 收集帖子和元数据
- **快速研究** — 搜索网页或捕获截图，无需离开终端
## 快速入门
1. **创建免费帐户** 在 [dashboard.decodo.com](https://dashboard.decodo.com) — 最多 2000 次免费请求，无需信用卡。
2. **获取 API 密钥。** 从 [playground](https://dashboard.decodo.com/playground) 获取 Web Scraping API 基本身份验证令牌。
3. **安装 Node.js 18+** 从 [nodejs.org](https://nodejs.org) （npm/npx 安装所需）。
4. **安装 CLI** （选择以下方法之一）。
5. **配置身份验证** 并运行您的第一个抓取任务：
```bash
decodo setup
decodo scrape https://ip.decodo.com
decodo search "decodo scraping api"
```
## 安装
> **需要 [Node.js](https://nodejs.org/) 18+**
### macOS / Linux（推荐）
```bash
curl -fsSL https://decodo.github.io/cli/install.sh | sh
```
### Windows（PowerShell）
```powershell
irm https://decodo.github.io/cli/install.ps1 | iex
```
### npm（任何平台）
```bash
npm install -g @decodo/cli
```
### 运行无需安装
```bash
npx @decodo/cli --version
npx @decodo/cli scrape https://ip.decodo.com --token "$DECODO_AUTH_TOKEN"
```
## 身份验证
从 [Decodo playground](https://dashboard.decodo.com/playground) 获取基本身份验证令牌。
```bash
# 交互式 — 保存令牌到配置文件
decodo setup
# 环境变量 — 无需保存配置文件
export DECODO_AUTH_TOKEN='your-token'
# 每命令覆盖
decodo whoami --token 'your-token'
```
**优先级：** `--token` 标志 → `DECODO_AUTH_TOKEN` 环境变量 → 保存的配置文件（`decodo setup`）。
```bash
decodo whoami # 显示令牌来源（标志 / 环境变量 / 配置文件）
decodo reset # 清除保存的配置文件
```
## 测试您的设置
安装并身份验证后，尝试：
```bash
decodo scrape https://ip.decodo.com
decodo google-search "top articles hacker news" --page-count 5 --parse
```
您应该在几秒钟内看到 Markdown 或解析后的 JSON 数据。如果您看到身份验证错误，请重新检查您的令牌是否来自仪表盘。
## 命令
### 一级命令
| 命令 | 描述 |
| --- | --- |
| `decodo scrape <url>` | 抓取 URL（默认 Markdown） |
| `decodo search <query>` | 网络搜索（ `--engine google\|bing` ， `--geo` ， `--limit` ） |
| `decodo screenshot <url>` | 捕获 PNG 截图（ `-o` 文件或目录） |
| `decodo targets` | 按组列出所有抓取目标 |
| `decodo setup` | 交互式保存身份验证令牌 |
| `decodo whoami` | 显示配置的身份验证来源 |
| `decodo reset` | 删除保存的身份验证配置 |
### 模式驱动的目标命令
每个 API 目标也作为其自己的子命令（来自 `decodo targets` 的 kebab-case 名称）：
```bash
decodo google-search "decodo scraping api"
decodo universal https://ip.decodo.com
decodo universal --help
```
使用 `decodo <target> --help` 获取目标特定的标志（ `--parse` 、 `--geo` 等）。
## 输出模式
默认情况下，抓取命令打印第一个结果的 `content` （解析后的 JSON 数据，如果目标支持 `--parse` ，则为 Markdown）。
| 标志 | 效果 |
| --- | --- |
| `--full` | 打印完整的 API 响应信封 |
| `--format ndjson` | 在 stdout 上每个结果一行 JSON 对象（管道友好） |
| `--pretty` | 在 stdout 上格式化 JSON 数据 |
| `-o, --output <path>` | 写入文件而不是 stdout |
| `-v, --verbose` | 将调试日志打印到 stderr |
**TTY 与管道：** 当 stdout 是终端时，使用人类可读的输出。 当数据通过管道传输或重定向时，写入原始字节或紧凑的 JSON 数据。 截图输出必须通过 `-o` 或重定向 — 将二进制 PNG 数据写入 TTY 是不允许的。
**NDJSON 行约定：** 使用 `--format ndjson` ，stdout 是每个 API 结果行一个 JSON 对象。 如果没有 `--full` ，每一行是结果的 `content` 。 如果有 `--full` ，每一行是完整的结果条目（例如 `content` 、 `status_code` 、 `url` ）。 没有每行一个 `.results[]` 的信封级别 — 单独将每行通过 `jq` 传输。
```bash
# 来自 Google 搜索的解析 JSON 数据
decodo google-search "query" --parse
# 完整信封，格式化输出
decodo google-search "query" --full --pretty
# jq / 代理的 NDJSON 流
decodo google-search "query" --format ndjson --full | jq -c '.url'
```
## 示例
### 管道友好工作流
```bash
# 搜索并提取标题
decodo google-search "rust web scraping" --page-count 3 --parse | jq '.results.results.organic[].title'
# 抓取 JSON API 端点
decodo scrape https://ip.decodo.com/json | jq '.proxy.ip'
# 截图到文件，然后打开
decodo screenshot https://example.com -o shot.png
```
### 抓取地理限制内容
```bash
# 来自特定国家的请求
decodo scrape https://example.com --country us
decodo search "shoes" --geo de
decodo google-search "shoes" --geo de --parse
```
使用 `decodo <target> --help` 获取 API 模式中的所有地理、本地化和目标特定选项。
## 代理工具
编码代理（Cursor、Claude Code、Codex、Gemini CLI、Windsurf）应将 CLI 调用为 **shell 子进程** ，而非嵌入抓取逻辑。
**推荐模式：
```bash
# 零安装（适用于 CI 和临时代理）
npx --yes @decodo/cli search "topic" --token "$DECODO_AUTH_TOKEN"
# 全局安装（重复调用更快）
decodo search "topic"
decodo scrape https://example.com --full --format ndjson
```
**代理指南：
1. 需要 `DECODO_AUTH_TOKEN` 或运行 `decodo setup` 才能进行抓取。
2. 编程方式解析多个结果时，优先使用 `--format ndjson --full` 。
3. 使用 `decodo targets` 发现可用的目标命令。
4. 使用 `decodo <target> --help` 获取模式准确的标志。
5. 检查退出代码（如下）以区分身份验证、用法和 API 错误。
## 环境变量
| 变量 | 描述 |
| --- | --- |
| `DECODO_AUTH_TOKEN` | 基本身份验证令牌（覆盖保存的配置文件，在 `--token` 之前） |
| `DECODO_CONFIG_HOME` | 覆盖配置文件目录（默认： `$XDG_CONFIG_HOME/decodo` ，否则 `~/.config/decodo` ） |
## 退出代码
| 代码 | 含义 |
| --- | --- |
| `0` | 成功 |
| `1` | 一般错误 |
| `2` | 用法错误（无效标志，缺少参数） |
| `3` | 身份验证错误（缺少或无效令牌） |
| `4` | 验证错误（无效请求参数） |
| `5` | 速率限制 |
| `6` | 超时 |
| `7` | API / 网络错误 |
## 故障排除
**`No auth token found`**
运行 `decodo setup` 或导出 `DECODO_AUTH_TOKEN` 。
**`command not found: decodo`**
安装脚本会自动配置 PATH 并打印 `source` 步骤 — 重新运行它或打开新终端。您也可以使用 `npx @decodo/cli` 。
**验证 / API 错误**
读取 stderr 上的 `Error:` 消息。使用 `--full` 检查原始 API 响应。
**截图 TTY 错误**
使用 `-o shot.png` 或重定向： `decodo screenshot <url> > shot.png` 。
## 开发
<details>
### 先决条件
- Node.js 18+（推荐 24）
- [pnpm](https://pnpm.io/) 10.x（如果需要，运行 `corepack enable` ）
### 安装和构建
```bash
git clone https://github.com/Decodo/cli
cd cli
pnpm install
pnpm build
```
### 本地运行
```bash
node build/esm/index.js --help
pnpm link --global && decodo --help
```
### 测试和检查
```bash
pnpm lint
pnpm typecheck
pnpm test
```
</details>
## 相关仓库
[Web Scraping API](https://github.com/Decodo/Web-Scraping-API)，
[Decodo MCP 服务器](https://github.com/Decodo/mcp-server)，
[Decodo OpenClaw 技能](https://github.com/Decodo/decodo-openclaw-skill)
## 试用
安装 CLI 并在几分钟内开始从终端抓取。
[免费开始](https://dashboard.decodo.com/) | [文档](https://help.decodo.com/docs/introduction)
| [Discord](https://discord.gg/Ja8dqKgvbZ)
## 许可证
所有代码均在 [MIT License](https://github.com/Decodo/Decodo/blob/master/LICENSE) 下发布。
连接信息
猜你喜欢
暂无推荐服务器