CLI 参考

`verso [OPTIONS] [COMMAND]`

不带子命令时，会规划或执行一次完整发布。全局参数可以放在子命令之前或之后。

参数	默认值	含义
`--dry-run`	`false`	输出准确计划，不写文件、不运行 hook，也不执行会修改 Git 的命令
`--json`	`false`	以 JSON 输出 dry-run、doctor 报告或事务状态
`--version <SEMVER>`	交互选择	为完整发布或 `bump` 使用准确且有效的 SemVer 目标
`--config <PATH>`	`verso.toml`	使用其他组配置；其父目录成为发布根目录
`--group <NAME>`	-	选择 `verso.NAME.toml`；与 `--config` 互斥
`--yes`	`false`	接受发布或 bump 确认；不会选择版本
`-V`、`--tool-version`	-	输出已安装的 Verso 版本并退出
`--help`	-	输出命令帮助

Shell

verso --dry-run --version 2.0.0-rc.0verso --group core --version 2.0.0 --yesverso doctor --group core --jsonverso --tool-version

完整发布或 bump 使用 --json 时必须同时使用 --dry-run；doctor --json 和 status --json 不需要 --dry-run。

交互式发布版本选择

完整发布没有 --version 时，Verso 会提供 patch、minor、major、alpha、beta、rc 和自定义 SemVer。当前版本是 prerelease 时，还会提供对应的 stable 版本。

选择 alpha、beta 或 rc 后，需要继续选择 patch、minor、major 或自定义 base。同一个 base 上重复选择同一 channel 会递增数字后缀；切换 channel 或 base 会从 .0 开始。例如从 1.3.0-beta.0 选择 beta + minor，结果是 1.3.0-beta.1。

准确目标版本可以等于或低于当前版本，但会额外显示一个默认否的确认；--yes 会跳过这个确认。stdin 或 stdout 不是终端时，会使用同一套纯文本提示。

准确的 dry-run 计划

Dry-run 会在内存中执行真实的计划转换。文本输出包含操作、发布组、修改文件树，以及每个计划修改实际的完整文件 before/after diff。它不会执行 hook、写文件或运行会修改 Git 的命令。

JSON 会增加 fileChanges 数组，每项包含 path、kind、before、after 和 diff。完整对象包含 operation、group、currentVersion、targetVersion、packageFiles、extraVersionFiles、 versionFiles、changelogFile、fileChanges、commitMessage、tagName、hooks、warnings 和 gitCommands。路径相对于发布根目录；发布的 Git 命令使用 tag object、commit OID 和 upstream 占位符，不会访问远端。Bump 计划不包含 changelog 或 Git 命令。

`verso bump`

Shell

verso bump patchverso bump minor --dry-runverso bump major --group coreverso bump --version 2.0.0

必须且只能提供一个 bump level（patch、minor 或 major）或 --version <SEMVER>。该命令会更新已发现的 package manifest、配置的 Cargo manifest，以及最近 Cargo lockfile 中匹配的记录。它不会更新 changelog、创建 commit 或 tag，也不会 push。只有 before_version 和 after_version hook 会运行。

发布组

一个配置对应一个发布组，组内每个成员的起始版本必须相同。--group core 是 --config verso.core.toml 的简写，两者互斥。独立版本组使用独立配置，并且每条命令只运行一个组。

组名必须以 ASCII 字母或数字开头，后续可以使用 ASCII 字母、数字、- 和 _。

`verso init`

Shell

verso [--config <PATH>] init [--single | --workspace] [--force]

参数	含义
`--single`	写入单包初始配置
`--workspace`	写入 `packages/*` workspace 初始配置
`--force`	替换已有配置文件

没有指定模式时，只通过 packages/*/package.json 检测 workspace。自定义配置路径所需的父目录会按需创建。

`verso doctor`

Shell

verso [--config <PATH> | --group <NAME>] doctor [--json]

报告会检查发布根目录解析、配置、已发现 package、当前及统一版本、配置的 Cargo 版本、changelog 可写性和 Git upstream。文本输出使用 PASS / FAIL；JSON 结构如下：

JSON

{  "ok": true,  "checks": [{ "name": "config", "status": "pass", "message": "..." }],  "packageCount": 3,  "currentVersion": "1.4.0"}

即使 JSON 成功写出，只要 doctor 报告失败，进程仍以状态 1 退出。

事务恢复

Shell

verso [--config <PATH> | --group <NAME>] status [--json]verso [--config <PATH> | --group <NAME>] resume [--retry-hook | --skip-hook]verso [--config <PATH> | --group <NAME>] abort [--force]

status 会显示当前操作、发布组、阶段、版本对、中断的 hook 和修改文件数。使用 --json 时还会输出 canAbort、canForceAbort、pushStarted 和 pushFailed；没有事务时返回 { "active": false }。

resume 会检查持久化计划、跳过已完成的工作，再从记录阶段继续。如果 hook 执行时中断，应先检查其副作用，再从 --retry-hook 和 --skip-hook 中明确选择一个。

abort 只回滚仍由事务拥有的状态，并拒绝覆盖后来修改。手工恢复后，abort --force 只丢弃日志，保留文件和 ref 原样。

准确阶段、校准规则和失败矩阵见发布流程。

Verso 成功时以 0 退出；校验、取消、hook、Git、事务或启动错误以 1 退出。