# CLI

> 通过 OAuth 2.1 授权，然后在终端中搜索网页、读取页面、查看热门趋势。

Canonical URL: https://s1.dev/zh/docs/integrations/cli

`s1` 把整个 API 搬进你的终端——而且由于它可以按需输出 JSON，也能直接用在 shell 脚本里。

## 安装

```bash
curl -fsSL https://cli.search1api.com/install.sh | bash
```

这会安装一个独立的二进制文件，无需 Node.js。如果你更习惯使用 npm：

```bash
npm install -g search1api-cli
```

## 登录

```bash
s1 login
```

这是 OAuth 2.1 登录，而不是交出 API 密钥。CLI 会：

1. 发现 Search1API 的授权服务器。
2. 将自身动态注册为公共原生客户端。
3. 使用 Authorization Code + PKCE（`S256`）打开授权页面。
4. 将获得的访问令牌和刷新令牌保存在本地配置中。
5. 在访问令牌过期时自动刷新。

账户所有者仍需在浏览器中登录并批准连接。之后运行 `s1 config show`，确认当前使用的认证方式是 OAuth 2.1。

如果 CLI 无法自动打开浏览器，可以改为输出授权 URL：

```bash
s1 login --no-browser
```

重定向仍需能够访问运行 `s1` 的机器上的回环（loopback）回调地址。

## 使用 API 密钥作为备选

对于脚本、CI 以及不便进行交互式 OAuth 登录的环境，现有的 API 密钥仍然可用：

```bash
s1 config set-key YOUR_API_KEY
# 或
export SEARCH1API_KEY=YOUR_API_KEY
```

`SEARCH1API_KEY` 的优先级高于已保存的 OAuth 凭据。如果希望 CLI 使用 `s1 login` 创建的 OAuth 令牌，请移除该变量。完整的 OAuth 与 API 密钥模型参见[认证](https://s1.dev/zh/docs/essentials/authentication)。

## 命令

| 命令 | 作用 |
| --- | --- |
| `s1 search "<query>"` | 搜索网页 |
| `s1 news "<query>"` | 搜索新闻 |
| `s1 ask "<request>"` | 描述你的需求，由 Search1API 选择引擎（5 积分） |
| `s1 crawl <url>` | 读取页面 |
| `s1 sitemap <url>` | 列出网站的链接 |
| `s1 trending <github\|hackernews>` | 热门话题 |
| `s1 balance` | 剩余积分 |
| `s1 login` | 在浏览器中通过 OAuth 2.1 授权 |
| `s1 config set-key \| show` | 管理配置 |
| `s1 update` | 原地更新 `s1` |

## 示例

```bash
# 来自 Google 的 5 条结果
s1 search "rust async" -n 5 -s google

# 搜索后抓取前 3 条结果的全文
s1 search "web framework" -c 3

# 来自 Hacker News 的今日新闻
s1 news "tech layoffs" -s hackernews -t day

# Bing 结果的第二页
s1 search "kubernetes" -s bing -p 2

# 让 Search1API 选择引擎和时间范围
s1 ask "What are developers saying about Bun 1.3 this month?"

# 机器可读输出，直接交给 jq
s1 search "test" --json | jq '.results[0].title'
```

`--json` 参数让 `s1` 可以用于脚本：用管道传给 `jq`、交给模型处理，或写入文件。

## 常用参数

| 参数 | 含义 |
| --- | --- |
| `-n, --max-results` | 1–50，默认 10 |
| `-s, --service` | 选择引擎；默认 `google` |
| `-p, --page <N>` | 结果页码；支持 `bing`、`bingcn`、`baidu` 和 `grokipedia` |
| `-c, --crawl <N>` | 抓取前 N 条结果的全文 |
| `--include` / `--exclude` | 限定或排除站点 |
| `-t, --time <day\|week\|month\|year>` | 时间范围 |
| `--json` | 输出原始 JSON，而非格式化结果 |

> **info:** `-c/--crawl` 与 API 的 `crawl_results` 是同一个深度搜索功能，计费方式也相同：搜索 1 积分，外加每个成功抓取的页面 1 积分。参见[积分与限制](https://s1.dev/zh/docs/essentials/credits-and-limits)。

已停用的 `s1 reasoning` 和 `s1 models` 命令已在 CLI 1.2.3 中移除。

源码：[github.com/superagents-lab/search1api-cli](https://github.com/superagents-lab/search1api-cli)