exp 选择可签入的运行配置，experiment 后的位置参数才按评估用例 ID 前缀过滤。agent、model 和 flags 写在 experiments/，不靠临时 CLI 参数。
命令
npx niceeval exp [path] [id-prefix]
按 experiment id 路径运行。每个配置的
evals 决定覆盖哪些评估用例。npx niceeval debug <experiment> <eval>
显示一个配对的 Sandbox 与 Plugin 生命周期命令计划，不运行评估。
npx niceeval init
创建空的
evals/ 目录和最小的 niceeval.config.ts。不生成示例评估用例文件。同时写入/刷新 niceeval 指引区块——项目已有 AGENTS.md 就写那份，只有 CLAUDE.md 就写进 CLAUDE.md，都没有则新建 AGENTS.md（见Agent 反馈闭环）。npx niceeval list
发现并打印所有评估用例，不运行。
npx niceeval clean
删除明确 writer 留下的 Record 临时目录，不删除正式 Run 或 Attempt。
npx niceeval show [--run]
在终端执行报告。不带 locator 或
--run 的命令读取当前项目结果；精确 Attempt 定位符或 Run ID 用于审计历史。npx niceeval view
构建完整报告站并在浏览器中托管。它与
show 共享选择规则，但会枚举全部页面。输出语言
CLI 与运行时文案是英语。这只影响终端/runtime 文案，不改变结果 JSON 里的机器字段，也不翻译 LLM Judge prompt。浏览器niceeval view 自己提供中英切换。
npx niceeval exp [path|config] [id-prefix...]
评估用例过滤参数只出现在 experiment 选择之后。只写
npx niceeval weather 不会运行。请使用 npx niceeval exp local weather 或 npx niceeval exp compare weather。npx niceeval exp list [experiment-prefix]
只发现并列出可运行的 Experiment 配置，不创建 Session、不取锁、不启动 Agent 或 Sandbox：
experimentId、描述、agent、model、attempts、选中的 eval 数和 labels。--json 输出单个 niceeval.experiments 文档，并在每项附上完整的 selectedEvalIds。
查看一个配对的完整 Shell 与 lifecycle
shell() / command() 展开为实际命令，普通 callback 标为 opaque。
评估在 Group 内时，只选择这个成员不会把同组其它成员加回计划，但输出仍保留一次 Group lifecycle 包裹。人读输出只显示 COMMAND PLAN；--json 输出单个 niceeval.debug-plan/v1 文档。
TTY 中，总览、Experiment、lane、slot 和每个 lifecycle step 都分别使用与 show 相同的圆角区域框，不会把整棵树放入一个总框。每条 Shell、每个 Plugin occurrence 和每个没有命令或只能运行期确定的阶段都有自己的框：
\n 的单行字符串。缩进、空行、末尾换行和长行续行都会保留；终端控制字符显示为转义文本：
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-bearingSandboxLayer，并从 niceeval/sandbox 导入下列工厂之一：
dockerSandbox({ source: { type: "image", image } })dockerComposeSandbox({ file, workspaceService })dockerSandbox({ source: { type: "dockerfile", context } })vercelSandbox({ snapshotId })e2bSandbox({ template })localSandbox()
list
exp
show 与 view 是顶层命令，应写成 npx niceeval show、npx niceeval view。误写成 npx niceeval exp show / exp view 且没有同名 experiment 时，CLI 会在“不存在的实验”错误后提示正确命令。仓库确实存在同名 experiment 时仍按合法 id 执行。
两种输出：人读文本与 --json
exp 的输出只有两种形态，只改变展示，不改变选择、调度、判定、Record 提交或退出码：
watch 或 session 查询；长期数据从停稳 Record 生成报告。
view
show 共用默认 Report 与选择规则。不带 locator 或 --run 的命令读取所有身份仍匹配当前项目的结果；精确 @<AttemptLocator> 显示该 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
show 是终端报告入口，适合人直接阅读，也适合 coding agent 在上下文窗口里逐级下钻。它不接受模糊的位置选择。省略 --page 时选择默认 Page；提供 --page <route> 时只执行这个精确 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 <id> 可重复，按完整 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。
runId、slotId 排序；表在排序后最多显示 200 rows，并显示省略数量。
membershipOutcome 是内建报告给出的来源结果，值为 carried、accepted、executed、not-dispatched 或 interrupted。它用于说明本次位置如何得到结果。内建表是 bounded summary；已知 Attempt 的身份与证据用 show @<AttemptLocator> 下钻，需要其它 Run 字段时显式选择自定义 Report。
选择完成后，show 只执行目标 Page 需要的 Measure 与领域视图。partial、unsupported、failed 等 Analysis 状态会随结果显示；未使用的数据问题不影响当前页面。show --json 是同一个单目标读取：内建 Report 返回 Host-owned 领域文档，自定义 Report 返回一个 Page 的 rendered text manifest。完整契约见查看结果。
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（不覆盖已经存在的环境变量）。完整清单见配置与环境变量。
退出码
CI 的退出码直接来自 Pass Eval 的 Boolean conditions 与最终 Verdict；JUnit 使用同一份已封口的断言结果。