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

# Olostep CLI

> 命令行界面用于抓取、搜索、映射、爬取、回答和批处理 — JSON 输出适用于脚本、CI 和 AI 代理

**NPM 包:** [olostep-cli](https://www.npmjs.com/package/olostep-cli)
**代码库:** [github.com/olostep-api/olostep-cli](https://github.com/olostep-api/olostep-cli)

用于 [Olostep API](https://www.olostep.com/) 的 CLI — 从终端**抓取**、**搜索**、**映射**、**爬取**、**回答**和**批处理**网络。每个命令返回**JSON**，因此可以干净地传递给 `jq`、代理和 CI。

纯 JavaScript，Node 18+，无需下载本地二进制文件。安装不到一秒，启动约需 200 毫秒，作为单个约 100 KB 的包发布。

## 安装

**要求:** Node.js **18+**。

<Tabs>
  <Tab title="npm (推荐)">
    ```bash theme={null}
    npm install -g olostep-cli
    olostep init
    ```
  </Tab>

  <Tab title="单行命令 (macOS / Linux)">
    ```bash theme={null}
    curl -fsSL https://olostep.com/install.sh | sh
    olostep init
    ```

    该脚本检查 Node 18+，运行 `npm install -g olostep-cli`，如有需要则回退到 `sudo`。
  </Tab>

  <Tab title="单行命令 (Windows)">
    ```powershell theme={null}
    iwr -useb https://olostep.com/install.ps1 | iex
    olostep init
    ```

    与 macOS/Linux 脚本相同的思路，但适用于 PowerShell。
  </Tab>

  <Tab title="无需安装 (npx)">
    ```bash theme={null}
    npx -y olostep-cli@latest --help
    ```

    适合在不进行全局安装的情况下尝试单个命令。
  </Tab>
</Tabs>

`olostep init` 是推荐的下一步 — 它会让你登录，将 Olostep 技能安装到你的 AI 代理中，并配置 MCP 服务器，所有这些都在一个命令中完成。单行脚本将 `npm install -g olostep-cli` 包装在 Node 18+ 检查和 `sudo` 回退中，因此即使你不确定本地设置，它们也能正常工作。

**平台:** macOS (Apple Silicon 和 Intel), Linux (x64 和 arm64), Windows (x64 和 arm64)。

## 设置

一个命令完成所有操作 — 登录、安装技能和安装 MCP 服务器：

```bash theme={null}
olostep init
```

标志: `--skills-only`, `--mcp-only`, `--no-browser`, `--relogin`.

仅**登录**（无技能/MCP）：

```bash theme={null}
olostep login
olostep login --no-browser     # 打印 URL（通过 SSH 时很有用）
```

浏览器会打开到 Olostep 认证页面；你点击**授权**，CLI 会将你的密钥保存在本地。

**替代方法 — 设置环境变量。** 适用于 CI：

```bash theme={null}
export OLOSTEP_API_KEY=your_key_here
```

从 [API 密钥仪表板](https://www.olostep.com/dashboard/api-keys) 获取密钥。

**密钥存储位置**（在 `olostep login` 之后）：

| 操作系统    | 路径                                                           |
| ------- | ------------------------------------------------------------ |
| macOS   | `~/Library/Application Support/olostep-cli/credentials.json` |
| Linux   | `~/.config/olostep-cli/credentials.json`                     |
| Windows | `%USERPROFILE%\AppData\Roaming\olostep-cli\credentials.json` |

## 登出

```bash theme={null}
olostep logout            # 提示确认，然后删除 credentials.json
olostep logout --dry-run  # 仅预览 — 查看会发生什么
olostep logout --yes      # 跳过确认（用于脚本）
olostep logout --json     # 机器可读输出
```

`logout` 还会警告你，如果 `OLOSTEP_API_KEY` / `OLOSTEP_API_TOKEN` 环境变量或当前目录中的 `.env` 文件仍然保存有密钥 — 这些优先于凭据文件，因此仅删除文件可能不够。输出包括 PowerShell 和 bash/zsh 的确切 unset 命令。

## 快速开始

```bash theme={null}
olostep login

olostep search "best web scraping APIs 2025" --limit 5
olostep answer "What does Olostep do?"
olostep map "https://example.com" --top-n 20
olostep scrape "https://example.com" --formats markdown
olostep crawl "https://docs.example.com" --max-pages 50
olostep batch-scrape urls.csv --formats markdown,html
```

每个命令默认将其 JSON 结果打印到 stdout。传递 `--out <path>` 保存到文件。

## 它能做什么？

| 你想要…            | 命令                               | Olostep 产品                                  |
| --------------- | -------------------------------- | ------------------------------------------- |
| 搜索网络            | `search`                         | [搜索](/features/search)                      |
| 获取研究答案          | `answer`                         | [回答](/features/answers)                     |
| 发现网站上的 URL      | `map`                            | [映射](/features/maps)                        |
| 抓取一个页面          | `scrape`                         | [抓取](/features/scrapes)                     |
| 抓取网站上的每个页面      | `crawl`                          | [爬取](/features/crawls)                      |
| 从 CSV 中抓取多个 URL | `batch-scrape`                   | [批处理](/features/batches)                    |
| 提取结构化字段         | `--parser-id` 在 `batch-scrape` 上 | [解析器](/features/structured-content/parsers) |
| 按 ID 重新获取结果     | `scrape-get`                     | [抓取](/features/scrapes)                     |
| 标记/组织批处理        | `batch-update`                   | [批处理](/features/batches)                    |

## 输出

每个命令默认**将其 JSON 结果打印到 stdout**。

| 标志             | 行为                               |
| -------------- | -------------------------------- |
| *(无)*          | 打印 JSON 到 **stdout** (UTF-8, 缩进) |
| `--out <path>` | 将 JSON 写入该文件                     |
| `--out -`      | 明确 stdout (与默认相同)                |

进度和日志行发送到 **stderr**，因此 stdout 保持干净以供管道使用。

```bash theme={null}
olostep map "https://example.com" --top-n 20 | jq '.urls[:10]'
olostep scrape "https://example.com" | jq .result.markdown_content
olostep search "topic" --json | jq '.links[].url'
```

**如何选择：**

* **`search`** — 你想要查询的相关 URL 和片段列表。CLI 为你搜索网络。
* **`answer`** — 你想要合成的答案，而不是原始页面内容。CLI 为你进行研究。
* **`scrape`** — 你已经有了 URL 并想要获取干净的内容。
* **`crawl`** — 你想要网站上的每个页面（或过滤后的子集），而无需手动枚举 URL。
* **`batch-scrape`** — 你有一个 URL 列表，并希望它们并行处理。

## 命令

使用 `olostep <command> --help` 查看每个选项。

### `search`: 实时网络搜索

返回去重的自然链接（URL、标题、描述）。

| 选项                  | 描述               |
| ------------------- | ---------------- |
| `--limit`           | 结果数量，默认 12，最大 25 |
| `--include-domains` | 逗号分隔的域名以限制结果     |
| `--exclude-domains` | 逗号分隔的域名以排除       |
| `--out`             | 文件或 `-`          |
| `--json`            | 机器可读输出           |

```bash theme={null}
olostep search "TypeScript CLI tools" --limit 10
olostep search "open source projects" --include-domains "github.com" --limit 5
olostep search "AI agents" --json | jq '.links[].url'
```

### `answer`: 研究答案

同步 — 当答案准备好时返回。

| 选项              | 描述                 |
| --------------- | ------------------ |
| `--out`         | 文件或 `-`            |
| `--json-format` | 可选的 JSON 形状用于结构化输出 |

```bash theme={null}
olostep answer "What does this company build?" --out answer.json
olostep answer "Extract facts" --json-format '{"company":"","year":""}' --out -
```

### `map`: 发现 URL

| 选项                                               | 描述           |
| ------------------------------------------------ | ------------ |
| `--out`                                          | 文件路径或 `-`    |
| `--top-n`                                        | 返回的最大 URL 数量 |
| `--search-query`                                 | 可选查询以指导发现    |
| `--include-subdomain` / `--no-include-subdomain` | 子域           |
| `--include-url` / `--exclude-url`                | 可重复的 URL 模式  |
| `--cursor`                                       | 分页游标         |

```bash theme={null}
olostep map "https://example.com" --top-n 100 --search-query "blog"
```

### `scrape`: 一个 URL

**格式:** `html`, `markdown`, `text`, `json`, `raw_pdf`, `screenshot` (逗号分隔; 默认 `markdown`)。

| 选项                                  | 描述                                                                            |
| ----------------------------------- | ----------------------------------------------------------------------------- |
| `--formats`                         | 逗号分隔                                                                          |
| `--country`                         | 国家代码 (例如 `US`, `GB`)                                                          |
| `--wait-before-scraping`            | 抓取前等待 (ms)                                                                    |
| `--payload-json` / `--payload-file` | 高级选项为 JSON (例如 `"max_age": 86400` 以选择缓存 — 参见 [缓存](/features/scrapes#caching)) |

```bash theme={null}
olostep scrape "https://example.com" --formats markdown,html
olostep scrape "https://example.com" --payload-file options.json --out -
```

### `scrape-get`: 按 ID 获取

```bash theme={null}
olostep scrape-get "scrape_abc123" --out -
```

### `crawl`: 整个网站

启动爬取，轮询直到完成，然后检索页面内容。

**检索格式:** `markdown`, `html`, `json`.

显著标志: `--max-pages`, `--max-depth`, `--include-subdomain`, `--include-external`, `--include-url`, `--exclude-url`, `--search-query`, `--top-n`, `--webhook`, `--crawl-timeout`, `--formats`, `--pages-limit`, `--pages-search-query`, `--poll-seconds`, `--poll-timeout`, `--dry-run`.

```bash theme={null}
olostep crawl "https://docs.example.com" --max-pages 50 --formats markdown,html
olostep crawl "https://example.com" --max-pages 10 --dry-run
```

### `batch-scrape`: CSV

CSV 必须有一个带有 **`custom_id`**（或 `id`）和 **`url`** 列的标题行。

```csv theme={null}
custom_id,url
example,https://example.com
iana,https://iana.org
docs,https://docs.olostep.com
```

| 选项                                               | 描述                                |
| ------------------------------------------------ | --------------------------------- |
| `--formats`                                      | `markdown`, `html`, `json` (逗号分隔) |
| `--country`                                      | 可选国家代码                            |
| `--parser-id`                                    | 解析器 ID 用于结构化提取                    |
| `--poll-seconds`, `--log-every`, `--items-limit` | 轮询和分页                             |
| `--dry-run`                                      | 打印负载并退出                           |

```bash theme={null}
olostep batch-scrape urls.csv --formats markdown,html
olostep batch-scrape urls.csv --parser-id "<PARSER_ID>" --out results.json
```

同步 — 轮询直到批处理完成，然后检索每个项目。

### `batch-update`: 批处理元数据

需要 **其中之一** `--metadata-json` 或 `--metadata-file` (JSON 对象)。

```bash theme={null}
olostep batch-update "batch_abc123" --metadata-json '{"team":"growth"}'
olostep batch-update "batch_abc123" --metadata-file meta.json
```

## 认证命令

```bash theme={null}
olostep login                      # 浏览器 PKCE 登录
olostep logout                     # 删除保存的凭据
olostep status                     # 显示认证状态、配置路径、版本

olostep auth login                 # 同 olostep login
olostep auth logout                # 同 olostep logout
olostep auth status                # 同 olostep status
olostep auth set-key <key>         # 直接保存 API 密钥（无需浏览器）
```

`auth set-key` 对于 CI 和脚本很有用 — 直接写入密钥而无需通过浏览器流程。

## 安装 MCP 服务器

CLI 将 Olostep MCP 服务器写入你的代理的配置中 — 无需 JSON 编辑。

```bash theme={null}
olostep mcp install                          # 检测代理，托管端点
olostep mcp install --agent cursor           # 仅 Cursor
olostep mcp install --transport stdio        # 本地 npx 而不是托管
olostep mcp install --no-global              # 写入当前项目
olostep mcp install --dry-run --json         # 仅计划
olostep mcp uninstall                        # 移除 olostep 条目
olostep list mcp                             # 显示哪些代理有它
```

| 选项                                 | 描述                                                                                                               |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `--agent`                          | 特定代理，可重复。支持: `cursor`, `claude`, `claude-desktop`, `windsurf`, `vscode`, `kilo`, `opencode`, `continue`, `codex` |
| `--all-agents` / `--no-all-agents` | 目标所有检测到的代理（默认）                                                                                                   |
| `--transport`                      | `http` (托管，推荐) 或 `stdio` (本地 `npx olostep-mcp`)                                                                  |
| `--global` / `--no-global`         | 每用户配置（默认）与项目本地                                                                                                   |
| `--api-key`                        | 嵌入的密钥；默认为解析的凭据                                                                                                   |
| `--dry-run`                        | 显示计划而不写入                                                                                                         |
| `--json`                           | 机器可读输出                                                                                                           |

托管端点位于 `https://mcp.olostep.com/mcp` 使用 `Authorization: Bearer <key>` — 无需本地 Node 进程。CLI 仅将 `olostep` 键合并到现有配置中。安装后重启你的代理。

## AI 代理技能

CLI 提供 **13 个 Olostep 技能** — `SKILL.md` 文件安装到 Claude Code、Cursor 和其他代理中，因此它们知道 Olostep 可以做什么以及何时使用。

```bash theme={null}
olostep add skills                     # 安装到每个检测到的代理中
olostep skills install                 # 同上（别名）
olostep skills update                  # 重新安装/刷新所有技能
olostep skills list                    # 查看安装了什么以及在哪里
olostep skills uninstall               # 移除所有技能
```

过滤安装内容：

```bash theme={null}
olostep add skills --category usage    # 仅核心网络数据技能
olostep add skills --skill scrape --skill map
olostep add skills --agent cursor --agent claude
```

查看 [技能](/features/skills) 获取完整列表和选项。

## 健康检查

```bash theme={null}
olostep doctor                         # 运行所有检查
olostep doctor --skip-network          # 仅认证 + 配置，无 HTTP 调用
olostep doctor --json                  # NDJSON — 每个检查一条记录（适合 CI）
olostep doctor --fail-on-warn          # 在警告时也退出 1
```

检查：API 密钥存在，API 密钥可访问，MCP 端点可访问，每个检测到的代理的配置文件存在。

CI 使用：

```bash theme={null}
olostep doctor --json --skip-network | jq 'select(.status == "fail")'
```

## 版本 & 更新

```bash theme={null}
olostep version                        # CLI 版本，Node 版本，频道
olostep version --json                 # 机器可读: { cli, node, channel }
olostep update                         # 更新到最新 (npm install -g olostep-cli@latest)
olostep update --check                 # 检查是否有新版本可用，不安装
```

## 环境变量

| 变量                          | 影响                             |
| --------------------------- | ------------------------------ |
| `OLOSTEP_API_KEY`           | API 密钥                         |
| `OLOSTEP_API_TOKEN`         | API 密钥（旧别名）                    |
| `OLOSTEP_JSON=1`            | 强制每个命令输出 JSON（与全局 `--json` 相同） |
| `OLOSTEP_NO_UPDATE_CHECK=1` | 静音“更新可用”通知                     |
| `OLOSTEP_CLI_CONFIG_DIR`    | 覆盖凭据目录                         |

## Windows / PowerShell 注意事项

PowerShell 对 `,` 和 `*` 的标记化与 bash 不同 — 引用参数：

```powershell theme={null}
olostep scrape "https://example.com" --formats "markdown,html"
olostep map   "https://example.com" --include-url "/*"
olostep answer "Extract facts" --json-format '{"company":"","year":""}'
```

单引号对于 JSON 值最安全（无 `$` 插值）。

## 查看已安装内容

```bash theme={null}
olostep list skills    # 已安装的 Olostep 技能及哪些代理有它们
olostep list mcp       # 哪些代理有 Olostep MCP 服务器，以及传输方式
```

## 全局标志

| 标志                | 描述 |
| ----------------- | -- |
| `-V`, `--version` | 版本 |
| `-h`, `--help`    | 帮助 |

`--out`, `--timeout`, 和 `--api-key` 在每个数据命令上都可用。

## 安全

保持 API 密钥不在源代码控制中；如果泄露则旋转。`olostep logout` 删除本地凭据文件，并告知你是否有任何环境变量来源仍然保存有密钥。

## 相关

* [映射](/features/maps) · [爬取](/features/crawls) · [批处理](/features/batches) · [回答](/features/answers) · [搜索](/features/search) · [技能](/features/skills) · [MCP 服务器](/integrations/mcp-server)