> For the complete documentation index, see [llms.txt](https://docs.termina.technology/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.termina.technology/documentation/developer-docs-zh/ji-shu-she-zhi-zhi-nan/cli-ke-hu-duan.md).

# CLI 客户端

`sim` 是一个命令行客户端，无需编写代码即可管理模拟会话。该工具支持重放历史 slot、注入修改后的程序以及分析交易结果。

### 安装

提供适用于 Linux 和 macOS（Apple Silicon）的预编译二进制文件：

```bash
curl -fsSL https://cli.simulator.termina.technology/install.sh | bash
```

所有连接到模拟器的命令都需要 API 密钥。可通过 `--api-key` 参数或 `SIMULATOR_API_KEY` 环境变量传入：

```bash
export SIMULATOR_API_KEY=<API_KEY>
```

### 工作流程

1. **检查可用 slot：** `sim ranges` 查找近期可用于测试的 slot 范围。
2. **运行基线：** `sim run` + `--program-id` 记录当前行为。
3. **构建修改后的程序：** `cargo build-sbf`（或等效命令）。
4. **使用覆盖运行：** `sim run` + `--program-so` 指向新的二进制文件。
5. **比较运行结果：** `sim compare baseline.json experiment.json` 查看回归、改进和余额变化。
6. **重新路由历史订单流：** `sim run` + `--reroute-order-flow` 查看历史 swap 如果通过 Jupiter Metis 重新路由会有怎样的表现。

### 命令

#### `sim ranges`：列出可用的 slot 范围

查询哪些 slot 范围可用于回测。

```
sim ranges [OPTIONS]
```

```bash
# List all available ranges
sim ranges

# Filter to a specific date window
sim ranges --after 2026-01-01 --before 2026-03-01
```

#### `sim run`：运行模拟

启动模拟会话、重放交易，并将结果流式写入输出文件。

```
sim run [OPTIONS] --start-slot <SLOT> --end-slot <SLOT>
```

先运行基线，再使用修改后的程序二进制文件重新运行，以比较结果：

```bash
# Baseline
sim run \
  --start-slot 400000000 \
  --end-slot 400001000 \
  --program-id <PROGRAM_ID> \
  --output-file baseline.json

# Experiment
# If the new program requires higher CUs, bump it up to prevent transaction failures 
sim run \
  --start-slot 400000000 \
  --end-slot 400001000 \
  --program-id <PROGRAM_ID> \
  --program-so ./target/deploy/program.so \
  --output-file experiment.json \
  --extra-compute-units 200
```

对于较大的 slot 范围，可通过 `--parallel` 将工作拆分到多个并发会话：

```bash
sim run \
  --start-slot 400000000 \
  --end-slot 400010000 \
  --parallel
```

如需跟踪每笔交易前后的账户状态，请使用 `--subscriptions`：

{% code title="" %}

```bash
sim run \
  --start-slot 400000000 \
  --end-slot 400010000 \
  --program-id <PROGRAM_ID> \
  --subscriptions account-diff
```

{% endcode %}

如需测试报价逻辑的更改会赢得还是失去来自 Jupiter Metis 的成交，请使用 `--reroute-order-flow`：

```bash
sim run \
  --start-slot 400000000 \
  --end-slot 400010000 \
  --reroute-order-flow
```

#### `sim compare`：比较两次模拟运行的差异

将基线运行与实验运行进行比较，并突出显示差异。

```
sim compare <BASELINE> <EXPERIMENT> [SECTION]
```

```bash
sim compare baseline.json experiment.json

# Only show what broke:
sim compare baseline.json experiment.json regressions

# Check P&L impact:
sim compare baseline.json experiment.json balances
```

#### `sim summarize`：汇总模拟输出

显示模拟输出文件的元数据和汇总统计。可选择跟踪特定账户在所有交易中的余额变化。

```
sim summarize <FILE> [--accounts <ADDRS>]
```

```bash
sim summarize baseline.json

# Trace specific wallets:
sim summarize baseline.json --accounts <WALLET1>,<WALLET2>
```

#### `sim update`：更新 CLI

下载最新发布版本，并替换当前的 `sim` 二进制文件。

```bash
sim update
```

### 输出格式

`sim run` 会写入一个 JSON 文件，结构如下：

```json
{
  "metadata": {
    "start_slot": 400000000,
    "end_slot": 400001000,
    "program_id": "<PROGRAM_ID>",
    "session_ids": ["..."],
    "timestamp": "2025-01-15T12:00:00Z"
  },
  "transactions": [
    {
      "slot": 400000042,
      "signature": "<BASE58_SIG>",
      "success": true,
      "error": null,
      "logs": ["Program log: ...", "..."],
      "sol_changes": { "<PUBKEY>": -5000000 },
      "token_changes": { "<PUBKEY>": { "<MINT>": -1000 } },
      "account_diffs": { "<PUBKEY>": { "before": "...", "after": "..." } }
    }
  ],
  "summary": {
    "total": 847,
    "successes": 831,
    "failures": 16
  }
}
```

此文件是 `sim compare` 和 `sim summarize` 的输入。