CLI 参考

`vbumpp [...files]`（默认命令）

发版主命令：更新版本号、生成 changelog、git commit / tag / push、执行发版脚本；装了平台包（如 @vill-v/bumpp-gitee，见安装 · npm）或给出 --provider 时，完成后自动创建平台 Release。

$ vbumpp --help
usage:
  vbumpp [...files]                bump version and generate changelog
  vbumpp release <version>         retry platform release from a changelog section
  vbumpp schema                    export the config JSON schema (--write saves ./vbumpprc.schema.json; --global the ~/.vbumpp/schema.json copy)
  vbumpp token <action> [name]     manage tokens (action: set / list / remove), stored encrypted
  (set/list/remove accept --host <url> for gitlab; remove also accepts --all, --yes, --dry-run)

options:
  -o, --output [output]       where the changelog is generated / read (default: changelog.output in the config, else CHANGELOG.md)
  -r, --recursive             recursively
  --provider <provider>       release provider (github / gitlab / gitee / gitcode)
  --dry-run                   preview the bump/release plan without side effects
  -h, --help                  show help
  -v, --version               show version

flag	说明
`-r`, `--recursive`	递归更新 monorepo 整树包的版本（含 `"private": true` 的包——private 仅表示不发布，版本号随整树一并更新）
`-o`, `--output <path>`	changelog 写入 / 读取路径；给出时优先于配置的 `changelog.output`，未给时回落配置值，两者都没有才用默认 `CHANGELOG.md`
`--provider <name>`	本次发版要创建 Release 的平台：`github` / `gitlab` / `gitee` / `gitcode`（优先级高于平台包的默认平台）
`--dry-run`	预览模式：只打印执行计划，不产生任何副作用（见下文「预览模式」）
`-h`, `--help`	显示帮助
`-v`, `--version`	显示版本号

-o 的几种写法都可以：-o OUT.md、-oOUT.md、--output OUT.md、--output=OUT.md；短 flag 可合并写（如 -ro OUT.md）；-- 之后的参数一律按文件处理。

预览模式（`--dry-run`）

--dry-run 走完真实发版的全部只读计算与前置校验，然后只打印执行计划、不产生任何副作用——零文件写盘、零 git 写操作、零网络请求。预览打印的就是真实执行会做的事。

$ vbumpp --dry-run
ℹ bump plan (dry run — no changes made)
ℹ package.json: update → 1.1.0
ℹ current version: 1.0.0 (source: package.json)
ℹ new version: 1.1.0
ℹ files to write:
ℹ   CHANGELOG.md
ℹ   package.json
ℹ git actions:
ℹ   commit: chore: release v1.1.0
ℹ   tag: v1.1.0
ℹ   git push
ℹ   git push --tags
ℹ changelog preview:
## v1.1.0
...

计划按真实执行序逐行给出：

逐文件预演判定：update → {新版本} / up-to-date / missing
版本：当前版本及其来源（来源文件名，或配置显式 currentVersion）、将更新的新版本
将写盘的文件清单：含 CHANGELOG.md 与 Cargo.lock
将执行的脚本与命令：scripts（preversion / version / postversion）、install（包管理器检测后的实际命令，如 pnpm install）、execute——逐条列出命令文本，均不执行
git 动作完整文本：%s 替换后的 commit message、tag 名、push 序列
changelog 全文预览：生成但不落盘、不提交；没有历史 git tag 时改为打印跳过原因

要点：

前置校验失败照常报错、退出码 1（与真实执行一致）——dry-run 可直接当 CI 预检门禁
版本选择交互保留（不定版本则无计划可预览）；零写盘无需二次确认，Bump? 这一步跳过
传 --provider 时，bump 计划之后追加平台 Release 预览与 token 来源报告（同 vbumpp release --dry-run 的输出，见下节）

CI 预检用法： 发版前先干跑一遍，版本号非法、当前版本无法确定等前置校验失败即 exit 1，可阻塞流水线。

# 发版前干跑：预览完整计划，校验失败即 exit 1
vbumpp --dry-run

`vbumpp release <version> --provider <name>`

单独创建（补发）平台 Release。适用场景：发版流程里 changelog、tag、push 都成功了，只有最后创建 Release 一步失败（网络抖动、token 过期），或者你想为历史版本补建 Release。

vbumpp release 5.1.0 --provider gitee

它会从 changelog 文件里取出 5.1.0 这一节的全部内容作为 Release 描述。changelog 文件路径与 bump 主命令同一套解析：-o 优先，未给时读配置的 changelog.output，都没有才用默认 CHANGELOG.md。版本号写 5.1.0 或 v5.1.0 都行。

执行前会检查本地存在 v5.1.0 这个 git tag、且 changelog 里能找到 5.1.0 这一节。

预览模式（`--dry-run`）

vbumpp release <version> --dry-run 走完真实执行的全部只读前置校验——本地 v<version> tag 存在性、changelog 版本节存在性——任一失败照常报错、退出码 1（与真实执行一致，可当 CI 预检门禁）。校验通过后打印执行计划，全程零网络请求（含 gitlab 的 GET project id）。

$ vbumpp release 5.1.0 --provider github --dry-run
ℹ release plan (dry run — no changes made)
ℹ token source: gh CLI (`gh auth token`)
ℹ provider: Github
ℹ host: https://api.github.com
ℹ repo: owner/repo
ℹ tag_name: v5.1.0
ℹ prerelease: false
ℹ body:
## v5.1.0
...
ℹ requests:
ℹ   POST https://api.github.com/repos/owner/repo/releases

计划含：

token 来源报告：token store / 具体环境变量名 / gh auth token；未配置 token 时降级为一行警告（不报错、退出码仍 0），预览照常输出
平台 Release 预览：provider、目标 host、owner/repo、tag_name、prerelease 判定（beta/alpha 版本号）、body 即提取的 changelog 版本节全文
将发出的请求：HTTP 方法与脱敏后的 URL（gitlab 为 GET project id → POST releases 两步；URL 里 url 编码的 owner%2Frepo 路径可见）

CI 预检用法： 在真正发布前用 dry-run 做检查，校验失败即阻塞流水线。

# 发布前预检：tag / changelog 任一不满足即 exit 1
vbumpp release "$VERSION" --provider "$PROVIDER" --dry-run

`vbumpp schema`

生成 .vbumpprc 配置文件对应的 JSON Schema——编辑器靠它在编写配置时给出补全与报红（JSON / JSONC / TOML 三种格式共用同一份，用法见配置文件参考）。

vbumpp schema                       # 打印到 stdout（纯 JSON，可直接重定向到文件）
vbumpp schema --write               # 写入 ./vbumpprc.schema.json（项目级是默认落点，可显式加 --project）
vbumpp schema --write --global      # 写入 ~/.vbumpp/schema.json（VBUMPP_HOME 生效）

--project 与 --global 互斥，不能同时给；不给 --write 时落点参数无效，一律打印到 stdout。生成的 schema 与当前安装的 vbumpp 版本一致——离线或内网环境可以把写出的文件提交进仓库，配置里改用相对路径引用它。

`vbumpp token <action> [name]`

管理各平台的 access token（详见平台 Release 指南）：

vbumpp token set gitee                                # 录入（输入时隐藏回显）
vbumpp token set gitlab --host https://gitlab-a.com   # 录入某个自建 GitLab 实例
vbumpp token list                                     # 查看已配置的 token（不显示明文）
vbumpp token list --host https://gitlab-a.com         # 只看某个实例
vbumpp token remove gitee                             # 删除（先列清单再确认）

--host 只支持 gitlab：set / remove 对其他 provider 带 --host 报错拒绝；list 的 --host 是实例过滤条件。host 写法宽松：gitlab-a.com、https://gitlab-a.com/、HTTPS://GitLab-A.com 归一为同一条目（归一规则见平台 Release 指南）；token list 里 host 条目显示为 gitlab (https://gitlab-a.com)。

remove 的交互矩阵

删除是破坏性操作，默认先列清单再二次确认（确认默认 No，拒绝即取消、退出码仍为 0）：

$ vbumpp token remove gitlab --all
ℹ tokens to remove:
ℹ   gitlab
ℹ   gitlab (https://gitlab-a.com)
Remove the listed tokens? [y/N]

目标形式	删除范围
`vbumpp token remove gitlab`	仅 provider 级键（不动各 host 条目）
`vbumpp token remove gitlab --host <url>`	仅该实例的条目
`vbumpp token remove gitlab --all`	gitlab 的 provider 级键 + 全部 host 条目
`vbumpp token remove --all`	全部平台的所有 token

修饰 flag	行为
`--dry-run`	只打印将删清单，不确认、不删除（优先级最高，与 `--yes` 同给也只打印）
`--yes`	跳过确认直接删除（CI 等非交互环境用它）

非 TTY 环境（CI、管道）不给 --yes 会因无法交互确认而报错、退出码 1——不会静默删；--host 与 --all 同给是用法错误（退出码 1）。目标不存在时只警告、退出码仍为 0。

退出码

码	含义
`0`	成功；`--dry-run` 下校验通过（token 缺失仅警告，仍为 `0`）
`1`	失败；`--dry-run` 下前置校验失败（tag 缺失 / changelog 无版本节 / 版本号非法等，与真实执行一致）

On this page