Restructure CLI: consolidate commands and add colorized help

- Move search/show under catalog subcommand (apx catalog search, apx catalog show)
- Merge link into sync — apx sync now handles Go and Python overlays
- Flatten semver suggest to apx semver
- Add colorized help output with ANSI-aware formatting
- Add Unlinker interface and ClearWorkFile for sync --clean
- Hide fetch command, improve CI/color detection in internal/ui
- Update docs, tests, and testscripts to match

Author: daniel-garcia

Makefile

@@ -26,10 +26,24 @@ GORELEASER_VERSION := v2.6.1
 
 ## help: Show this help message
 help:
-	@echo "Usage: make [target]"
-	@echo ""
-	@echo "Available targets:"
-	@awk '/^##/ { print "  " $$0 }' $(MAKEFILE_LIST) | sed 's/##//' | sort
+	@if [ -z "$$CI$$GITHUB_ACTIONS$$JENKINS_HOME$$NO_COLOR" ]; then \
+		BOLD="\033[1m"; CYAN="\033[36m"; RESET="\033[0m"; \
+	else \
+		BOLD=""; CYAN=""; RESET=""; \
+	fi; \
+	printf "$${BOLD}Usage:$${RESET} make [target]\n"; \
+	printf "\n"; \
+	printf "$${BOLD}Available targets:$${RESET}\n"; \
+	awk -v cyan="$${CYAN}" -v reset="$${RESET}" \
+		'/^## / { \
+			line = substr($$0, 4); \
+			colon = index(line, ":"); \
+			if (colon > 0) { \
+				target = substr(line, 1, colon-1); \
+				desc = substr(line, colon+2); \
+				printf "  %s%-22s%s %s\n", cyan, target, reset, desc; \
+			} \
+		}' $(MAKEFILE_LIST) | sort
 
 ## build: Build the binary
 build:

README.md

@@ -454,7 +454,7 @@ jobs:
           fetch-depth: 0
 
       - name: Install APX
-        uses: infobloxopen/apx@v1
+        uses: infobloxopen/apx@main
 
       - name: Lint Schemas
         run: apx lint internal/apis
@@ -473,7 +473,7 @@ jobs:
           token: ${{ secrets.CANONICAL_REPO_TOKEN }}
 
       - name: Install APX
-        uses: infobloxopen/apx@v1
+        uses: infobloxopen/apx@main
 
       - name: Release to Canonical Repo
         run: |

cmd/apx/commands/breaking.go

@@ -18,8 +18,7 @@ func newBreakingCmd() *cobra.Command {
 		Args:  cobra.MaximumNArgs(1),
 		RunE:  breakingAction,
 	}
-	cmd.Flags().String("against", "", "git reference or path to compare against")
-	_ = cmd.MarkFlagRequired("against")
+	cmd.Flags().String("against", "", "git reference or path to compare against (required)")
 	cmd.Flags().StringP("format", "f", "", "Schema format (proto, openapi, avro, jsonschema, parquet)")
 	return cmd
 }
@@ -31,6 +30,9 @@ func breakingAction(cmd *cobra.Command, args []string) error {
 	}
 
 	against, _ := cmd.Flags().GetString("against")
+	if against == "" {
+		return fmt.Errorf("--against is required\n\nUsage: apx breaking [path] --against <git-ref>\n\nExamples:\n  apx breaking --against HEAD^\n  apx breaking --against origin/main")
+	}
 
 	// Try to resolve API ID (e.g. proto/payments/ledger/v1) to a path.
 	// Falls back to treating the argument as a filesystem path.

cmd/apx/commands/catalog.go

@@ -14,8 +14,10 @@ import (
 func newCatalogCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "catalog",
-		Short: "Catalog operations",
+		Short: "Browse and search the API catalog",
 	}
+	cmd.AddCommand(newCatalogSearchCmd())
+	cmd.AddCommand(newCatalogShowCmd())
 	cmd.AddCommand(newCatalogGenerateCmd())
 	cmd.AddCommand(newCatalogSiteCmd())
 	return cmd

cmd/apx/commands/doc_parity_test.go

@@ -160,23 +160,23 @@ func TestDocParity_ConsumerCommands(t *testing.T) {
 	root := NewRootCmd("test")
 
 	tests := []struct {
-		name        string
-		commandName string
-		section     string
+		name    string
+		args    []string
+		section string
 	}{
-		{"search command", "search", "6 - Discover APIs"},
-		{"add command", "add", "6 - Add Dependencies"},
-		{"gen command", "gen", "6 - Generate Client Code"},
-		{"sync command", "sync", "6 - Generate Client Code"},
-		{"unlink command", "unlink", "6 - Switch to Published Module"},
+		{"search command", []string{"catalog", "search"}, "6 - Discover APIs"},
+		{"add command", []string{"add"}, "6 - Add Dependencies"},
+		{"gen command", []string{"gen"}, "6 - Generate Client Code"},
+		{"sync command", []string{"sync"}, "6 - Generate Client Code"},
+		{"unlink command", []string{"unlink"}, "6 - Switch to Published Module"},
 	}
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			cmd, _, err := root.Find([]string{tt.commandName})
+			cmd, _, err := root.Find(tt.args)
 			if err != nil || cmd.Use == "apx" {
 				t.Fatalf("Doc parity failure: 'apx %s' command not found (documented in quickstart.md section %s)",
-					tt.commandName, tt.section)
+					strings.Join(tt.args, " "), tt.section)
 			}
 		})
 	}
@@ -233,14 +233,14 @@ func TestDocParity_AllCommandsExist(t *testing.T) {
 	commands := [][]string{
 		{"init"}, {"init", "canonical"}, {"init", "app"},
 		{"lint"}, {"breaking"},
-		{"semver"}, {"semver", "suggest"},
+		{"semver"},
 		{"gen"}, {"policy"}, {"policy", "check"},
 		{"catalog"},
-		{"release"}, {"search"}, {"add"},
+		{"release"}, {"add"},
 		{"sync"}, {"unlink"}, {"update"}, {"upgrade"},
 		{"config"}, {"config", "init"}, {"config", "validate"},
 		{"fetch"},
-		{"show"},
+		{"catalog", "search"}, {"catalog", "show"},
 		{"inspect"}, {"inspect", "identity"}, {"inspect", "release"},
 		{"explain"}, {"explain", "go-path"},
 		// Note: "completion" is Cobra's built-in command, added lazily at Execute() time;
@@ -268,9 +268,9 @@ func TestDocParity_AllFlagsExist(t *testing.T) {
 	root := NewRootCmd("test")
 	documentedFlags := []flagSpec{
 		{[]string{"breaking"}, []string{"against", "format"}},
-		{[]string{"semver", "suggest"}, []string{"against"}},
+		{[]string{"semver"}, []string{"against"}},
 		{[]string{"gen"}, []string{"out", "clean", "manifest"}},
-		{[]string{"search"}, []string{"format", "catalog", "lifecycle", "domain", "api-line", "origin", "tag"}},
+		{[]string{"catalog", "search"}, []string{"format", "catalog", "lifecycle", "domain", "api-line", "origin", "tag"}},
 		{[]string{"sync"}, []string{"clean", "dry-run"}},
 		{[]string{"fetch"}, []string{"config", "output", "verify"}},
 		{[]string{"lint"}, []string{"format"}},
@@ -313,14 +313,14 @@ func TestDocParity_RequiredFlags(t *testing.T) {
 		}
 	})
 
-	t.Run("semver suggest requires --against", func(t *testing.T) {
+	t.Run("semver requires --against", func(t *testing.T) {
 		root := NewRootCmd("test")
-		root.SetArgs([]string{"semver", "suggest", "."})
+		root.SetArgs([]string{"semver", "."})
 		var errBuf strings.Builder
 		root.SetErr(&errBuf)
 		err := root.Execute()
 		if err == nil {
-			t.Error("Doc parity failure: 'apx semver suggest .' should fail when --against is not provided")
+			t.Error("Doc parity failure: 'apx semver .' should fail when --against is not provided")
 		}
 	})
 }
@@ -441,7 +441,7 @@ func TestDocParity_CommandExamples(t *testing.T) {
 		{"breaking", []string{"apx", "breaking"}},
 		{"gen go", []string{"apx", "gen", "go"}},
 		{"sync", []string{"apx", "sync"}},
-		{"search", []string{"apx", "search", "payments"}},
+		{"catalog search", []string{"apx", "catalog", "search", "payments"}},
 		{"add", []string{"apx", "add", "proto/payments/ledger/v1@v1.2.3"}},
 		{"unlink", []string{"apx", "unlink", "proto/payments/ledger/v1"}},
 	}

cmd/apx/commands/fetch.go

@@ -11,9 +11,10 @@ import (
 
 func newFetchCmd() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "fetch",
-		Short: "Download and cache toolchain dependencies for offline use",
-		RunE:  fetchAction,
+		Use:    "fetch",
+		Short:  "Download and cache toolchain dependencies for offline use",
+		Hidden: true,
+		RunE:   fetchAction,
 	}
 	cmd.Flags().StringP("config", "c", "apx.yaml", "Path to configuration file")
 	cmd.Flags().String("output", ".apx-tools", "Output directory for toolchain bundles")

cmd/apx/commands/help.go

@@ -0,0 +1,123 @@
+package commands
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/fatih/color"
+	"github.com/infobloxopen/apx/internal/ui"
+	"github.com/spf13/cobra"
+)
+
+// setColorizedHelp installs a colorized help function on cmd.
+// Cobra walks the parent chain when looking up HelpFunc, so every subcommand
+// inherits this automatically without needing per-command wiring.
+func setColorizedHelp(cmd *cobra.Command) {
+	cmd.SetHelpFunc(colorHelpFunc)
+}
+
+func colorHelpFunc(cmd *cobra.Command, _ []string) {
+	// Honor --no-color even when PersistentPreRunE hasn't run yet
+	// (e.g. `apx --no-color --help` triggers help before the pre-run hook).
+	if noColor, err := cmd.Root().PersistentFlags().GetBool("no-color"); err == nil && noColor {
+		ui.SetColorEnabled(false)
+	}
+
+	out := cmd.OutOrStdout()
+	bold := color.New(color.Bold)
+	cyan := color.New(color.FgCyan)
+
+	// Description — long preferred, fall back to short.
+	desc := cmd.Long
+	if desc == "" {
+		desc = cmd.Short
+	}
+	if desc != "" {
+		fmt.Fprintln(out, strings.TrimRight(desc, " \n"))
+		fmt.Fprintln(out)
+	}
+
+	// Usage line
+	fmt.Fprintf(out, "%s\n", bold.Sprint("Usage:"))
+	if cmd.Runnable() {
+		fmt.Fprintf(out, "  %s\n", cmd.UseLine())
+	}
+	if cmd.HasAvailableSubCommands() {
+		fmt.Fprintf(out, "  %s [command]\n", cmd.CommandPath())
+	}
+
+	// Aliases
+	if len(cmd.Aliases) > 0 {
+		fmt.Fprintln(out)
+		fmt.Fprintf(out, "%s\n", bold.Sprint("Aliases:"))
+		fmt.Fprintf(out, "  %s\n", cmd.NameAndAliases())
+	}
+
+	// Examples
+	if cmd.HasExample() {
+		fmt.Fprintln(out)
+		fmt.Fprintf(out, "%s\n", bold.Sprint("Examples:"))
+		fmt.Fprintln(out, cmd.Example)
+	}
+
+	// Available Commands
+	if cmd.HasAvailableSubCommands() {
+		fmt.Fprintln(out)
+		fmt.Fprintf(out, "%s\n", bold.Sprint("Available Commands:"))
+		pad := subcommandPadding(cmd)
+		for _, sub := range cmd.Commands() {
+			if sub.IsAvailableCommand() || sub.Name() == "help" {
+				// Compute spacing manually — cyan.Sprint embeds ANSI codes that
+				// would throw off %-*s width calculation.
+				spacing := strings.Repeat(" ", max(0, pad-len(sub.Name())))
+				fmt.Fprintf(out, "  %s%s  %s\n", cyan.Sprint(sub.Name()), spacing, sub.Short)
+			}
+		}
+	}
+
+	// Local Flags
+	if cmd.HasAvailableLocalFlags() {
+		fmt.Fprintln(out)
+		fmt.Fprintf(out, "%s\n", bold.Sprint("Flags:"))
+		fmt.Fprint(out, strings.TrimRight(cmd.LocalFlags().FlagUsages(), "\n"))
+		fmt.Fprintln(out)
+	}
+
+	// Global / Inherited Flags
+	if cmd.HasAvailableInheritedFlags() {
+		fmt.Fprintln(out)
+		fmt.Fprintf(out, "%s\n", bold.Sprint("Global Flags:"))
+		fmt.Fprint(out, strings.TrimRight(cmd.InheritedFlags().FlagUsages(), "\n"))
+		fmt.Fprintln(out)
+	}
+
+	// Additional help topics (commands marked as help topics, not runnable)
+	if cmd.HasHelpSubCommands() {
+		fmt.Fprintln(out)
+		fmt.Fprintf(out, "%s\n", bold.Sprint("Additional help topics:"))
+		pad := subcommandPadding(cmd)
+		for _, sub := range cmd.Commands() {
+			if sub.IsAdditionalHelpTopicCommand() {
+				fmt.Fprintf(out, "  %-*s  %s\n", pad, sub.Name(), sub.Short)
+			}
+		}
+	}
+
+	// Footer
+	if cmd.HasAvailableSubCommands() {
+		fmt.Fprintln(out)
+		fmt.Fprintf(out, "Use \"%s [command] --help\" for more information about a command.\n", cmd.CommandPath())
+	}
+}
+
+// subcommandPadding returns the column width needed to align descriptions
+// in the Available Commands block.
+func subcommandPadding(cmd *cobra.Command) int {
+	maxLen := 11 // Cobra's default minimum
+	for _, sub := range cmd.Commands() {
+		if (sub.IsAvailableCommand() || sub.IsAdditionalHelpTopicCommand()) && len(sub.Name()) > maxLen {
+			maxLen = len(sub.Name())
+		}
+	}
+	return maxLen
+}