feat(cli): add cz --version back and add cz --report to separate them from cz version

[bearomorphism]

Description

Currently, all of cz version, cz version --commitizen, and cz version --report print the installed Commitizen version / system info. As we extend cz version to also report the project version (see #1785), it makes sense to extract those two installed-Commitizen / bug-report concerns out of the version subcommand and back into top-level flags:

• cz --version / cz -v — print the installed Commitizen version and exit.
• cz --report — print Commitizen version, Python version, and OS, intended for bug reports, and exit.

The corresponding subcommand options are kept and emit a DeprecationWarning pointing at the new flags; they will be removed in v5.

Closes part of #1785.

Checklist

• I have read the contributing guidelines

Was generative AI tooling used to co-author this PR?

• Yes (please specify the tool below)

Generated-by: GitHub Copilot following the guidelines

Code Changes

• Add test cases to all the changes you introduce
• Run uv run poe all locally to ensure this change passes linter check and tests
• Manually test the changes:
  • Verify the feature/bug fix works as expected in real-world scenarios
  • Test edge cases and error conditions
  • Ensure backward compatibility is maintained (cz version --commitizen / cz version --report keep working with deprecation warnings)
  • Document any manual testing steps performed (see below)
• Update the documentation for the changes

Documentation Changes

• Run uv run poe doc locally to ensure the documentation pages renders correctly
• Check and fix any broken links (internal or external)

Expected Behavior

Invocation	Behavior
cz --version / cz -v	Print installed Commitizen version. Takes precedence over any subcommand.
cz --report	Print Commitizen version, Python version, OS. Only takes effect when no subcommand is given.
cz --report version	Runs the version subcommand (top-level --report is a "no subcommand" flag — kept simple by design).
cz version --commitizen	Still works, emits DeprecationWarning pointing at cz --version.
cz version --report	Still works, emits DeprecationWarning pointing at cz --report.
cz --invalid-arg	Errors with argparse unrecognized arguments: --invalid-arg (previously silently fell through).
cz (no args)	Prints help — unchanged.
cz invalidCommand	argparse invalid choice error — unchanged.

Steps to Test This Pull Request

uv sync --frozen --group base --group test --group linters

# New top-level flags
uv run cz --version
uv run cz -v
uv run cz --report

# Deprecated subcommand flags still work
uv run cz version --commitizen   # emits DeprecationWarning
uv run cz version --report       # emits DeprecationWarning

# Unknown args now error properly
uv run cz --invalid-arg          # exits 13, prints argparse usage + "unrecognized arguments"

# Regression tests
uv run pytest tests/test_cli.py tests/commands/test_version_command.py
uv run poe lint

Additional Context

Related: #1785.

Reviewer feedback addressed in this PR:

• Empty tests/test_cli/test_invalid_command_py_*___invalid_arg_.txt baselines were a side effect of changing subcommands.required to False (needed so the new top-level flags work without a subcommand). parse_known_args() then silently swallowed --invalid-arg. Fixed by re-running parser.parse_args() when there is no subcommand and unknown args are present, so argparse's unrecognized arguments error reaches stderr; baselines regenerated for Python 3.10–3.14.
• The earlier suggestion to make cz --report version route to the top-level --report was intentionally left as-is: --report stays a simple "no subcommand" flag (per @woile's note: existing cz version --* options are kept until all the new features are out, then removed in v5).

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.24%. Comparing base (efb1a7d) to head (79631f4).
⚠️ Report is 15 commits behind head on master.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1798      +/-   ##
==========================================
+ Coverage   98.23%   98.24%   +0.01%     
==========================================
  Files          61       61              
  Lines        2772     2799      +27     
==========================================
+ Hits         2723     2750      +27     
  Misses         49       49              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[bearomorphism]

Will deprecate cz version --report and cz version --commitizen

[woile]

Good. Remember that the existing ones, under cz version, we don't remove until all the features are out 👍🏻

[Copilot]

Pull request overview

This PR adjusts the Commitizen CLI interface to reintroduce a top-level cz --version/-v and add a top-level cz --report, separating these concerns from the evolving cz version subcommand (per #1785).

Changes:

• Added global --version/-v handling to print the installed Commitizen version and exit.
• Added global --report handling to print system info for bug reports and exit.
• Deprecated cz version --report and cz version --commitizen via warnings, and updated CLI regression snapshots/tests accordingly.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/test_cli/test_no_argv_py_3_14_.txt	Updates help output snapshot to include global -v/--version and --report.
tests/test_cli/test_no_argv_py_3_13_.txt	Updates help output snapshot to include global -v/--version and --report.
tests/test_cli/test_no_argv_py_3_12_.txt	Updates help output snapshot to include global -v/--version and --report.
tests/test_cli/test_no_argv_py_3_11_.txt	Updates help output snapshot to include global -v/--version and --report.
tests/test_cli/test_no_argv_py_3_10_.txt	Updates help output snapshot to include global -v/--version and --report.
tests/test_cli/test_invalid_command_py_3_14_invalidCommand_.txt	Updates invalid-command snapshot to reflect new global options in usage.
tests/test_cli/test_invalid_command_py_3_14___invalid_arg_.txt	Modifies invalid-arg snapshot file content (currently emptied in this PR).
tests/test_cli/test_invalid_command_py_3_13_invalidCommand_.txt	Updates invalid-command snapshot to reflect new global options in usage.
tests/test_cli/test_invalid_command_py_3_13___invalid_arg_.txt	Modifies invalid-arg snapshot file content (currently emptied in this PR).
tests/test_cli/test_invalid_command_py_3_12_invalidCommand_.txt	Updates invalid-command snapshot to reflect new global options in usage.
tests/test_cli/test_invalid_command_py_3_12___invalid_arg_.txt	Modifies invalid-arg snapshot file content (currently emptied in this PR).
tests/test_cli/test_invalid_command_py_3_11_invalidCommand_.txt	Updates invalid-command snapshot to reflect new global options in usage.
tests/test_cli/test_invalid_command_py_3_11___invalid_arg_.txt	Modifies invalid-arg snapshot file content (currently emptied in this PR).
tests/test_cli/test_invalid_command_py_3_10_invalidCommand_.txt	Updates invalid-command snapshot to reflect new global options in usage.
tests/test_cli/test_invalid_command_py_3_10___invalid_arg_.txt	Modifies invalid-arg snapshot file content (currently emptied in this PR).
tests/test_cli.py	Adds tests for global --version/-v and --report behavior/precedence.
tests/commands/test_version_command.py	Adds tests ensuring deprecated cz version --report/--commitizen emit warnings.
commitizen/commands/version.py	Emits deprecation warnings for cz version --report and cz version --commitizen.
commitizen/cli.py	Adds global args (--version/-v, --report) and implements top-level handling logic.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[bearomorphism]

Analysis: impact of subcommands.required = False

In case it's useful for review, here's a write-up of what this PR's "required": False change does and the regression analysis I ran locally.

What it changes

decli passes the value straight through to argparse as subparsers.required = False:

Setting	Behavior when no subcommand given
True (master)	argparse aborts with cz: error: the following arguments are required: {init,…,version} and exits before user code runs.
False (this PR)	argparse accepts the args silently. args.func simply isn't set; main() decides what to do.

The flip is necessary for cz --version / cz -v / cz --report to work without a subcommand.

Master vs PR — direct comparison

Verified locally on Windows / Python 3.13. Exit codes unchanged across the board.

Input	Master stderr	PR stderr	Exit
cz	help (unchanged)	help (unchanged)	0 = 0
cz --debug	argparse "the following arguments are required: …" + "Command is required"	"Command is required"	13 = 13
cz -n cz_jira	same as above	"Command is required"	13 = 13
cz --invalid-arg	argparse "the following arguments are required: …" (misleading — real issue is the unknown flag)	argparse "unrecognized arguments: --invalid-arg" (accurate)	13 = 13
cz invalidCommand	argparse "invalid choice"	argparse "invalid choice"	13 = 13
cz init, cz commit, …	normal	normal	unchanged
cz init --invalid-arg	InvalidCommandArgumentError	InvalidCommandArgumentError	18 = 18
cz --version / -v	n/a	prints installed version	new
cz --report	n/a	prints version/python/OS	new

Regression assessment

Functional: none.

• Every exit code is preserved, including the documented cz --debug → 13 contract in docs/exit_codes.md:25.
• Every previously valid invocation still works.
• Every previously invalid invocation still errors with the same exit code.
• grep -r "following arguments are required" . and grep -r "subcommands.*required" turn up nothing — no code, tests, or docs parse the old argparse string.

UX: minor cosmetic changes, neutral-to-positive.

• For "global-flag-only" invocations (cz --debug, cz -n NAME) without a subcommand, users no longer see the argparse usage block before the "Command is required" error. They still get a clear actionable error and can run cz (no args) for the full help. Very niche scenario.
• For typos like cz --invalid-arg, the error is now strictly more accurate ("unrecognized arguments: --invalid-arg" vs. the misleading "the following arguments are required").

Tests: test_no_argv, test_invalid_command[--invalid-arg], test_invalid_command[invalidCommand], test_cz_with_arg_but_without_command, test_cz_with_version_arg, test_cz_with_report_arg, test_unknown_args_raises, test_unknown_args_before_double_dash_raises all pass; the full python-check matrix (3.10–3.14 × ubuntu/macos/windows) is green.

Generated-by: GitHub Copilot following the guidelines