---
title: "CLI"
description: "shunt 命令行 —— run、check、init、add、token 和 provider login。"
image: "https://shunt-docs.pages.dev/og.png"
---

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

# CLI

## `shunt run`

启动网关。`run` 是默认子命令,因此裸的 `shunt` 也可以。

```bash
shunt run
shunt run --config /path/to/shunt.toml
```

启动时它会用绑定地址(默认 `127.0.0.1:3001`)记录 `shunt listening`。用 `RUST_LOG` 设置日志详细程度,例如 `RUST_LOG=shunt=debug shunt run`。

不带 `--config` 时,shunt 依次搜索 `./shunt.toml` → `~/.config/shunt/shunt.toml` → `$HOMEBREW_PREFIX/etc/shunt.toml`;带 `--config` 时,文件缺失即报错。见 [配置](/zh-cn/guides/configuration/)。

## `shunt check`

校验解析后的配置并退出(`shunt --check` 也可以):

```bash
shunt check
# -> config ok
```

报告具体错误:错误的 bind 地址、路由中的未知提供方、缺失的 `api_key_env`、错误的 `base_url`、错误的适配器/认证组合。

## `shunt init`

在现有目录中创建 starter `shunt.toml`。该命令只写入这一个文件，不会安装任何内容或访问网络。

```bash
shunt init
shunt init --upstream codex --upstream kimi
shunt init --root /path/to/project
shunt init --force
```

不指定 upstream 时，starter 完全由注释组成，加载后使用 shunt 的默认 passthrough 配置。重复使用 `--upstream` 可按 failover 顺序添加 preset 条目；可用名称为 `anthropic`、`codex`、`openai`、`xai`、`grok`、`kimi` 和 `cursor`。Starter 不设置 `server.default_provider`，因此未映射流量仍使用默认 Anthropic passthrough。指定 preset 时，会在末尾自动追加一个 `anthropic` passthrough upstream（除非你自己指定了 `anthropic`），使生成的文件既能通过 `shunt check`，又能保留该 fallback。

Root 默认为当前目录，并且必须已经存在。如果其中已有 `shunt.toml`、`shunt.yaml` 或 `shunt.yml`，则不带 `--force` 时会停止且不写入任何内容。强制 init 只覆盖 `shunt.toml`；YAML variant 保持不变，config discovery 会优先使用新的 TOML 文件。

## `shunt add`

获取面向编码 agent 的内置 Markdown blueprint。Blueprint 是实现指南，而不是安装程序：该命令不会修改文件、安装任何内容或访问网络。

```bash
shunt add                                      # 列出两种 blueprint kind
shunt add upstream                             # 列出具名 upstream 指南
shunt add upstream kimi --print                # 打印一份指南
shunt add upstream https://example.com/docs    # 调研兼容 endpoint
shunt add provider https://example.com/docs    # 调研源码集成
```

Kind 分为 `upstream`（配置已提供的 preset 或兼容 endpoint）和 `provider`（贡献新的 provider protocol 支持）。已知的 upstream slug 或 alias 会获取对应的具名指南。绝对 `http://` 或 `https://` URL 会注入该 kind 的通用 research 指南；相对路径会被拒绝。

Blueprint Markdown 始终输出到 stdout，以便直接输送给 agent。`--print` 明确表达这一意图并抑制交互式 stderr hint，但不会改变 stdout 内容。

```bash
shunt add upstream kimi --print | claude
```

## `shunt token`

将一个 Claude 订阅 OAuth token 打印到 **stdout**(日志走 stderr),设计用来接入 Claude Code 的 `apiKeyHelper`。两种模式:

- **静态** —— 如果设置了 `SHUNT_GATEWAY_TOKEN` 或 `CLAUDE_CODE_OAUTH_TOKEN`,原样回显该值。把它指向一个 `claude setup-token` 值,则从不刷新任何东西。
- **自动刷新** —— 否则读取 `~/.claude/.credentials.json`(用 `CLAUDE_CREDENTIALS` 覆盖路径),返回 `claudeAiOauth` 访问 token,并在它距 `expiresAt` 5 分钟以内时,针对 `platform.claude.com/v1/oauth/token`(与 Claude Code 使用的同一授权)刷新它,然后以 `0600` 原子写回新 token,保留其他所有字段。刷新只在实际过期时发生,以尊重该端点的速率限制。

```json
// ~/.claude/settings.json
{
  "apiKeyHelper": "/path/to/shunt token"
}
```

何时需要它,见 [连接 Claude Code](/zh-cn/guides/connect-claude-code/#2-choose-the-anthropic-credential)。

## `shunt login claude`

用以下三种模式之一创建一个由 shunt 管理的 Anthropic 池账户:

```bash
# Full OAuth: shunt 获取并存储一个新的可刷新登录(推荐)。
shunt login claude --name primary --mode oauth

# 导入当前可刷新的 Claude Code 登录。
shunt login claude --name imported --mode import

# 运行 Claude 的一年期、仅推理 setup-token 流程。
shunt login claude --name ci --mode setup-token
```

在 TTY 中省略 `--mode` 时,shunt 会提示选择 `oauth`、`import` 或 `setup-token`,并默认推荐 OAuth。非交互输入继续沿用原有的 `import` 默认值。`--long-lived` 保留为 `--mode setup-token` 的 deprecated alias。

`--mode oauth` 运行 shunt 的 full-scope PKCE 授权流程,并同时存储 access token 与 refresh token。默认情况下,shunt 在 `127.0.0.1` 上绑定一个临时 listener,打开授权 URL,并在浏览器返回 `http://127.0.0.1:<port>/callback` 时完成。如果无法打开浏览器、无法启动 listener,或 5 分钟内没有收到 callback,它会回退到隐藏输入的手动粘贴流程。通过 SSH 或在 headless 环境中可用 `--manual` 立即使用手动流程:

```bash
shunt login claude --name remote --mode oauth --manual
```

`--mode import` 将 `~/.claude/.credentials.json`(或 `CLAUDE_CREDENTIALS`)复制到 `~/.shunt/accounts/claude/<name>.json`。它保留 refresh token,关联 Claude Code 全局配置中的当前账户 UUID,而 shunt 刷新这份私有副本,不会修改 Claude Code 的源文件。

`--mode setup-token` 运行与 `claude setup-token` 相同的一年期、仅推理 PKCE 流程。在浏览器批准后,把显示的授权码粘贴到 shunt 的隐藏输入提示中。shunt 直接交换该代码,存储 opaque token 和签发账户 UUID,并且绝不打印 token。

在 Unix 上,文件以 `0600` 权限原子写入 `0700` 目录。`SHUNT_CLAUDE_ACCOUNTS_DIR` 可覆盖存储目录;复用名称会替换其文件。已有的外部 setup token 仍需要 `token_env` 加显式 `uuid`,因为签发后无法恢复其账户 UUID。

> **每个可刷新登录只能有一个 owner**
>
> OAuth provider 可能在 shunt 刷新 access token 时轮换 refresh token。不要让多个 shunt 进程使用同一个可刷新 credential 文件,也不要把正在使用的存储文件复制到另一台主机后独立运行。一端的首次刷新可能使另一份副本失效。请为每个进程分别预配;如果有意共享静态 credential,请使用不可刷新的 setup token。

通过只带名称的池条目引用结果,或将 provider 的账户列表留空以扫描所有存储文件:

```toml
[[providers.anthropic.accounts]]
name = "primary"
```

## `shunt login xai`

运行 xAI 的 device-code OAuth 流程并保存可刷新的 credential:

```bash
shunt login xai
```

## Anthropic 账户池认证

对于 `auth = "claude_oauth"` 的 Anthropic provider,账户可以使用只带名称的存储条目、`credentials = "~/.claude/.credentials.json"` 或 `token_env = "YOUR_ENV_NAME"`。存储条目可由上面的 Full OAuth、Claude Code 登录导入或 setup-token 流程创建。完整配置和 failover 规则见 [Anthropic 多账户](/zh-cn/guides/anthropic-multi-account/)。

## 环境变量

| 变量 | 效果 |
| :-- | :-- |
| `SHUNT_*`(如 `SHUNT_SERVER__BIND`) | 覆盖任意配置键;`__` 分隔嵌套键 |
| `RUST_LOG` | 日志过滤器,如 `shunt=debug` |
| `SHUNT_CLIENT_TOKENS` | 面向 [`[server.auth]`](/zh-cn/guides/shared-gateway/) 的客户端 token(名称可通过 `tokens_env` 配置) |
| `SHUNT_GATEWAY_TOKEN` / `CLAUDE_CODE_OAUTH_TOKEN` | 面向 `shunt token` 的静态 token |
| `CLAUDE_CREDENTIALS` | 面向 `shunt token` 和可刷新 `shunt login claude` 导入的备用 credential 文件路径 |
| `SHUNT_CLAUDE_ACCOUNTS_DIR` | shunt 管理的 Claude 账户存储的备用目录 |
| 由 `token_env` 指定的按账户变量 | Anthropic `claude_oauth` 池条目的 setup token;原样使用 |
| `OPENAI_API_KEY` | `openai` 提供方的默认密钥环境变量(每个提供方通过 `api_key_env`) |

Source: https://shunt-docs.pages.dev/zh-cn/reference/cli/index.mdx