CLI Tools Overview¶

Every CLI command provided by this package, organized by runtime context. Each entry documents the tool's purpose, where it runs, what it assumes, and how it fails when those assumptions are violated.

Host tools¶

Host tools run on the developer's machine (outside any container). They drive git, gh, SSH, and Docker operations. Installed via uv tool install or the dev-tree override venv.

vrg-commit¶

Construct standards-compliant conventional commits with co-author resolution. Performs five branch/context checks before committing (detached HEAD, protected branch, branch prefix, issue number, worktree convention).

Attribute	Value
Source	`vergil_tooling.bin.vrg_commit`
Args	`--type` (required), `--scope`, `--message` (required), `--body`, `--agent` (required)
Preconditions	Git repo, staged changes, not detached HEAD, not on protected branch, branch prefix matches branching model, issue number in branch name, not main worktree when `.worktrees/` present
Failure mode	`SystemExit` with diagnostic on stderr for each check
Exit codes	0 success, 1 rejection or error
Status	Active

vrg-submit-pr¶

Create standards-compliant pull requests. Pushes the current branch and opens a PR with a populated template body.

Attribute	Value
Source	`vergil_tooling.bin.vrg_submit_pr`
Args	`--issue` (required), `--summary` (required), `--linkage` (default: Fixes), `--notes`, `--title`, `--dry-run`
Preconditions	Git repo, `gh` CLI on PATH
Failure mode	Subprocess error from `git push` or `gh pr create`
Exit codes	0 success
Status	Active

vrg-pr-fix-body¶

Repair a PR's body by regenerating it from corrected fields through the same validated builder as vrg-submit-pr, then push an empty commit to re-trigger CI. The agent-safe fix path for body-level standards failures during the pr-watch reconcile loop (denied to the audit identity; the user identity may only fix its own PR).

Attribute	Value
Source	`vergil_tooling.bin.vrg_pr_fix_body`
Args	`pr` (positional, required), `--issue` (required), `--summary` (required), `--linkage` (default: Ref), `--notes`, `--dry-run`, `--no-retrigger`
Preconditions	Git repo, `gh` CLI on PATH, PR open, agent identities on the PR's head branch
Failure mode	`SystemExit`/diagnostic on identity, scope, or state rejection
Exit codes	0 success, 1 rejection or error
Status	Active

vrg-merge-when-green¶

Poll a PR's CI checks, then merge when they all pass. Designed for release-workflow PRs where the agent is both author and reviewer.

Attribute	Value
Source	`vergil_tooling.bin.vrg_merge_when_green`
Args	`pr` (positional, required), `--strategy` (merge/squash/rebase), `--no-delete-branch`
Preconditions	`gh` CLI on PATH, worktree-aware (skips `--delete-branch` in secondary worktrees)
Failure mode	`subprocess.CalledProcessError` from `gh pr checks --fail-fast` on first red check
Exit codes	0 success, non-zero on check failure or merge failure
Status	Active

vrg-prepare-release¶

Automate release preparation: create release branch from develop, merge main, generate changelog and release notes, push, and open PR. Auto-detects the ecosystem (Python, Maven, Go, Ruby, Cargo, Claude plugin, VERSION file) to find the version.

Attribute	Value
Source	`vergil_tooling.bin.vrg_prepare_release`
Args	`--issue` (required)
Preconditions	On `develop` branch, clean working tree, local develop matches `origin/develop`, `gh` and `git-cliff` on PATH
Failure mode	`SystemExit` with clear message for each precondition
Exit codes	0 success, 1 error
Status	Active

vrg-finalize-pr¶

Finalize a pull request. Given a PR, runs the provenance check, merges it, then cleans up; with no PR, runs cleanup only. Cleanup switches to the target branch, fast-forward pulls, deletes merged local branches (auto-removing worktrees inside .worktrees/ when necessary), prunes remotes, runs validation, and checks the CD workflow status.

Attribute	Value
Source	`vergil_tooling.bin.vrg_finalize_pr`
Args	`PR` (optional), `--target-branch` (default: develop), `--strategy` (default: squash), `--allow-provenance-violation`, `--dry-run`
Preconditions	Must run from the main worktree, `vrg-container-run` on PATH
Failure mode	Provenance violations, a dirty working tree, validation failures, or a failed CD run all return exit 1
Exit codes	0 success, 1 provenance/worktree/validation/CD failure or unrecognized branching model
Status	Active

vrg-worktree-status¶

List canonical .worktrees/ worktrees with their derived lifecycle state, so removable cruft (merged/closed PRs whose worktree was never cleaned up) is distinguishable from in-flight work at a glance. Read-only — cleanup stays vrg-finalize-pr's job. PR state is queried from GitHub per worktree; a failed lookup shows as unknown with the reason rather than being silently downgraded.

Attribute	Value
Source	`vergil_tooling.bin.vrg_worktree_status`
Args	`--target-branch` (default: develop)
Preconditions	Git repo; `gh` CLI on PATH for PR state
Failure mode	None for classification — a failed PR lookup is reported as an `unknown` row, never a crash
Exit codes	0 always (read-only)
Status	Active

vrg-ensure-label¶

Ensure GitHub labels exist. Three modes: single-label (create/update one label), sync (provision all labels from the canonical registry), and project (discover repos via a GitHub Project and sync each).

Attribute	Value
Source	`vergil_tooling.bin.vrg_ensure_label`
Args	`--repo`, `--label`, `--color`, `--description`, `--sync`, `--owner`, `--project`
Preconditions	`gh` CLI on PATH
Failure mode	argparse validation for incompatible flag combinations; subprocess error from `gh`
Exit codes	0 success
Status	Active

vrg-container-run¶

Run arbitrary commands inside a dev container. Auto-detects the project language to select the Docker image; falls back to dev-base:latest. Uses execvp to replace the process.

Attribute	Value
Source	`vergil_tooling.bin.vrg_container_run`
Args	`[--prefix <dev\\|prod>] [--] <command> [args...]` (manual parsing, `--` separator)
Preconditions	Git repo, `GH_TOKEN` set, Docker daemon running
Failure mode	Explicit error message for missing `GH_TOKEN`; `assert_docker_available()` exits with message for Docker; `git.repo_root()` raises on non-git directory
Exit codes	0 (help), 1 error; command exit code after `execvp`
Status	Active

vrg-container-test¶

Run a repository's test suite inside a dev container. Auto-detects language and selects appropriate image and test command.

Attribute	Value
Source	`vergil_tooling.bin.vrg_container_test`
Args	None
Preconditions	Git repo, Docker daemon running, language detection or `DOCKER_DEV_IMAGE` + `DOCKER_TEST_CMD`
Failure mode	Explicit error for undetected language and unavailable Docker; `git.repo_root()` raises on non-git directory
Exit codes	0 (help), 1 error; command exit code after `execvp`
Status	Active

vrg-container-docs¶

Preview or build MkDocs documentation inside a dev container. Supports serve (live-reload) and build subcommands. For Python repos, wraps with uv sync --group docs.

Attribute	Value
Source	`vergil_tooling.bin.vrg_container_docs`
Args	`<serve\\|build> [mkdocs args...]` (manual parsing)
Preconditions	Git repo, Docker daemon
Failure mode	Usage message on missing/unknown subcommand
Exit codes	0 (help), 1 error; command exit code after `execvp`
Status	Active

vrg-generate-commands¶

Generate MQSC command methods for all language ports (Python, Ruby, Java, Go, Rust) from mapping-data.json. Updates target files between BEGIN/END GENERATED MQSC METHODS markers.

Attribute	Value
Source	`vergil_tooling.bin.vrg_generate_commands`
Args	`--language` (required), `--mapping-data` (required), `--target`, `--mapping-pages-dir`, `--check`
Preconditions	`mapping-data.json` file exists at the given path
Failure mode	Explicit error for missing mapping data file
Exit codes	0 success, 1 error or `--check` mismatch
Status	Active

Container tools¶

Container tools run inside dev containers launched by vrg-container-run. They assume language toolchain dependencies (ruff, mypy, shellcheck, markdownlint, yamllint) are available on PATH.

vrg-validate-common¶

Shared validation checks for all repos: repository profile validation, markdownlint on published markdown (docs/site/**/*.md and README.md) using the bundled canonical config, shellcheck on scripts/, yamllint on .github/ and docs/ YAML files, hadolint on Dockerfile*, actionlint on .github/workflows/, and ansible-lint (using the bundled canonical config) when the repo carries Ansible content.

Attribute	Value
Source	`vergil_tooling.bin.validate_common`
Args	None
Preconditions	Git repo, `shellcheck` and `yamllint` on PATH
Failure mode	Propagates exit codes from each tool
Exit codes	0 all passed, non-zero on first failure
Status	Active (called internally by `vrg-validate`)

vrg-repo-profile¶

Validate the repository profile in docs/repository-standards.md. Checks that all required attributes are present and none contain placeholder values.

Attribute	Value
Source	`vergil_tooling.bin.vrg_repo_profile`
Args	None
Preconditions	`docs/repository-standards.md` exists
Failure mode	Exit 2 if profile file not found; exit 1 for missing or placeholder attributes
Exit codes	0 valid, 1 invalid, 2 file not found
Status	Active

Removed in this audit¶

st-list-project-repos (removed)¶

Entry point declared in pyproject.toml but the source module vergil_tooling.bin.list_project_repos did not exist. Would crash on import with ModuleNotFoundError. The underlying function (list_project_repos) lives in vergil_tooling.lib.github and is consumed by vrg-ensure-label --owner/--project mode.

st-set-project-field (removed)¶

Entry point declared in pyproject.toml but the source module vergil_tooling.bin.set_project_field did not exist. Would crash on import with ModuleNotFoundError.

Audit notes¶

Precondition consistency¶

Most tools check preconditions explicitly and fail with clear messages. Notable gaps:

vrg-submit-pr does not validate that gh is on PATH before attempting git push and gh pr create. Failure surfaces as a subprocess error rather than a clear precondition message.
vrg-container-run checks GH_TOKEN explicitly; vrg-container-test does not (it will fail inside the container when gh commands run without a token, but the error is less clear).

Args style¶

Most tools use argparse. Two exceptions:

vrg-container-run parses sys.argv manually with a -- separator.
vrg-container-docs parses sys.argv manually with subcommands.

Both are intentional: vrg-container-run passes everything after -- through to docker run, and vrg-container-docs has a simpler interface than argparse would provide. No alignment needed.

Exit code contract¶

0: success
1: check failure, validation error, or precondition violation
2: infrastructure error (used by vrg-repo-profile)

The 1-vs-2 distinction is not universal. Tools added before the convention was established use 1 for all errors.