Addressed #218

Author: daveshanley

AGENTS.md

@@ -16,18 +16,23 @@ Public documentation:
 - local git history for a file in a repository
 - GitHub-hosted file history via file URL
 
-The public command surface is:
+The public comparison/report surface is:
 
 - `console`
 - `summary`
 - `report`
 - `markdown-report`
 - `html-report`
 
-All five commands use the current engine built on `doctor`, the open source Apache 2.0 library from pb33f:
+These five commands use the current engine built on `doctor`, the open source Apache 2.0 library from pb33f:
 
 - https://github.com/pb33f/doctor
 
+Utility commands:
+
+- `completion`
+- `version`
+
 ## Source Of Truth
 
 The code is the source of truth.
@@ -90,6 +95,7 @@ All `cmd/` implementation files use their canonical names (e.g., `cmd/summary.go
 ## Files That Matter Most
 
 - `cmd/root.go` — root Cobra command, CLI entry point, subcommand registration
+- `cmd/version.go` — prints the raw build version string
 - `cmd/common.go` — shared option flags and Lip Gloss styling for all doctor-based commands
 - `cmd/loaders.go` — loads specs from files, URLs, and git history; progress tracking and error aggregation
 - `cmd/engine.go` — wraps doctor changerator for API comparison; manages document resource cleanup and mutex-guarded breaking config

README.md

@@ -75,6 +75,13 @@ To run the interactive `console` through Docker, allocate a TTY with `-it`:
 docker run --rm -it -v $PWD:/work:rw pb33f/openapi-changes console . path/to/openapi.yaml
 ```
 
+## Verify the install
+
+Print the installed version:
+
+```bash
+openapi-changes version
+```
 
 ---
 
@@ -159,6 +166,7 @@ Full docs: https://pb33f.io/openapi-changes/
   - [`markdown-report`](https://pb33f.io/openapi-changes/markdown-report/)
   - [`html-report`](https://pb33f.io/openapi-changes/html-report/)
   - [`completion`](https://pb33f.io/openapi-changes/completion/)
+  - [`version`](https://pb33f.io/openapi-changes/version/)
 - [About openapi-changes](https://pb33f.io/openapi-changes/about/)
 
 ---
@@ -191,6 +199,7 @@ The current command surface is:
 - `markdown-report` for shareable markdown output
 - `html-report` for the interactive offline browser report
 - `completion` for shell completion scripts
+- `version` for raw build version output
 
 Run `openapi-changes --help` or `openapi-changes <command> --help` for the live CLI surface.
 

cmd/command_surface_test.go

@@ -15,4 +15,5 @@ func TestCommandSurface_UsesCanonicalNames(t *testing.T) {
 	assert.Equal(t, "markdown-report", GetMarkdownReportCommand().Use)
 	assert.Equal(t, "html-report", GetHTMLReportCommand().Use)
 	assert.Equal(t, "console", GetConsoleCommand().Use)
+	assert.Equal(t, "version", GetVersionCommand().Use)
 }

cmd/root.go

@@ -6,6 +6,7 @@ package cmd
 import (
 	"fmt"
 	"os"
+	"sort"
 
 	"github.com/spf13/cobra"
 )
@@ -20,9 +21,9 @@ var (
 		Use:          "openapi-changes",
 		Short:        "Detect and explore changes between OpenAPI / Swagger specifications.",
 		Long: `openapi-changes can detect every change found in an OpenAPI specification.
-it can compare between two files, or a single file, over time.
+	it can compare between two files, or a single file, over time.
 
-All commands use the current doctor-based engine.`,
+	The comparison and reporting commands use the current doctor-based engine.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts, _, err := readCommonFlags(cmd)
 			if err != nil {
@@ -32,7 +33,7 @@ All commands use the current doctor-based engine.`,
 
 			fmt.Println("Current commands")
 			fmt.Println()
-			for _, name := range []string{"console", "summary", "report", "markdown-report", "html-report"} {
+			for _, name := range visibleRootCommandNames(cmd) {
 				fmt.Printf("  > %s\n", name)
 			}
 			fmt.Println()
@@ -53,13 +54,26 @@ func Execute(version, commit, date string) {
 	}
 }
 
+func visibleRootCommandNames(root *cobra.Command) []string {
+	var names []string
+	for _, command := range root.Commands() {
+		if command == nil || command.Hidden || command.Name() == "help" {
+			continue
+		}
+		names = append(names, command.Name())
+	}
+	sort.Strings(names)
+	return names
+}
+
 func init() {
 	cobra.OnInitialize(initConfig)
 	rootCmd.AddCommand(GetConsoleCommand())
 	rootCmd.AddCommand(GetHTMLReportCommand())
 	rootCmd.AddCommand(GetMarkdownReportCommand())
 	rootCmd.AddCommand(GetReportCommand())
 	rootCmd.AddCommand(GetSummaryCommand())
+	rootCmd.AddCommand(GetVersionCommand())
 	rootCmd.PersistentFlags().BoolP("top", "t", false, "Only show latest changes (last git revision against HEAD)")
 	rootCmd.PersistentFlags().IntP("limit", "l", 5, "Limit history to number of revisions (default is 5)")
 	rootCmd.PersistentFlags().BoolP("global-revisions", "R", false, "Consider all revisions in limit, not just the ones for the file")

cmd/root_test.go

@@ -21,6 +21,8 @@ func TestRootCommand_ZeroArgsHonorsNoLogo(t *testing.T) {
 	})
 
 	assert.Contains(t, output, "Current commands")
+	assert.Contains(t, output, "completion")
+	assert.Contains(t, output, "version")
 	assert.NotContains(t, output, "https://pb33f.io/openapi-changes/")
 	assert.NotContains(t, output, "@@@@@@@")
 }

cmd/summary_test.go

@@ -427,6 +427,51 @@ func TestRenderSummary_ComposedSchemaTitleRemovalDoesNotMislabelAsAnyOf(t *testi
 	assert.NotContains(t, output, "anyOf")
 }
 
+func TestRenderSummary_RendersRemovedRequiredMemberName(t *testing.T) {
+	commit := mustMakeDoctorOnlyCommitFromSpecs(t, "required-label", `openapi: 3.0.3
+info:
+  title: Test API
+  version: "1.0"
+paths: {}
+components:
+  schemas:
+    ReminderRequest:
+      type: object
+      required:
+        - result
+      properties:
+        result:
+          type: string
+`, `openapi: 3.0.3
+info:
+  title: Test API
+  version: "1.0"
+paths: {}
+components:
+  schemas:
+    ReminderRequest:
+      type: object
+      properties:
+        result:
+          type: string
+`)
+
+	output, hasBreaking, hasChanges, err := renderSummary(
+		[]*model.Commit{commit},
+		nil,
+		true,
+		true,
+		true,
+		summaryStyles{},
+	)
+
+	require.NoError(t, err)
+	assert.True(t, hasChanges)
+	assert.True(t, hasBreaking)
+	assert.Contains(t, output, "Removed ReminderRequest required/result")
+	assert.Contains(t, output, "required/result (")
+}
+
 func TestLoadLeftRightCommits_ReturnsHTTPStatusErrors(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, "missing", http.StatusNotFound)

cmd/version.go

@@ -0,0 +1,27 @@
+// Copyright 2023-2026 Princess Beef Heavy Industries, LLC / Dave Shanley
+// SPDX-License-Identifier: Apache-2.0
+
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+)
+
+// GetVersionCommand returns the cobra command for printing the raw build version.
+func GetVersionCommand() *cobra.Command {
+	return &cobra.Command{
+		Use:   "version",
+		Short: "Print the openapi-changes version",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			version := Version
+			if version == "" {
+				version = "latest"
+			}
+			_, err := fmt.Fprintln(cmd.OutOrStdout(), version)
+			return err
+		},
+	}
+}

cmd/version_test.go

@@ -0,0 +1,26 @@
+// Copyright 2023-2026 Princess Beef Heavy Industries, LLC / Dave Shanley
+// SPDX-License-Identifier: Apache-2.0
+
+package cmd
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestVersionCommand_PrintsVersionOnly(t *testing.T) {
+	originalVersion := Version
+	Version = "v1.2.3-test"
+	t.Cleanup(func() {
+		Version = originalVersion
+	})
+
+	cmd := testRootCmd(GetVersionCommand())
+	output := captureStdout(t, func() {
+		require.NoError(t, cmd.Execute())
+	})
+
+	assert.Equal(t, "v1.2.3-test\n", output)
+}