> ## 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.

# CLI

> 用 query、show 和 view 读取运行记录。

运行评估用 `niceeval exp`。读取结果有三条路：脚本和 CI 用 `niceeval query` 取 JSON，人和 Coding Agent 在终端用 `niceeval show` 逐层查看，在浏览器里审阅用 `niceeval view`。

三条路读的是同一份运行记录 `.niceeval/record.sqlite`。每次读取开始时，NiceEval 会固定一个可见边界：此刻已经写入的结果都能看到，之后写入的不会混进这次读取。所属 Run 还在运行时，已经写入的 Attempt 也能读到。

把 `niceeval exp` 的输出接到管道时，stdout 仍会显示进度。每行带上 Experiment、评估用例和 Attempt 序号。同一个 Attempt 每秒最多输出一次，内容没变就不重复输出。直接在终端里运行时显示动态面板。脚本要读结构化结果时加 `--json`。

重复传入 `--experiment` 可以一次运行多个实验，例如 `niceeval exp --experiment baseline --experiment memory --max-concurrency 4`。这些实验在同一次运行里共享并发上限和预算。同一个 ID 写两次只运行一次。只要有一个 ID 不存在，整条命令在开始执行前就会失败。用了 `--experiment` 后，位置参数用来筛选评估用例。

## `niceeval query`

```sh theme={null}
niceeval query discover
niceeval query explain [--record <file>] --request <file|->
niceeval query run [--record <file>] --request <file|->
```

`query` 使用带版本号的 JSON 请求协议 `niceeval.query/v1`，每一种固定的读取问题叫一个 operation。成功的结果和协议里定义的失败，都会向 stdout 写出恰好一个 JSON 文档。参数写错，或者进程出错到无法生成文档时，错误只写到 stderr。

* `discover` 列出当前版本支持的 operation ID。它不读运行记录，所以不接受 `--record`，也不返回请求的字段结构。
* `explain` 校验完整请求，说明它会运行哪个 operation，以及接下来可以发哪些请求。
* `run` 执行请求，返回该 operation 的完整结果。

先用 `discover` 确认当前版本有哪些 operation，再按本页或[查看结果](/docs/zh/tutorials/viewing-results)里的最小请求来写，并用 `explain` 校验。不要猜字段，也不要用 SQL、JSON path 或公式拼出另一种查询语言。

结果分页时会带一个续读 token。这个 token 记住了 operation、请求内容、读取的记录文件和这次读取的可见边界。任何一项变了，`query` 都不会接着读，而是返回 restart correction，表示调用方要从 `discover` 或重新发请求开始。

## `niceeval show`

```sh theme={null}
niceeval show [--record <file>]
niceeval show --run <run-id>... [--record <file>]
niceeval show --experiment <experiment-id>... [--record <file>]
niceeval show @<locator> [--record <file>]
niceeval show @<locator> --source [--record <file>]
niceeval show @<locator> --execution [--expand <stable-id>] [--record <file>]
niceeval show @<locator> --timing [--record <file>]
niceeval show @<locator> --usage [--record <file>]
niceeval show @<locator> --diff [--record <file>]
```

`show` 在终端里按固定格式显示结果。不带选择参数时显示默认总览。`--run <run-id>` 显示指定的 Run，`--experiment <experiment-id>` 显示指定的 Experiment，两者都可以重复传入。

通过率和分数按评估用例的类型显示：

* 通过制的评估显示 `Verdicts` 和 `Pass rate`。
* 纯计分制的评估显示 `Verdicts` 和 `Score`，不显示通过率。
* 两种混在一起时，只有通过制的行显示通过率。

分数“完整”只说明这个分数算得出来，不代表评估通过。判定为 `failed` 的评估即使分数完整，也显示失败，同时保留它拿到的分数。只有判定为 `passed` 且分数完整的评估才进入成功排名。

判定为 `passed` 且分数完整时，终端详情显示 `scored`，浏览器显示“评分完成”。零分也可以是完整评分：它说明评分做完了，不说明目标已经达成，NiceEval 也没有默认的及格线。gate 失败照样显示失败。分数不完整（`partial`）时只保留已知分数的下限，不算有效评分。

`@<locator>` 选中一个 Attempt。一条命令最多给一个 locator，它不能和 `--run` 或 `--experiment` 同时使用；`--run` 和 `--experiment` 之间也不能同时使用。

选中 Attempt 后，可以加下面任意一个选项看某一方面。这五个选项互斥，都必须配合 Attempt locator：

* `--source`：记录下来的源码信息，以及每条断言在源码里的位置。
* `--execution`：执行过程的概要，篇幅有上限。
* `--timing`：各阶段的耗时。
* `--usage`：用量合计，以及每一次上报的用量。
* `--diff`：运行期间的文件改动。

`--execution` 的输出分开显示三件事：采集状态、上报方是否声明数据完整、分页状态。即使当前页为空或已到最后一页，上报方标记的 `partial` 和限制原因也会保留。

* 用 `--actor <id>` 和 `--type <event-type>` 按参与方和事件类型筛选。
* 用 `--continuation <token>` 翻页时，要带上相同的筛选条件。
* 用 `--expand <stable-id>` 直接展开一项详情。ID 必须取自概要里的 `itemId`、`toolOccurrenceId` 或 `commandId`，不能用位置序号。`--expand` 只能和 `--execution` 一起用，也不能和筛选、翻页参数同时出现。

## `niceeval view`

```sh theme={null}
niceeval view [--run <run-id>...] [--no-open] [--port <port>] [--json]
```

`view` 在本机打开 NiceEval 自带的浏览器界面。不带 `--run` 时打开默认总览，重复传入 `--run` 可以预先选中多个 Run。它不接受位置参数，也不加载项目自己的页面、主题、组件或渲染器。

`--no-open` 只启动服务，不自动打开浏览器。`--port` 指定端口，服务只监听 `127.0.0.1`。页面资源、本机访问授权和读取接口都准备好后，命令向 stdout 输出一次可以打开的本机地址。

加 `--json` 时，stdout 改为 `niceeval.view/v1` 格式的 NDJSON：就绪时输出 `ready` 事件，关闭时输出 `closed` 事件。启动或运行失败时，通过退出码和 stderr 报告。

`view` 只读取当前项目的 `.niceeval/record.sqlite`。打开期间有新结果写入时，页面会提示刷新，确认后才切换到新数据。它没有 `--record`、SQL、部署或分享选项，也不能指定自定义报告、页面、主题、路由或 operation。

## 选择读取方式

三条路读取得到的是同一份结果，但各自负责自己的排版和展示。

| 目标 | 使用 |
| - | - |
| 让脚本或 CI 取得稳定的 JSON | `niceeval query discover`，再用 `explain` / `run` |
| 人或 Coding Agent 在终端查看总览、Run、Experiment 或 Attempt 的摘要 | `niceeval show` |
| 在浏览器里审阅总览或某个 Run | `niceeval view` |
| 在另一台机器上读取同一份结果 | 复制 `.niceeval/record.sqlite`，再用 `--record` 指定它 |

## CLI flags

下表从各命令自己的选项定义生成。表里没有的 flag 会被当作未知参数拒绝。

| Flag | 命令 | 类型 | 说明 |
| - | - | - | - |
| `--help` | `niceeval` | boolean | 打印根命令索引。 |
| `--version` | `niceeval` | boolean | 打印当前安装的 NiceEval 版本。 |
| `--tag` | `niceeval check`、`niceeval exp`、`niceeval exp list` | string | 只选择带有该 tag 的评估用例。 |
| `--help` | `niceeval check`、`niceeval exp`、`niceeval exp list`、`niceeval exp rename`、`niceeval exp --teardown`、`niceeval debug`、`niceeval accept`、`niceeval session` | boolean | 打印该命令的帮助。 |
| `--experiment` | `niceeval exp` | string\[] | 按 Experiment selector 缩小当前项目的结果。 |
| `--attempts` | `niceeval exp` | number | 让每个选中的评估用例运行指定次数。 |
| `--max-concurrency` | `niceeval exp` | number | 限制同时执行的 Attempt 数量。 |
| `--max-build-concurrency` | `niceeval exp` | number | 限制同时准备 Sandbox build 的数量。 |
| `--max-setup-prefix-concurrency` | `niceeval exp` | number | 限制同时准备 Sandbox setup prefix 的数量。 |
| `--sandbox-setup-cache` | `niceeval exp` | string | 使用或绕过 Sandbox 准备缓存。 |
| `--timeout` | `niceeval exp` | number | 以毫秒设置每个 Attempt 的超时时间。 |
| `--budget` | `niceeval exp` | number | 以美元设置本次 Invocation 的预算。 |
| `--junit` | `niceeval exp` | string | 写出必需的 JUnit 报告。 |
| `--json` | `niceeval exp` | boolean | 写出该命令的机器文档或事件流。 |
| `--dry` | `niceeval exp` | boolean | 规划但不创建 Invocation。 |
| `--rerun`（单独使用为 `failed`） / `--rerun=failed\|all` / `--rerun failed\|all` | `niceeval exp` | `failed` \| `all` | 要求重新运行失败目标或全部目标。 |
| `--keep-sandbox`（单独使用为 `failed`） / `--keep-sandbox=failed\|all` | `niceeval exp` | `failed` \| `all` | 保留 failed 或全部已结束 Attempt 的 Sandbox。 |
| `--early-exit` / `--no-early-exit` | `niceeval exp` | boolean | 某次结果通过后停止该评估用例余下的 Attempt。 |
| `--record` | `niceeval exp`、`niceeval accept` | string | 使用指定的 NiceEval Record root。 |
| `--json` | `niceeval exp list` | boolean | 写出该命令的机器文档或事件流。 |
| `--run` | `niceeval exp rename` | string\[] | 选择要采用到目标 Experiment 的一个精确 Run；重复传入会被拒绝。 |
| `--dry` | `niceeval exp rename` | boolean | 预览显式 Experiment 重命名。 |
| `--json` | `niceeval exp rename` | boolean | 写出该命令的机器文档或事件流。 |
| `--teardown` | `niceeval exp --teardown` | boolean | 运行显式的 Experiment teardown 恢复。 |
| `--json` | `niceeval exp --teardown` | boolean | 写出该命令的机器文档或事件流。 |
| `--recover-shared-state` | `niceeval exp --teardown` | string | 指定要显式恢复的共享状态 key。 |
| `--owner-token` | `niceeval exp --teardown` | string | 提供准确的共享状态 owner token。 |
| `--confirm-owner-terminated` | `niceeval exp --teardown` | boolean | 确认记录的 owner 已终止。 |
| `--confirm-remote-quiesced` | `niceeval exp --teardown` | boolean | 确认远端共享状态已静止。 |
| `--json` | `niceeval debug` | boolean | 写出该命令的机器文档或事件流。 |
| `--run` | `niceeval accept` | string\[] | 采用一个已发布的精确 Run；重复传入会被拒绝。 |
| `--dry` | `niceeval accept` | boolean | 完成整 Run 采用预检，但不发布新 Run。 |
| `--all` | `niceeval session` | boolean | 包含已经完成的 Invocation 状态条目。 |
| `--json` | `niceeval session` | boolean | 写出该命令的机器文档或事件流。 |
| `--request` | `niceeval query` | string | 从文件或标准输入读取一个 niceeval.query/v1 request。 |
| `--record` | `niceeval query`、`niceeval show` | string | 读取一个外部 canonical SQLite Record。 |
| `--help` | `niceeval query` | boolean | 打印该命令的帮助。 |
| `--run` | `niceeval show` | string\[] | 显示一个已封口的 Run；可重复传入。 |
| `--experiment` | `niceeval show` | string\[] | 显示一个精确的 Experiment；可重复传入。 |
| `--all` | `niceeval show` | boolean | 显示紧凑 Results 视图中隐藏的 Attempt。 |
| `--source` | `niceeval show` | boolean | 显示一个 Attempt 已捕获的 source facts。 |
| `--execution` | `niceeval show` | boolean | 显示一个 Attempt 的有界 execution outline。 |
| `--actor` | `niceeval show` | string | Filter execution events by exact actor ID. |
| `--type` | `niceeval show` | string | Filter execution events by exact event type. |
| `--continuation` | `niceeval show` | string | Read the next execution page with the same filters. |
| `--timing` | `niceeval show` | boolean | 显示一个 Attempt 已捕获的 timing activities。 |
| `--usage` | `niceeval show` | boolean | 显示一个 Attempt 已捕获的 usage totals。 |
| `--diff` | `niceeval show` | boolean | 显示一个 Attempt 已捕获的文件变更。 |
| `--expand` | `niceeval show` | string | 展开一个稳定的 execution identity。 |
| `--help` | `niceeval show` | boolean | 打印该命令的帮助。 |
| `--run` | `niceeval view` | string\[] | 选择一个已封口的 Run；可重复传入。 |
| `--no-open` | `niceeval view` | boolean | 不请求操作系统打开浏览器。 |
| `--port` | `niceeval view` | string | 选择 loopback 监听端口；0 表示自动选择。 |
| `--json` | `niceeval view` | boolean | 输出 View lifecycle NDJSON，不输出 Inspection 结果。 |
| `--help` | `niceeval view` | boolean | 打印该命令的帮助。 |
| `--all` | `niceeval state migrate` | boolean | 迁移所有已注册的第一方 Service state module。 |
| `--help` | `niceeval state migrate` | boolean | 打印该命令的帮助。 |
| `--help` | `niceeval init` | boolean | 打印该命令的帮助。 |
| `--json` | `niceeval docker profile list`、`niceeval docker profile doctor`、`niceeval docker cache inventory`、`niceeval docker cache gc` | boolean | 写出该命令的机器文档或事件流。 |
| `--domain` | `niceeval docker cache inventory`、`niceeval docker cache gc` | string | 选择一个由 NiceEval 管理的 Docker 缓存域。 |
| `--apply` | `niceeval docker cache gc` | string | 应用先前签发的 Docker 缓存回收计划。 |
| `--help` | `niceeval docker` | boolean | 打印该命令的帮助。 |
| `--all` | `niceeval sandbox stop` | boolean | 销毁全部留存 Sandbox。 |
| `--window` | `niceeval sandbox diff` | string | 选择一个已记录的改动窗口。 |
| `--path` | `niceeval sandbox diff` | string | 选择 Sandbox diff 中的一个路径。 |
| `--leave-running` | `niceeval sandbox enter` | boolean | 离开 shell 后继续保留 Sandbox。 |
| `--record` | `niceeval sandbox list`、`niceeval sandbox enter`、`niceeval sandbox history`、`niceeval sandbox diff`、`niceeval sandbox stop`、`niceeval sandbox prune` | string | 使用指定的 NiceEval Record root。 |
| `--orphans` | `niceeval sandbox list` | boolean | 检查已终止运行遗留的未登记 Sandbox 实例。 |
| `--force` | `niceeval sandbox prune` | boolean | 同时清理未验证的孤儿候选项。 |
| `--development` | `niceeval sandbox` | boolean | Diagnose the isolated Incus development domain instead of reference. |
| `--help` | `niceeval sandbox` | boolean | 打印该命令的帮助。 |
| `--tag` | `niceeval list` | string | 只选择带有该 tag 的评估用例。 |
| `--help` | `niceeval list` | boolean | 打印该命令的帮助。 |


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