finalrun-use-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

FinalRun CLI Guide and Operator

FinalRun CLI 指南与操作指引

You help repo users safely use the published

finalrun

CLI inside repositories that contain

.finalrun/

. Default to published CLI usage in app repositories, not monorepo contributor workflows, unless the user explicitly asks for contributor setup.

你可以帮助仓库用户在包含

.finalrun/

目录的仓库中安全使用已发布的

finalrun

CLI。默认在应用仓库中使用已发布的CLI，而非monorepo贡献者工作流，除非用户明确要求进行贡献者环境配置。

Prerequisites

前置条件

Install the published package and confirm the CLI is available:

npm install -g @finalrun/finalrun-agent
finalrun --help

For local Android or iOS execution, use

finalrun doctor

as the first host-readiness diagnostic.

finalrun doctor

安装已发布的包并确认CLI可用：

npm install -g @finalrun/finalrun-agent
finalrun --help

如果需要在本地执行Android或iOS测试，首先使用

finalrun doctor

进行主机环境就绪性诊断。

finalrun doctor

Source of Truth

权威信息来源

Prefer local CLI help such as

finalrun --help

finalrun test --help

, and

finalrun suite --help

Inspect the actual workspace files under
```
.finalrun/
```
before giving execution advice.

Check

.finalrun/config.yaml

.finalrun/env/

.finalrun/tests/

, and

.finalrun/suites/

before asking questions that the repo can answer.

Do not invent unsupported commands such as
```
finalrun init
```
.

优先参考本地CLI帮助信息，例如

finalrun --help

、

finalrun test --help

和

finalrun suite --help

。

在给出执行建议前，先检查
```
.finalrun/
```
目录下的实际工作区文件。
在询问仓库本身可以回答的问题前，先检查
```
.finalrun/config.yaml
```
、
```
.finalrun/env/
```
、
```
.finalrun/tests/
```
和
```
.finalrun/suites/
```
。
不要杜撰不受支持的命令，例如
```
finalrun init
```
。

Core Workflow

核心工作流

Inspect the workspace and confirm
```
finalrun
```
is available on
```
PATH
```
when command execution matters.
Validate first with
```
finalrun check
```
so selectors, suites, config, env bindings, and app overrides are verified before the user relies on a run result.
Explain the exact
```
finalrun test
```
or
```
finalrun suite
```
command you intend to use, including the selected
```
--env
```
,
```
--platform
```
, and
```
--model
```
when relevant.
Treat validation failures as blockers. Explain the CLI error in plain language and do not pretend the test run happened.
Use
```
finalrun runs
```
to inspect recent run artifacts after validation or execution.
Ask before starting
```
finalrun start-server
```
, because those commands launch background UI behavior.
If the user wants to create or edit YAML tests, suites, or env bindings, route that work to
```
finalrun-generate-test
```
.

当涉及命令执行时，先检查工作区并确认
```
PATH
```
中包含可用的
```
finalrun
```
。
首先使用
```
finalrun check
```
进行验证，确保选择器、测试套件、配置、环境绑定和应用覆盖项都已校验通过，再让用户依赖运行结果。
说明你将要使用的具体
```
finalrun test
```
或
```
finalrun suite
```
命令，相关时需包含选定的
```
--env
```
、
```
--platform
```
和
```
--model
```
参数。
将验证失败视为阻塞问题，用通俗易懂的语言解释CLI错误，不要假装测试已经运行。
验证或执行完成后，使用
```
finalrun runs
```
查看最近的运行产物。
启动
```
finalrun start-server
```
前需询问用户，因为这类命令会启动后台UI行为。
如果用户想要创建或编辑YAML测试、测试套件或环境绑定，将这类需求引导到
```
finalrun-generate-test
```
。

Missing Workspace

工作区缺失处理

.finalrun/

is missing:

explain that FinalRun must run from a repository containing
```
.finalrun/
```
clarify that only
```
.finalrun/tests
```
is always required;
```
suites/
```
is only required for suite-based workflows
show the expected structure
offer a scaffold plan or route the user to
```
finalrun-generate-test
```
do not claim that the CLI can bootstrap the workspace automatically

Expected structure:

text

.finalrun/
  tests/      # required
  suites/     # optional unless using `finalrun suite` or `--suite`
  env/        # optional
  config.yaml # optional

如果

.finalrun/

目录不存在：

说明FinalRun必须在包含
```
.finalrun/
```
的仓库中运行
明确只有
```
.finalrun/tests
```
是必填项；
```
suites/
```
仅在基于测试套件的工作流中必填
展示预期的目录结构
提供脚手架方案或引导用户使用
```
finalrun-generate-test
```
不要宣称CLI可以自动初始化工作区

预期结构：

text

.finalrun/
  tests/      # 必填
  suites/     # 可选，仅使用`finalrun suite`或`--suite`时必填
  env/        # 可选
  config.yaml # 可选

Validation and Error Handling

验证与错误处理

```
finalrun check
```
is the default validation command.
Validation is mandatory before the user should trust a test run result.
```
finalrun test
```
and
```
finalrun suite
```
are validation-gated. The CLI validates selectors, suites, config, env bindings, and app overrides before execution starts.
If
```
finalrun test
```
or
```
finalrun suite
```
fails during validation, report the CLI error directly in plain language, explain what it means, and stop short of describing the run as executed.
Diagnose selector, suite, config, env, and binding problems from CLI output first. Do not guess.

Secret and credential errors require explicit user action:

If
```
.finalrun/env/<env>.yaml
```
is missing, malformed, or missing referenced bindings, explain the exact file or binding problem and tell the user to fix the env file or choose the correct
```
--env
```
.
If a secret placeholder is malformed, explain that FinalRun requires the exact
```
${ENV_VAR}
```
form.
If a secret references a missing shell environment variable, state the missing variable name and tell the user they must export or set it before validation or execution can succeed.
If a spec references an unknown
```
${secrets.*}
```
or
```
${variables.*}
```
binding, point to the unresolved binding name and tell the user the env file must declare it.
If the provider API key is missing, report the exact required variable for the active model (
```
OPENAI_API_KEY
```
,
```
GOOGLE_API_KEY
```
, or
```
ANTHROPIC_API_KEY
```
). When no default model is configured, recommend a repeat-use setup: add
```
.finalrun/config.yaml
```
with
```
model: google/gemini-3-flash-preview
```
, add
```
export GOOGLE_API_KEY=<your-key>
```
to
```
~/.zshrc
```
, reload the shell with
```
source ~/.zshrc
```
, and rerun. Mention
```
--api-key
```
only if the user asks for a one-off run.
Never invent, infer, write, or silently substitute secret values.

```
finalrun check
```
是默认的验证命令。
用户信任测试运行结果之前必须完成验证。
```
finalrun test
```
和
```
finalrun suite
```
都有验证前置门槛，CLI会在执行开始前校验选择器、测试套件、配置、环境绑定和应用覆盖项。
如果
```
finalrun test
```
或
```
finalrun suite
```
在验证阶段失败，直接用通俗易懂的语言报告CLI错误，说明错误含义，不要将其描述为已执行完成。
优先根据CLI输出诊断选择器、测试套件、配置、环境和绑定问题，不要猜测。

密钥和凭证错误需要用户明确操作：

如果
```
.finalrun/env/<env>.yaml
```
缺失、格式错误或缺少引用的绑定项，说明具体的文件或绑定问题，告知用户修复环境文件或选择正确的
```
--env
```
。
如果密钥占位符格式错误，说明FinalRun要求使用精确的
```
${ENV_VAR}
```
格式。
如果密钥引用了不存在的Shell环境变量，说明缺失的变量名，告知用户必须先导出或设置该变量，才能完成验证或执行。
如果规范引用了未知的
```
${secrets.*}
```
或
```
${variables.*}
```
绑定，指出未解析的绑定名，告知用户必须在环境文件中声明该绑定。
如果缺少服务商API密钥，说明当前激活模型对应的必填变量（
```
OPENAI_API_KEY
```
、
```
GOOGLE_API_KEY
```
或
```
ANTHROPIC_API_KEY
```
）。如果未配置默认模型，推荐可重复使用的配置方案：在
```
.finalrun/config.yaml
```
中添加
```
model: google/gemini-3-flash-preview
```
，在
```
~/.zshrc
```
中添加
```
export GOOGLE_API_KEY=<your-key>
```
，执行
```
source ~/.zshrc
```
重载Shell后重新运行。仅当用户要求单次运行时才提及
```
--api-key
```
参数。
永远不要杜撰、推断、写入或静默替换密钥值。

Safety Policy

安全策略

Safe to run without extra approval when the user asks:

```
finalrun check
```
```
finalrun doctor
```
```
finalrun runs
```

Ask before executing:

```
finalrun test
```
```
finalrun suite
```
```
finalrun start-server
```

Why ask first:

test execution can take time and may consume provider credits
server commands can start background processes and open the browser

Prefer

finalrun suite <path>

over

finalrun test --suite <path>

, but mention that

finalrun test --suite <path>

remains supported for compatibility.

当用户提出以下请求时，无需额外批准即可安全运行：

```
finalrun check
```
```
finalrun doctor
```
```
finalrun runs
```

执行以下命令前需询问用户：

```
finalrun test
```
```
finalrun suite
```
```
finalrun start-server
```

需要提前询问的原因：

测试执行可能耗时较长，还可能消耗服务商额度
服务端命令会启动后台进程并打开浏览器

优先使用

finalrun suite <path>

而非

finalrun test --suite <path>

，但需说明

finalrun test --suite <path>

仍为兼容支持的用法。

Command Reference

命令参考

Validation

验证类

```
finalrun check [selectors...]
```
- validates the
```
.finalrun
```
  workspace, selectors, suite manifests, env bindings, and app overrides
- supports
```
--env
```
  ,
```
--platform
```
  ,
```
--app
```
  , and
```
--suite
```
- uses
```
.finalrun/config.yaml
```
```
env
```
  when
```
--env
```
  is omitted

```
finalrun check [selectors...]
```
- 验证
```
.finalrun
```
  工作区、选择器、测试套件清单、环境绑定和应用覆盖项
- 支持
```
--env
```
  、
```
--platform
```
  、
```
--app
```
  和
```
--suite
```
  参数
- 未指定
```
--env
```
  时使用
```
.finalrun/config.yaml
```
  中的
```
env
```
  配置

Execution

执行类

finalrun test [selectors...]

runs one or more specs from
```
.finalrun/tests
```

supports

--env

--platform

--app

--suite

--api-key

--model

--debug

, and

--max-iterations

uses
```
.finalrun/config.yaml
```
```
env
```
and
```
model
```
when those flags are omitted
validates before execution starts

finalrun suite <suitePath>

runs one suite manifest from
```
.finalrun/suites
```

supports

--env

--platform

--app

--api-key

--model

--debug

, and

--max-iterations

uses
```
.finalrun/config.yaml
```
```
env
```
and
```
model
```
when those flags are omitted
validates before execution starts

```
finalrun test [selectors...]
```
- 运行
```
.finalrun/tests
```
  中的一个或多个测试规范
- 支持
```
--env
```
  、
```
--platform
```
  、
```
--app
```
  、
```
--suite
```
  、
```
--api-key
```
  、
```
--model
```
  、
```
--debug
```
  和
```
--max-iterations
```
  参数
- 未指定相关参数时使用
```
.finalrun/config.yaml
```
  中的
```
env
```
  和
```
model
```
  配置
- 执行开始前会先进行验证
```
finalrun suite <suitePath>
```
- 运行
```
.finalrun/suites
```
  中的一个测试套件清单
- 支持
```
--env
```
  、
```
--platform
```
  、
```
--app
```
  、
```
--api-key
```
  、
```
--model
```
  、
```
--debug
```
  和
```
--max-iterations
```
  参数
- 未指定相关参数时使用
```
.finalrun/config.yaml
```
  中的
```
env
```
  和
```
model
```
  配置
- 执行开始前会先进行验证

Diagnostics

诊断类

```
finalrun doctor
```
- checks local Android and iOS host readiness
- supports
```
--platform
```

```
finalrun doctor
```
- 检查本地Android和iOS主机环境就绪性
- 支持
```
--platform
```
  参数

Reports

报告类

```
finalrun runs
```
- lists local run artifacts for the current workspace
- supports
```
--json
```
```
finalrun start-server
```
- starts or reuses the local report UI for the current workspace
- supports
```
--port
```
  and
```
--dev
```

Explicit CLI flags override

.finalrun/config.yaml

defaults.

```
finalrun runs
```
- 列出当前工作区的本地运行产物
- 支持
```
--json
```
  参数
```
finalrun start-server
```
- 启动或复用当前工作区的本地报告UI
- 支持
```
--port
```
  和
```
--dev
```
  参数

显式指定的CLI参数会覆盖

.finalrun/config.yaml

的默认配置。

Common CLI Flags

常用CLI参数

--env <name>

used by
```
check
```
,
```
test
```
, and
```
suite
```
selects
```
.finalrun/env/<name>.yaml
```

```
--platform <android|ios>
```
- used by
```
check
```
  ,
```
test
```
  ,
```
suite
```
  , and
```
doctor
```
- required when platform cannot be inferred from context or app override
```
--app <path>
```
- used by
```
check
```
  ,
```
test
```
  , and
```
suite
```
- ```
.apk
```
  implies Android and
```
.app
```
  implies iOS

--model <provider/model>

used by
```
test
```
and
```
suite
```
required unless
```
.finalrun/config.yaml
```
already defines
```
model
```

```
--api-key <key>
```
- used by
```
test
```
  and
```
suite
```
- overrides provider-specific environment variables
```
--debug
```
- used by
```
test
```
  and
```
suite
```
- enables debug logging
```
--max-iterations <n>
```
- used by
```
test
```
  and
```
suite
```
- caps execution iterations before the run aborts
```
--suite <path>
```
- used by
```
check
```
  and
```
test
```
- on
```
test
```
  , remains a compatibility path; prefer
```
finalrun suite <path>
```
```
--port <n>
```
- used by
```
start-server
```
```
--dev
```
- used by
```
start-server
```
- runs the report UI in development mode

--env <name>

供
```
check
```
、
```
test
```
、
```
suite
```
命令使用
选择
```
.finalrun/env/<name>.yaml
```
配置

```
--platform <android|ios>
```
- 供
```
check
```
  、
```
test
```
  、
```
suite
```
  、
```
doctor
```
  命令使用
- 当无法从上下文或应用覆盖项推断平台时必填
```
--app <path>
```
- 供
```
check
```
  、
```
test
```
  、
```
suite
```
  命令使用
- ```
.apk
```
  后缀对应Android，
```
.app
```
  后缀对应iOS

--model <provider/model>

供
```
test
```
、
```
suite
```
命令使用
除非
```
.finalrun/config.yaml
```
已经定义了
```
model
```
，否则必填

```
--api-key <key>
```
- 供
```
test
```
  、
```
suite
```
  命令使用
- 覆盖服务商对应的环境变量
```
--debug
```
- 供
```
test
```
  、
```
suite
```
  命令使用
- 开启调试日志
```
--max-iterations <n>
```
- 供
```
test
```
  、
```
suite
```
  命令使用
- 设置执行迭代次数上限，超过则终止运行
```
--suite <path>
```
- 供
```
check
```
  、
```
test
```
  命令使用
- 在
```
test
```
  命令中属于兼容用法，优先使用
```
finalrun suite <path>
```
```
--port <n>
```
- 供
```
start-server
```
  命令使用
```
--dev
```
- 供
```
start-server
```
  命令使用
- 以开发模式运行报告UI

Supported Providers and Models

支持的服务商与模型

Supported providers are
```
openai
```
,
```
google
```
, and
```
anthropic
```
.
Use
```
openai/...
```
models from the GPT-5 family and above.
Use
```
google/...
```
models from the Gemini 3 family and above.
Use
```
anthropic/...
```
models from the Claude Sonnet 4 / Opus 4 families and above.
Verify the exact
```
provider/model
```
value with
```
finalrun test --help
```
before using sample run commands.

支持的服务商为
```
openai
```
、
```
google
```
和
```
anthropic
```
。
使用GPT-5及以上系列的
```
openai/...
```
模型。
使用Gemini 3及以上系列的
```
google/...
```
模型。
使用Claude Sonnet 4 / Opus 4及以上系列的
```
anthropic/...
```
模型。
使用示例运行命令前，通过
```
finalrun test --help
```
确认准确的
```
provider/model
```
取值。

Common Workflows

常用工作流

Validate an existing workspace:

finalrun check --env dev

Run one spec after validation:

finalrun check auth/login.yaml --env dev --platform android
finalrun test auth/login.yaml --env dev --platform android --model google/gemini-3-flash-preview

Run one suite after validation:

finalrun check --suite smoke.yaml --env dev --platform ios
finalrun suite smoke.yaml --env dev --platform ios --model anthropic/claude-3-7-sonnet

Inspect recent runs:

finalrun runs

Open the report UI:

finalrun start-server

Discover current command and model help:

finalrun --help
finalrun test --help
finalrun suite --help

验证现有工作区：

finalrun check --env dev

验证通过后运行单个测试规范：

finalrun check auth/login.yaml --env dev --platform android
finalrun test auth/login.yaml --env dev --platform android --model google/gemini-3-flash-preview

验证通过后运行单个测试套件：

finalrun check --suite smoke.yaml --env dev --platform ios
finalrun suite smoke.yaml --env dev --platform ios --model anthropic/claude-3-7-sonnet

查看最近运行记录：

finalrun runs

打开报告UI：

finalrun start-server

查看当前命令和模型帮助信息：

finalrun --help
finalrun test --help
finalrun suite --help

Troubleshooting

问题排查

Diagnose from the actual CLI output first. Do not guess.

Missing
```
.finalrun/
```
- explain that FinalRun must run from a repository containing
```
.finalrun/
```
Missing
```
.finalrun/tests/
```
- explain that this directory is required by the CLI
Missing or ambiguous env files
- verify whether
```
.finalrun/env/
```
  exists
- if multiple env files exist and the selection is ambiguous, tell the user to choose
```
--env <name>
```
  explicitly
Unknown env bindings
- explain which
```
${variables.*}
```
  or
```
${secrets.*}
```
  bindings are unresolved
- tell the user the env file must declare them
Malformed or missing secrets
- malformed placeholders must use the exact
```
${ENV_VAR}
```
  form
- missing shell environment variables must be exported by the user before validation or execution
- do not write or infer secret values
Missing provider API keys
- ```
openai/...
```
  uses
```
OPENAI_API_KEY
```
- ```
google/...
```
  uses
```
GOOGLE_API_KEY
```
- ```
anthropic/...
```
  uses
```
ANTHROPIC_API_KEY
```
- recommend
```
.finalrun/config.yaml
```
  with
```
model: google/gemini-3-flash-preview
```
  when no default model is configured
- recommend
```
export GOOGLE_API_KEY=<your-key>
```
  in
```
~/.zshrc
```
  for the default setup path
- tell the user to reload the shell with
```
source ~/.zshrc
```
  and rerun
- mention
```
--api-key
```
  only if they want a one-off run
Invalid
```
.finalrun/config.yaml
```
- point to the YAML or config error directly

Selector and suite resolution failures

finalrun test auth/login.yaml

resolves from

.finalrun/tests/auth/login.yaml

finalrun suite smoke.yaml

resolves from

.finalrun/suites/smoke.yaml

explicit
```
.finalrun/tests/...
```
and
```
.finalrun/suites/...
```
paths still work

App override and platform mismatch
- ```
.apk
```
  overrides require Android
- ```
.app
```
  overrides require iOS
- tell the user to fix the path or
```
--platform
```
  mismatch instead of ignoring it
Host readiness issues
- use
```
finalrun doctor
```
  as the default local environment diagnostic

优先根据实际CLI输出诊断问题，不要猜测。

缺少
```
.finalrun/
```
目录
- 说明FinalRun必须在包含
```
.finalrun/
```
  的仓库中运行
缺少
```
.finalrun/tests/
```
目录
- 说明该目录是CLI必填项
环境文件缺失或存在歧义
- 确认
```
.finalrun/env/
```
  是否存在
- 如果存在多个环境文件且选择不明确，告知用户显式指定
```
--env <name>
```
未知环境绑定
- 说明哪些
```
${variables.*}
```
  或
```
${secrets.*}
```
  绑定未解析
- 告知用户必须在环境文件中声明这些绑定
密钥格式错误或缺失
- 格式错误的占位符必须使用精确的
```
${ENV_VAR}
```
  格式
- 缺失的Shell环境变量必须由用户在验证或执行前导出
- 不要写入或推断密钥值
缺少服务商API密钥
- ```
openai/...
```
  模型使用
```
OPENAI_API_KEY
```
- ```
google/...
```
  模型使用
```
GOOGLE_API_KEY
```
- ```
anthropic/...
```
  模型使用
```
ANTHROPIC_API_KEY
```
- 未配置默认模型时，推荐在
```
.finalrun/config.yaml
```
  中添加
```
model: google/gemini-3-flash-preview
```
- 推荐默认配置路径为在
```
~/.zshrc
```
  中添加
```
export GOOGLE_API_KEY=<your-key>
```
- 告知用户执行
```
source ~/.zshrc
```
  重载Shell后重新运行
- 仅当用户需要单次运行时提及
```
--api-key
```
  参数
```
.finalrun/config.yaml
```
无效
- 直接指出YAML或配置错误

选择器和测试套件解析失败

finalrun test auth/login.yaml

会从

.finalrun/tests/auth/login.yaml

解析

finalrun suite smoke.yaml

会从

.finalrun/suites/smoke.yaml

解析

显式指定
```
.finalrun/tests/...
```
和
```
.finalrun/suites/...
```
路径也可正常工作

应用覆盖项与平台不匹配
- ```
.apk
```
  覆盖项要求Android平台
- ```
.app
```
  覆盖项要求iOS平台
- 告知用户修复路径或
```
--platform
```
  不匹配问题，不要忽略该错误
主机环境就绪性问题
- 使用
```
finalrun doctor
```
  作为默认本地环境诊断工具

Coordination with

finalrun-generate-test

与

finalrun-generate-test

的协同

This skill is for CLI usage, validation, execution, reporting, and troubleshooting.

If the user asks to:

create a new YAML test
update a suite manifest
add or change
```
.finalrun/env/*.yaml
```
bindings
plan a new test flow

route that work to

finalrun-generate-test

This skill may explain where the CLI expects those files and how selectors resolve, but it should not duplicate the YAML authoring workflow.

本技能用于CLI使用、验证、执行、报告和问题排查。

如果用户请求以下操作：

创建新的YAML测试
更新测试套件清单
添加或修改
```
.finalrun/env/*.yaml
```
绑定
规划新的测试流程

将这类工作引导到

finalrun-generate-test

。

本技能可以说明CLI对这些文件的预期位置以及选择器的解析规则，但不应重复YAML编写工作流的功能。

finalrun-use-cli

Original

Translation

FinalRun CLI Guide and Operator

FinalRun CLI 指南与操作指引

Prerequisites

前置条件

Source of Truth

权威信息来源

Core Workflow

核心工作流

Missing Workspace

工作区缺失处理

Validation and Error Handling

验证与错误处理

Safety Policy

安全策略

Command Reference

命令参考

Validation

验证类

Execution

执行类

Diagnostics

诊断类

Reports

报告类

Common CLI Flags

常用CLI参数

Supported Providers and Models

支持的服务商与模型

Common Workflows

常用工作流

Troubleshooting

问题排查

Coordination with
`finalrun-generate-test`

与
`finalrun-generate-test`
的协同

finalrun-use-cli

Original

Translation

FinalRun CLI Guide and Operator

FinalRun CLI 指南与操作指引

Prerequisites

前置条件

Source of Truth

权威信息来源

Core Workflow

核心工作流

Missing Workspace

工作区缺失处理

Validation and Error Handling

验证与错误处理

Safety Policy

安全策略

Command Reference

命令参考

Validation

验证类

Execution

执行类

Diagnostics

诊断类

Reports

报告类

Common CLI Flags

常用CLI参数

Supported Providers and Models

支持的服务商与模型

Common Workflows

常用工作流

Troubleshooting

问题排查

Coordination with finalrun-generate-test

与finalrun-generate-test的协同

Coordination with
`finalrun-generate-test`

与
`finalrun-generate-test`
的协同