Scrapeless CLI

概述

Scrapeless CLI 提供统一的 scrapeless 命令，用于网页内容提取、网站爬取、AI 回答、代理 URL 生成以及云浏览器操作。你可以在终端中运行它，也可以在自动化脚本中调用它。

功能

api 命名空间为保留项，尚未实现。

开始使用

• 快速开始 — 安装 CLI、配置密钥并发出第一个请求。
• 使用示例 — 各功能对应的命令。
• 配置与任务 — 凭据、输出、轮询及浏览器要求。

快速开始

环境要求

请使用 Node.js 22 或更高版本以及 npm。Node.js 是 CLI 的运行时；你无需编写 JavaScript 或 TypeScript。使用需要身份验证的服务时，必须拥有 Scrapeless 账户和 API 密钥。

1. 安装 CLI

npm install -g scrapeless
scrapeless --version
scrapeless --help

2. 配置 API 密钥

从 Scrapeless 控制台复制你的 API 密钥，并替换 YOUR_API_TOKEN：

1. 在控制台中打开 Settings（设置）。
2. 选择 API Key Management（API 密钥管理）。
3. 使用一个可用的密钥；如有需要，也可以选择 Create API Key（创建 API 密钥）。复制该密钥，用于下方的配置命令。

scrapeless config set api_token YOUR_API_TOKEN
scrapeless auth status

auth status 用于检查身份验证状态和账户余额。云端请求和代理流量会消耗账户额度。

3. 提取页面

scrapeless unlock https://example.com --type markdown

该命令会输出从页面中提取的 Markdown。

查看完整响应

添加 --json 可查看完整响应，包括响应代码和页面内容：

scrapeless unlock https://example.com --type markdown --json

使用示例

运行以下示例前，请先安装 CLI 并配置 API 密钥。

Web Unlocker

以 HTML 格式提取选定区域，或保存完整的 JSON 响应：

scrapeless unlock https://example.com --type html --selector body
scrapeless unlock https://example.com --type markdown --json -o page.json

scrape 是 unlock 的别名。默认输出为 HTML，并启用 JavaScript 渲染。

Crawl

scrapeless crawl https://example.com --limit 3 --max-depth 2 --formats markdown --json -o crawl.json

--formats markdown 用于选择页面内容的格式；整个任务结果仍为 JSON。可使用 --include-paths 和 --exclude-paths 限定爬取范围。

AI Scraper

scrapeless ai platforms
scrapeless ai chatgpt "Explain what Scrapeless is used for" -o answer.md
scrapeless ai perplexity "What web scraping techniques are available?" --web-search true --json -o answer.json

任务成功时默认返回 Markdown。可用选项因平台而异；使用 ai platforms 查看当前支持的平台列表。示例中的英文提示词仅作演示：CLI 接受 Unicode 文本，可用语言取决于所选服务。

Proxies

scrapeless proxy gateways
scrapeless proxy create --type residential --country US --gateway us

URL 在本地生成，不会测试连通性。支持的类型为 residential、ipv6 和 datacenter；网关可取 us、eu、ap 或 hostname:port。该 URL 包含凭据，请妥善保管，切勿泄露。

云浏览器

将 SESSION_ID 替换为 new-session 返回的会话 ID：

scrapeless browser new-session --name demo --ttl 300 --json
scrapeless browser --session-id SESSION_ID open https://example.com
scrapeless browser --session-id SESSION_ID snapshot -i
scrapeless browser --session-id SESSION_ID screenshot page.png
scrapeless browser --session-id SESSION_ID close

对于 click @e1 或 fill @e2 "hello world" 这类命令，请在会话保持打开期间，使用最新快照中的实际交互元素引用。默认情况下，首次使用（包括运行 browser --help）时会安装上游 CLI；详见“配置与任务”中的“浏览器要求”。

如需查看命令选项，请运行 scrapeless unlock --help、scrapeless crawl --help、scrapeless ai --help 或 scrapeless proxy create --help。browser --help 的首次使用安装行为见上文说明。

完整的命令参考和源码构建说明请参阅 CLI 仓库。AI 服务的行为与计费说明请参阅 AI Scraper 文档。

配置与任务

凭据

默认配置文件为 ~/.scrapeless/config.json。密钥的优先级为 配置文件 → SCRAPELESS_API_TOKEN → SCRAPELESS_API_KEY。如需使用环境变量：

export SCRAPELESS_API_KEY="YOUR_API_TOKEN"

已保存的密钥优先。CLI 不会自动加载 .env。上述为 POSIX 语法；在 PowerShell 中请使用 $env:SCRAPELESS_API_KEY="YOUR_API_TOKEN"。

自定义配置路径不会改变 Browser 的默认配置文件。封装层会通过环境变量传递其解析出的密钥，但 Browser 默认保存的密钥可能会覆盖它。请使用共享的默认配置文件，以保持身份验证一致。

输出与请求体

HTTP 命令支持使用 --json 获取完整响应，使用 -o, --output <file> 保存输出。默认情况下，结果输出到 stdout；使用 -o 时则改为保存到文件。进度信息、轮询期间的任务 ID 提示以及错误信息输出到 stderr。使用 --no-wait 时，创建响应（包括其中的任务 ID）将作为结果输出的一部分。

Unlocker、Crawl 和 AI 的创建命令接受 --data '<JSON>' 或 --data @request.json。优先级为 显式参数 → 请求体字段 → CLI 默认值；嵌套对象会合并，数组则会被替换。

任务处理

默认情况下，Crawl 和 AI 创建任务后每 5 秒轮询一次，最长 300 秒。添加 --no-wait 可在创建后立即返回。使用返回的 ID 查询已有任务：

scrapeless crawl result TASK_ID --wait --timeout 300 --interval 5
scrapeless ai result TASK_ID --platform chatgpt --wait --timeout 300 --interval 5

请使用对应服务的 ID。轮询超时不会取消服务端任务。对于 Crawl 请检查 completed，对于 AI 请检查 success，并查看实际内容；仅凭退出码 0 不足以判断成功。

--timeout 和 --interval 以秒为单位；抓取选项 --wait-for 和 --scrape-timeout 以毫秒为单位。每个 HTTP 请求各有独立的 60 秒超时。创建任务的 POST 请求不会自动重试。

浏览器要求

封装层需要 npm、能够访问 npm 和 GitHub Releases，并具备缓存写入权限。会话在云端运行；封装层在本地运行，无需单独安装 Chromium。

固定版本支持 macOS x64/arm64、Linux x64/arm64 和 Windows x64；未附带 Windows arm64 二进制文件。

故障排查