> ## Documentation Index
> Fetch the complete documentation index at: https://niceeval.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# NiceEval CLI：命令、flags 和退出码参考
> NiceEval CLI 参考：exp、debug、show、view、init、list 和 clean 命令，以及结果下钻、experiment、评估用例过滤、并发、预算和 CI 输出。
[NiceEval](https://niceeval.com/) CLI 是发现、运行和查看评估用例的入口。实际执行评估用例时采用 experiment-first 模型：**`exp` 选择可签入的运行配置**，experiment 后的位置参数才按评估用例 ID 前缀过滤。agent、model 和 flags 写在 `experiments/`，不靠临时 CLI 参数。
## 命令
按 experiment id 路径运行。每个配置的 `evals` 决定覆盖哪些评估用例。
显示一个配对的 Sandbox 与 Plugin 生命周期命令计划，不运行评估。
创建空的 `evals/` 目录和最小的 `niceeval.config.ts`。不生成示例评估用例文件。同时写入/刷新 niceeval 指引区块——项目已有 `AGENTS.md` 就写那份，只有 `CLAUDE.md` 就写进 `CLAUDE.md`，都没有则新建 `AGENTS.md`（见[Agent 反馈闭环](/docs/zh/tutorials/agent-feedback-loop)）。
发现并打印所有评估用例，不运行。
删除明确 writer 留下的 Record 临时目录，不删除正式 Run 或 Attempt。
在终端执行报告。不带 locator 或 `--run` 的命令读取当前项目结果；精确 Attempt 定位符或 Run ID 用于审计历史。
构建完整报告站并在浏览器中托管。它与 `show` 共享选择规则，但会枚举全部页面。
## 输出语言
CLI 与运行时文案是英语。这只影响终端/runtime 文案，不改变结果 JSON 里的机器字段，也不翻译 LLM Judge prompt。浏览器 `niceeval view` 自己提供中英切换。
## `npx niceeval exp [path|config] [id-prefix...]`
```bash theme={null}
# 运行 experiments/ 下全部实验
npx niceeval exp
# 按多层目录运行一批 experiment
npx niceeval exp models
# 只运行一个配置
npx niceeval exp models/openai/gpt-5.4
# 运行一个多层目录下全部配置
npx niceeval exp models/openai
# 在这一批里只运行 ID 以 weather 开头的 eval
npx niceeval exp models weather
```
评估用例过滤参数只出现在 experiment 选择之后。只写 `npx niceeval weather` 不会运行。请使用 `npx niceeval exp local weather` 或 `npx niceeval exp compare weather`。
第一个位置参数只解释为 experiment id、目录路径或文件名前缀。尾随位置参数按评估用例 id 前缀继续收窄。
### `npx niceeval exp list [experiment-prefix]`
只发现并列出可运行的 Experiment 配置，不创建 Session、不取锁、不启动 Agent 或 Sandbox：
```bash theme={null}
npx niceeval exp list
npx niceeval exp list compare/codex
npx niceeval exp list --json
```
默认输出每个配置的 `experimentId`、描述、agent、model、attempts、选中的 eval 数和 labels。`--json` 输出单个 `niceeval.experiments` 文档，并在每项附上完整的 `selectedEvalIds`。
### 查看一个配对的完整 Shell 与 lifecycle
```bash theme={null}
npx niceeval debug compare/codex memory/commit0
npx niceeval debug compare/codex memory/commit0 --json
```
两个 selector 都必须唯一。精确 ID 优先，否则可以使用唯一前缀。Eval 只能从 Experiment 自己选中的范围里匹配；零命中或多命中会列出精确候选。
计划包含 Plugin lifecycle、author prepare、Agent ensure/setup/teardown、test、cleanup 与 Provider finalizer。能静态声明的 `shell()` / `command()` 展开为实际命令，普通 callback 标为 `opaque`。
评估在 Group 内时，只选择这个成员不会把同组其它成员加回计划，但输出仍保留一次 Group lifecycle 包裹。人读输出只显示 `COMMAND PLAN`；`--json` 输出单个 `niceeval.debug-plan/v1` 文档。
TTY 中，总览、Experiment、lane、slot 和每个 lifecycle step 都分别使用与 `show` 相同的圆角区域框，不会把整棵树放入一个总框。每条 Shell、每个 Plugin occurrence 和每个没有命令或只能运行期确定的阶段都有自己的框：
```text theme={null}
╭─ sandbox.materialize ─────────────────────────────────────── OPAQUE ─╮
│ position: lane eval-group:group · physical lifecycle template enter │
│ owner: provider:docker │
│ template: docker:image │
│ template owner: experiment:suite/one │
│ configured locator: exact · image="node@sha256:cd849..." │
│ reason: provider materialization is a runtime operation │
╰──────────────────────────────────────────────────────────────────────╯
╭─ sandbox.prepare ──────────────────────────────────────────── EXACT ─╮
│ position: lane eval-group:group · slot group/first #0 │
│ owner: eval:group/first │
│ command: shell "printf fixture-ready" │
╰──────────────────────────────────────────────────────────────────────╯
```
多行 Shell 会在自己的框内显示成带 gutter 的代码区，而不是压成带 `\n` 的单行字符串。缩进、空行、末尾换行和长行续行都会保留；终端控制字符显示为转义文本：
```text theme={null}
╭─ sandbox.prepare ──────────────────────────────────────────────────── EXACT ─╮
│ position: lane eval:group/first · slot group/first #0 │
│ owner: eval:group/first │
│ command: shell · 5 lines │
│ │ set -eu │
│ │ pnpm install │
│ │ │
│ │ pnpm test │
│ │ │
╰──────────────────────────────────────────────────────────────────────────────╯
```
管道、`NO_COLOR` 或过窄终端逐框降级成无框标题与正文，内容和顺序不变。`--json` 不包含框线。
Human 输出在每条 lane 内固定依次显示 Group before-slot、physical enter、slots、physical exit 与 Group after-slot。Physical teardown 和 Provider finalizer 因而位于使用该实例的全部 slot 之后。
Sandbox materialize 节点会显示 template owner、provider、kind 和安全的 configured locator。`Exact` 只代表原样显示作者配置，不代表 image tag、远端内容或最终实例已经冻结。远端 URL 的凭据、query 与 fragment 会脱敏。Docker image 只有保守的 credential-safe reference（可带标准 `sha256` digest）才显示 `Exact`；URL、非 digest userinfo 或其它不安全语法整项显示 `Opaque`，且不输出原字符串。
作者提供的本地 path、`file:` URL、Dockerfile file 或 local dir 整项显示 `Opaque`，原路径不会进入输出。只有未配置 `localSandbox.dir` 时的固定 `author-base-dir` 标签可以显示 `Exact`。env value、credential、stdin、build arg value 和 custom identity 不输出。
E2B template name 与 Vercel snapshot ID 是 Provider 管理的任意字符串，因此完整 locator 同样显示 `Opaque`。Human 命令计划在统一终端出口把 C0、C1、ESC、tab 与 carriage return 显示成转义文本，覆盖 template metadata 与 Shell 行。JSON 保留结构化值，并依靠 JSON string escaping。
`debug` 不执行运行期 setup、test、teardown、ensure、materialize 或 finalizer，也不创建 Invocation、Run、Record、锁、Sandbox 或 build。它会加载 `.env` 和受信任定义，并执行 Experiment 的选择 predicate。Provider planner 也可能读取文件、调用只读 CLI，或查询 Docker control plane 和远端 API。
计划把 Experiment 配置的全部 Attempt 列作候选 dispatch。正常运行仍可能因 carry、首过即停或预算而不执行某个 slot。`debug` 只接受可选的 `--json`；其它运行 flag 会按用法错误退出。
## 常用 flags
下表由 CLI 的 flag 解析表生成，表外的 flag 一律按未知 flag 报错并以非零状态退出。**没有**用于选择 Sandbox provider 的 CLI flag，也没有项目级默认 provider。请在 Eval 或 Experiment 上声明 template-bearing `SandboxLayer`，并从 `niceeval/sandbox` 导入下列工厂之一：
* `dockerSandbox({ source: { type: "image", image } })`
* `dockerComposeSandbox({ file, workspaceService })`
* `dockerSandbox({ source: { type: "dockerfile", context } })`
* `vercelSandbox({ snapshotId })`
* `e2bSandbox({ template })`
* `localSandbox()`
| Flag | 类型 | 说明 |
| ---------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--agent` | string | experiment 运行不支持该 flag。要换 agent,请在 `experiments/` 下新增或复制一个配置文件。 |
| `--model` | string | experiment 运行不支持该 flag。要换模型,请新增或复制一个 experiment 文件并修改 `model`。 |
| `--attempts` | number | 每个 eval 运行多少次,常用于 pass\@N。 |
| `--max-concurrency` | number | 设置同时运行的 eval 数量。 |
| `--max-build-concurrency` | number | 设置同时进行的 Sandbox 镜像 lookup/build 数量；与 eval 并发独立，默认 2。 |
| `--timeout` | number | 单个 attempt 的超时时间,单位毫秒。解析链:`--timeout` > experiment > eval(`defineEval({ timeoutMs })`)> `niceeval.config.ts`,默认无上限(四层都没声明就不设 deadline);config 是缺省底而不是覆盖层,写了 config 不会让 eval 自己声明的上限失效。 |
| `--budget` | number | 整次运行的预算上限(美元)。 |
| `--keep-sandbox` | boolean | `exp` 命令专用:跑完留下 failed/errored attempt 的 Sandbox 现场(= `--keep-sandbox=failed`);`--keep-sandbox=all` 连 passed 也留。事后用 `niceeval sandbox list/enter/stop` 查看与销毁。 |
| `--all` | boolean | `sandbox stop` 专用:销毁全部留存 Sandbox。 |
| `--window` | string | `sandbox diff` 专用:只看某个 send 窗口(如 `--window turn2` 或 `--window session2/turn1`);省略输出全部窗口的串联视图。 |
| `--path` | string | `sandbox diff` 专用:只看某个文件的 patch;省略输出该窗口的全部文件。 |
| `--leave-running` | boolean | `sandbox enter` 专用:shell 退出后让现场保持运行,不送回休眠。 |
| `--orphans` | boolean | `sandbox list` 专用:核对强杀(`SIGKILL` / 断电)路径留下的无主沙箱实例(docker + e2b;vercel 无按元数据检索实例的通道,不参与)。只读,不清理;销毁走 `niceeval sandbox prune`。 |
| `--tag` | string | 只运行带有该 tag 的 eval(见 `defineEval` 的 `tags`)。 |
| `--junit` | string | 额外写一份 JUnit XML 报告到指定路径,供 CI 消费。 |
| `--json` | boolean | `exp` 运行在 stdout 输出单一有序的 NDJSON 事件流；`exp --dry` 与 `debug` 输出各自的单个 JSON 计划文档。`show` 输出 Host 拥有的内建或自定义单目标机器文档，不形成完整站点或打开第二条取数路径。 |
| `--smoke` | boolean | `docker profile doctor` 专用：启动受限 DinD 容器并运行内层容器。 |
| `--out` | string | `view` 命令专用:把结果查看器静态导出到指定目录。 |
| `--port` | number | `view` 命令专用:指定本地服务器监听端口。 |
| `--host` | string | `view` 命令专用:指定监听地址；省略时为 127.0.0.1，只写 `--host` 时为 0.0.0.0。非 loopback 监听无认证或 TLS，会向所有可达客户端暴露报告数据。 |
| `--experiment` | string\[] | `show` / `view` 命令专用：按完整 ExperimentId 收窄当前项目结果；可重复，不接受前缀或逗号列表。 |
| `--record` | string | `show` / `view` / `accept` / `sandbox enter\|list\|stop` 共用:指定实际 Record root;CLI 不补接 `.niceeval/record` 或其它后缀。 |
| `--run` | string\[] | `show` / `view` 可重复传入 `--run`;每次按完整 RunId 增加一个显式 Run,重复 identity 去重。 |
| `--report` | string | `show` / `view` 命令专用：内建 `overview` 或受信任的 Report module 路径。 |
| `--page` | string | `show` / `view` 命令专用:选择报告的初始页;`show` 渲染该页并在尾部附其余页索引,`view` 以它作初始路由。未命中的页 id 按用法错误退出并列出可用页 id。 |
| `--teardown` | boolean | `exp` 命令专用:补齐被强杀打断的实验级 teardown——只对选中的实验各执行一次 teardown(新进程语义),不派发 attempt、不跑 setup;没有遗留登记也照常执行。与 eval 前缀位置参数组合是用法错误。 |
| `--dry` | boolean | 只打印本次会匹配到的 eval × 运行配置,不实际执行(人读文本或 `--json` 单文档,见「机器怎么读:--json」)。 |
| `--force` | boolean | `sandbox prune` 专用:除 orphan 外也销毁 unverified 实例;`exp` 明确拒绝此 flag,重跑失败项或全部项请用 `--rerun` / `--rerun all`。 |
| `--rerun` | boolean | `exp` 命令专用:重新运行失败项(裸写/failed)或全部项(all),不改变长期指纹。 |
| `--early-exit` / `--no-early-exit` | boolean | 某个 eval 的一次 attempt 通过后,停止该 eval 剩余的 attempts;省略默认关(`attempts` 默认跑满、测完整通过率)。 |
| `--open` / `--no-open` | boolean | `view` 命令专用:启动后自动打开浏览器(默认行为)。 |
| `--yes` | boolean | `clean` / `migrate` 专用：确认不可逆 maintenance 动作或没有 Git restore point 的 migration。 |
| `--help` | boolean | 打印用法说明并退出。 |
| `--version` | boolean | 打印 niceeval 的版本号并退出。 |
## `list`
```bash theme={null}
npx niceeval list
```
用于检查评估用例发现、ID 和配置加载是否正常。
## `exp`
```bash theme={null}
npx niceeval exp compare-models
npx niceeval exp compare-models weather-tool
```
运行命名 experiment，用矩阵比较 agents、models 或 flags。第二个参数开始是评估用例 ID 前缀过滤。
`show` 与 `view` 是顶层命令，应写成 `npx niceeval show`、`npx niceeval view`。误写成 `npx niceeval exp show` / `exp view` 且没有同名 experiment 时，CLI 会在“不存在的实验”错误后提示正确命令。仓库确实存在同名 experiment 时仍按合法 id 执行。
## 两种输出：人读文本与 `--json`
`exp` 的输出只有两种形态，只改变展示，不改变选择、调度、判定、Record 提交或退出码：
```bash theme={null}
# 不加 flag = 人读文本：TTY 里是动态 dashboard，管道/CI 日志里自动降级为只追加的纯文本流
npx niceeval exp compare
# --json = 机器面：stdout 上单一有序的 NDJSON 事件流，coding agent、CI adapter、脚本共用
npx niceeval exp compare --json
# CI 门禁:退出码 + JUnit；需要 JSON 汇总时运行后用 show --json 重定向
npx niceeval exp compare --junit ./artifacts/niceeval-junit.xml
```
两种形态怎么选见[运行器 · Reporter](/docs/zh/explanation/runner#reporter)。AI 反馈闭环的完整用法见 [AI 反馈闭环](/docs/zh/tutorials/agent-feedback-loop)。CI 集成（GitHub Actions、退出码、JUnit）见 [CI 集成](/docs/zh/tutorials/ci-integration)。进程结束后没有 `watch` 或 session 查询；长期数据从停稳 Record 生成报告。
## `view`
```bash theme={null}
npx niceeval view
npx niceeval view --run 01H...
npx niceeval view @01H...
npx niceeval view --host 192.168.0.199
```
打开本地结果查看器。它和 `show` 共用默认 Report 与选择规则。不带 locator 或 `--run` 的命令读取所有身份仍匹配当前项目的结果；精确 `@` 显示该 Attempt 的默认概览；`--run` 读取指定历史 Run。NiceEval 随后形成固定 Sample、枚举全部 Page 与参数实例，并构建完整站点。
没有显式 `--report` 时，`--run` 使用内建 `run-membership-overview`，精确 locator 使用 `attempt-overview`。`project-current` 才使用配置里的 Report，并在没有配置时回退到通用 `default-overview`。显式 `--report` 始终优先。Config 仍会为 Theme 和 `view` rebuild 加载；这里只说明配置里的 Report 不参与显式 Run 的默认选择。
省略 `--host` 时，`view` 只监听 `127.0.0.1`。传入具体 hostname / IP 会显式监听该地址；只写 `--host` 时则监听全部 IPv4 接口。wildcard listener 先打印 loopback URL，再打印可用接口 URL；`--page` 应用到每条 URL，自动打开浏览器只使用第一条。
非 loopback 模式是无认证、无加密的开发服务器。所有网络可达客户端都能读取报告页面、下载和公开 JSON 文档，所以只能在可信网络使用；启动时也会打印同样的警告。server 只接受已公布的 Host authority 与只读 `GET` / `HEAD` 请求；未来写端点必须另行设计认证与 CSRF 边界。
此前的局部执行可能让部分 slot 以 `reference` 采用已有 Attempt。这些是当时的采用事实，不是补跑状态。同一份 `Sample` 不会在页面请求时重新选择。`--experiment` 可按完整 ID 收窄当前项目目标；`--record` 只在主动读取其它 Record root 时使用。
## `show`
```bash theme={null}
npx niceeval show
npx niceeval show --run 01H...
npx niceeval show --run 01H... --run 01J...
npx niceeval show @01H...
npx niceeval show --run 01H... --page /
npx niceeval show --run 01H... --report ./reports/summary.tsx --page /overview
npx niceeval show --run 01H... --report ./reports/summary.tsx --json
```
`show` 是终端报告入口，适合人直接阅读，也适合 coding agent 在上下文窗口里逐级下钻。它不接受模糊的位置选择。省略 `--page` 时选择默认 Page；提供 `--page ` 时只执行这个精确 route。
参数 Page 的 show 路径只对请求 key 调用 `decode()`、canonical `encode()`、`load()` 与 `render()`。它不调用 `enumerate()`，也不为了查找成员资格而执行其它 Page。通过 Page 的关闭 Evidence 边界验证的 locator、identity 或 key 不属于当前 Sample 时，命令返回类型化错误。
不带 locator 或 `--run` 的 `show` 规划当前项目身份，并扫描默认 Record 中全部 published Run。只有 Experiment、Eval、Attempt 序号、evaluation kind、input identity 与 config identity 仍匹配的 slot 才进入 Sample；命令不会按时间只留一个 Run。没有匹配结果时显示空 Sample，过期结果仍可用完整 `--run` 读取。
`--run` 可重复，只读取这些显式历史 Run。`--experiment ` 可重复，按完整 ExperimentId 收窄当前项目目标，不能与 `--run` 合用。`exp`、不带 `--record` 的 `show` 与 `view` 默认使用同一份结果集。
单个 `--run` 用于核对这一轮的 expected-slot 分母与 membership；多个 `--run` 用同一表形状比较多个固定历史边界。即使两个 Run 指向同一个 Attempt，它们也可能分别由实际执行、自动沿用或人工采用形成。`exp --json` 最后一条 receipt 的 `runIds` 是机器稳定出口；TTY 完成反馈也显示 Run ID。`accept` 的成功反馈会显示新 Run ID，但这行人读文本不是 JSON receipt 或自动化输入契约。
内建 `run-membership-overview` 固定使用 `reportId: "run-membership-overview"`、`pageId: "run-membership"` 和 route `/`。
`Run membership` 表的稳定 column keys 分成三组：
* row identity：`runId`、`slotId`。
* Core 与 provenance：`slotState`、`memberRelation`、`sourceAttemptLocator`、`membershipState`、`membershipOutcome`。
* Attempt 事实：`verdictState`、`verdict`。
单 Run 和多 Run 都按 `runId`、`slotId` 排序；表在排序后最多显示 200 rows，并显示省略数量。
`membershipOutcome` 是内建报告给出的来源结果，值为 `carried`、`accepted`、`executed`、`not-dispatched` 或 `interrupted`。它用于说明本次位置如何得到结果。内建表是 bounded summary；已知 Attempt 的身份与证据用 `show @` 下钻，需要其它 Run 字段时显式选择自定义 Report。
选择完成后，`show` 只执行目标 Page 需要的 Measure 与领域视图。`partial`、`unsupported`、`failed` 等 Analysis 状态会随结果显示；未使用的数据问题不影响当前页面。`show --json` 是同一个单目标读取：内建 Report 返回 Host-owned 领域文档，自定义 Report 返回一个 Page 的 rendered text manifest。完整契约见[查看结果](/docs/zh/tutorials/viewing-results)。
`view --out <目录>`（或显式 `--run`）构建完整自包含静态站。目标目录必须不存在；全部页面、下载项与静态资产路径先通过校验。导出完成后，站点即可独立查看。导出过程不会把底层结果存储交给用户 Report。
view 与静态导出都从同一完整站点版本读取 bytes。运行中的 view 对变化构造候选站点；成功后原子替换当前 revision，失败保留 last-good。静态 export 只写出已完成的完整站点。
## `--early-exit`
`--early-exit` 默认关闭：`--attempts` > 1 时默认把每次 attempt 都跑完，给出真实通过率——这是 NiceEval 衡量 agent 稳不稳的核心指标，默认不该被无声截断。只想知道"这题能不能过"、不在乎完整分布时，显式加 `--early-exit`：某个评估用例的一次 attempt 通过后，自动停止该评估用例剩余的 attempts（省钱）。实验文件里写了 `earlyExit: true` 时，用 `--no-early-exit` 强制关掉它。
## 环境变量只放凭据
跑几次、超时、并发、预算、judge 模型和端点——这些都是配置，只从 CLI flag、`experiments/` 下的 experiment 文件和 `niceeval.config.ts` 读。优先级从高到低：CLI flag > experiment > `niceeval.config.ts` > 内置默认值。没有对应的环境变量，同一个值不会有第三条来路。
环境变量留给凭据（API key、provider token）和终端环境（`NO_COLOR`）。每个 agent / sandbox / judge 只认自己那一个变量名，不会在环境里翻找其它 key。启动时自动加载 cwd 下的 `.env`（不覆盖已经存在的环境变量）。完整清单见[配置与环境变量](/docs/zh/tutorials/configuration)。
## 退出码
| 退出码 | 含义 |
| ----- | ----------------------------------------------------------------------- |
| `0` | 全部评估用例通过（或 `list`、`init`、`clean` 等命令正常完成）。 |
| `1` | 存在 `failed` / `errored` 的评估用例。或命令用法错误（如 `exp` 没匹配到任何实验、传了不支持的 flag 组合）。 |
| `2` | 运行时崩溃（未捕获异常），CLI 顶层捕获后退出。 |
| `130` | 收到中断信号（Ctrl-C / SIGTERM）后退出。 |
CI 的退出码直接来自 Pass Eval 的 Boolean conditions 与最终 Verdict；JUnit 使用同一份已封口的断言结果。