> ## 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、全局标志、环境变量和退出代码。

## 命令结构

```bash theme={null}
olostep <group> <command> [arguments] [flags]
```

命令根据它们的作用进行分组，例如 `olostep keys list` 或 `olostep monitors pause <monitor_id>`。主要的 web-data 命令有一个简写形式，可以运行它们的创建命令：

| 简写 | 运行 |
| - | - |
| `olostep scrape <url>` | `olostep scrape create <url>` |
| `olostep search "<query>"` | `olostep search create "<query>"` |
| `olostep map <url>` | `olostep map create <url>` |
| `olostep crawl <url>` | `olostep crawl create <url>` |
| `olostep answer "<task>"` | `olostep answer create "<task>"` |
| `olostep extract <url>` | `olostep extract run <url>` |

`olostep whoami` 与 `olostep account info` 相同。

## 获取帮助

```bash theme={null}
olostep --help                  # 每个命令组
olostep monitors --help         # 组内的命令
olostep monitors create --help  # 单个命令的参数和标志
olostep help export logs        # 根据功能查找命令
```

`olostep help <words>` 列出名称或描述中包含每个单词的命令。帮助在未登录时也可使用。

## 输出

CLI 根据输出的去向选择其输出格式：

| 输出去向 | 输出内容 |
| - | - |
| 终端 | 格式化的 Markdown：标题、表格和颜色。红色仅用于错误。 |
| 管道或文件，或设置了 `NO_COLOR` | 相同的 Markdown 作为纯文本，无颜色。 |
| 任何目的地，使用 `--json` | 精确的 JSON，适用于脚本和代理。 |

错误输出到 stderr，因此管道 stdout 时不会将其混入数据中。

当设置 `FORCE_COLOR=0` 或 `TERM=dumb` 时，颜色也会关闭：

```bash theme={null}
NO_COLOR=1 olostep credits balance
```

### JSON

在任何列出 `--json` 的命令中添加 `--json`：

```bash theme={null}
olostep scrape https://example.com -f markdown --json
```

调用 Olostep 的命令返回一个 JSON 对象：

```json theme={null}
{
  "operation": "<operation>",
  "mode": "executed",
  "data": {},
  "warnings": []
}
```

| 字段 | 描述 |
| - | - |
| `operation` | 运行的操作。 |
| `mode` | 其中之一：`read`、`executed`、`dry_run`、`browser` 或 `unavailable`。 |
| `data` | 结果。其结构取决于命令。 |
| `warnings` | 关于结果的任何注意事项，例如部分数据。为空表示无内容。 |

解析 JSON，而不是人类可读的输出。人类可读的输出可能会在版本之间更改。

### 选择字段

`--fields` 只保留你指定的字段。用逗号分隔字段，并使用点号访问嵌套字段。每个选择的字段都会在你给出的路径下打印：

```bash theme={null}
olostep whoami --json --fields mode,warnings
```

```json theme={null}
{"mode":"read","warnings":[]}
```

要选择嵌套字段，先查看完整的 `--json` 输出，然后将其命名为 `data.<field>`。`--fields` 也可以在没有 `--json` 的情况下使用，并仅在表格中显示这些字段。

### 使用 jq 管道

```bash theme={null}
olostep credits balance --json | jq '.data'
olostep crawl pages <crawl_id> --json | jq '.data'
```

## 传递值

| 标志类型 | 传递方式 | 示例 |
| - | - | - |
| 文本或数字 | 标志后面 | `--country US`, `--max-pages 50` |
| 可重复列表 | 重复标志，或用逗号分隔 | `-f markdown -f html` 或 `-f markdown,html` |
| JSON | 内联 JSON，或 `@` 和文件路径 | `--metadata '{"project":"q3"}'` 或 `--items @urls.json` |
| 布尔值 | 仅标志 | `--include-subdomain` |
| 固定选择 | 帮助中显示的值之一 | `--days 7`, `--format csv` |

位置 URL 和查询也可以作为标志传递，例如 `olostep scrape create --url-to-scrape https://example.com` 或 `olostep search create --query "olostep"`。

## 改变内容的命令

创建、修改或删除内容的命令，或使用积分的命令，会在帮助中说明。它们支持：

| 标志 | 功能 |
| - | - |
| `--dry-run` | 显示 CLI 将进行的调用，并不发送任何内容。 |
| `--preview` | 请求 Olostep 预览更改而不实际进行更改。 |
| `--yes` | 跳过确认。可能删除或覆盖的命令在没有终端确认时需要 `--yes`。没有它会以代码 `4` 退出。 |

```bash theme={null}
olostep monitors delete <monitor_id> --dry-run
olostep monitors delete <monitor_id> --yes
```

使用积分的命令，如 `scrape`、`search`、`map`、`crawl`、`answer`、`extract`、`batch create`、`monitors create`、`monitors run` 和 `agents run`，在其帮助中会说明 `This consumes credits` 或 `consumes credits`。

## 全局标志

这些标志适用于每个命令：

| 标志 | 描述 |
| - | - |
| `-h`, `--help` | 打印命令帮助并退出。 |
| `--server <url>` | 要使用的 Olostep CLI 服务器。默认为 `https://cli.olostep.com/mcp`。 |
| `--token <token>` | 使用此令牌而不是保存的登录信息。参见 [Authentication](https://docs.olostep.com/cli/authentication.md#scripts-ci-and-agents)。 |
| `--refresh-tools` | 从服务器获取当前命令及其输入列表，而不是使用缓存副本。 |

这些标志适用于帮助中显示的每个命令：

| 标志 | 描述 |
| - | - |
| `--json` | 打印 JSON：适用于脚本和代理。 |
| `--fields <a,b>` | 仅这些字段，逗号分隔（嵌套字段用 `a.b`）。 |
| `--dry-run` | 显示将进行的调用，并不发送任何内容。 |
| `--preview` | 预览而不进行更改。 |
| `--yes` | 不先询问（在没有终端时需要）。 |

## 环境变量

| 变量 | 描述 |
| - | - |
| `OLOSTEP_TOKEN` | 使用此令牌而不是保存的登录信息。与 `--token` 相同。 |
| `OLOSTEP_SERVER` | 服务器 URL。与 `--server` 相同。 |
| `OLOSTEP_HOME` | 安装脚本放置 CLI 的位置。默认为 `~/.olostep`。必须是绝对路径。 |
| `NO_COLOR` | 任何值都会关闭颜色。 |
| `XDG_CONFIG_HOME` | CLI 将其登录信息保存在 `$XDG_CONFIG_HOME/olostep`。默认为 `~/.config/olostep`。 |
| `CI` | 关闭更新通知。 |

## 退出代码

| 代码 | 含义 |
| - | - |
| `0` | 完成。 |
| `1` | 命令失败。消息在 stderr 上。 |
| `2` | 命令或参数错误。 |
| `3` | 需要登录。运行 `olostep login` 或设置 `OLOSTEP_TOKEN`。 |
| `4` | 命令需要 `--yes`。 |
| `5` | 无法访问服务器。 |


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