feat: add --version flag to cli

[tianzhou]

What

Closes #542 — adds a --version flag to the pgschema CLI.

$ pgschema --version
1.12.3

Output is a single, machine-parseable line containing only the semantic version, so agentic tools and scripts can detect behavioral changes between releases.

Changes

• cmd/root.go: Set cobra's Version field (adds the --version flag to the root command) and a custom version template that prints just the version string.
• cmd/root_test.go: New test asserting pgschema --version output equals version.App() + "\n". Includes a flag reset since tests share the global RootCmd (pflag doesn't reset flag values between Parse calls, and cobra checks help before version).

Notes

• --version is a root-command flag: pgschema --version works, pgschema dump --version errors (standard cobra behavior).
• The version string comes from internal/version/VERSION (1.12.3); pgschema --help still shows the fuller Version: 1.12.3@<commit> <os/arch> <date> line.

Tests

• go test ./cmd/ -run TestRoot -v — all pass
• go vet ./cmd/ — clean
• Verified end-to-end: pgschema --version → 1.12.3; pgschema --debug --version → 1.12.3; pgschema dump --version → unknown flag: --version

[greptile-apps]

Greptile Summary

The PR adds a root-level --version flag that emits only the semantic version and documents the CLI's root options.

• Configures Cobra's version field and a machine-readable output template.
• Adds coverage for the version output.
• Adds a Global Options documentation page and navigation entry.

Confidence Score: 4/5

The PR appears safe to merge, with one non-blocking documentation correction needed for --debug flag placement.

The version behavior and test align, but the new documentation inaccurately says all global flags must precede a subcommand even though --debug is persistent.

Files Needing Attention: docs/cli/global.mdx

Important Files Changed

Filename	Overview
cmd/root.go	Correctly enables Cobra's root version flag and customizes its output to one version-only line.
cmd/root_test.go	Verifies exact version output while resetting the shared command's retained help flag.
docs/cli/global.mdx	Documents the new flag but inaccurately applies a before-subcommand restriction to persistent --debug.
docs/docs.json	Adds the new Global Options page to the CLI Reference navigation.

_{Reviews (1): Last reviewed commit: "feat: add --version flag to cli (#542)" | Re-trigger Greptile}

[greptile-apps]

Distinguish persistent flag placement

The blanket statement that global flags must precede the subcommand is inaccurate for --debug: it is registered through RootCmd.PersistentFlags() and is also accepted after a subcommand, such as pgschema plan --debug. Distinguishing this from the root-only --version flag would accurately document the supported CLI syntax.

Suggested change

	- Global flags must come before the subcommand name: `pgschema --version` (not `pgschema dump --version`).
	- The root-only `--version` flag must come before the subcommand name: `pgschema --version` (not `pgschema dump --version`). The persistent `--debug` flag can appear before or after a subcommand.

Knowledge Base Used: CLI Entrypoints

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[Copilot]

Pull request overview

Adds a root-level --version flag to the pgschema CLI (via Cobra) so scripts and agentic tools can reliably detect the installed semantic version, and documents the new global flag.

Changes:

• Set the root Cobra command’s Version and customize the version output template to print only the semantic version.
• Add a CLI test asserting pgschema --version prints version.App() followed by \n.
• Add documentation for root/global options and link it in the docs navigation.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
cmd/root.go	Enables Cobra’s --version flag on the root command and sets a minimal version output template.
cmd/root_test.go	Adds a test verifying --version output matches version.App() exactly.
docs/cli/global.mdx	Documents root/global CLI flags including --version.
docs/docs.json	Adds the new global options page to the CLI Reference navigation.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.