feat: organize CLI help commands into logical groups

internal/cmd/audit.go

@@ -81,8 +81,9 @@ func (ao *auditOpts) AddFlags(cmd *cobra.Command) {
 func addAudit(parentCmd *cobra.Command) {
 	opts := &auditOpts{}
 	auditCmd := &cobra.Command{
-		Use:   "audit",
-		Short: "Audits the SLSA properties and controls of a repository",
+		Use:     "audit",
+		GroupID: "verification",
+		Short:   "Verifies multiple commits in the branch history",
 		Long: `Checks the revisions on the specified branch within the repository.
 
 Revisions 'pass' an audit if they have:

internal/cmd/auth.go

@@ -18,6 +18,7 @@ var colorHiRed = color.New(color.FgHiRed).SprintFunc()
 
 func addAuth(parentCmd *cobra.Command) {
 	authCmd := &cobra.Command{
+		GroupID:       "configuration",
 		Short:         "Manage user authentication",
 		Use:           "auth",
 		SilenceUsage:  false,

internal/cmd/checklevel.go

@@ -42,8 +42,9 @@ func addCheckLevel(parentCmd *cobra.Command) {
 	opts := checkLevelOpts{}
 
 	checklevelCmd := &cobra.Command{
-		Use:   "checklevel",
-		Short: "Determines the SLSA Source Level of the repo",
+		Use:     "checklevel",
+		GroupID: "assessment",
+		Short:   "Determines the SLSA Source Level of the repo",
 		Long: `Determines the SLSA Source Level of the repo.
 
 This is meant to be run within the corresponding GitHub Actions workflow.`,

internal/cmd/checklevelprov.go

@@ -51,8 +51,9 @@ func addCheckLevelProv(parentCmd *cobra.Command) {
 	opts := &checkLevelProvOpts{}
 
 	checklevelprovCmd := &cobra.Command{
-		Use:   "checklevelprov",
-		Short: "Checks the given commit against policy using & creating provenance",
+		Use:     "checklevelprov",
+		GroupID: "assessment",
+		Short:   "Checks the given commit against policy using & creating provenance",
 		PreRunE: func(cmd *cobra.Command, args []string) error {
 			if len(args) > 0 {
 				if err := opts.ParseLocator(args[0]); err != nil {

internal/cmd/checktag.go

@@ -50,8 +50,9 @@ func addCheckTag(parentCmd *cobra.Command) {
 	opts := &checkTagOptions{}
 
 	checktagCmd := &cobra.Command{
-		Use:   "checktag",
-		Short: "Checks to see if the tag operation should be allowed and issues a VSA",
+		Use:     "checktag",
+		GroupID: "assessment",
+		Short:   "Checks to see if the tag operation should be allowed and issues a VSA",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return doCheckTag(opts)
 		},

internal/cmd/createpolicy.go

@@ -30,8 +30,9 @@ func addCreatePolicy(parentCmd *cobra.Command) {
 	opts := createPolicyOptions{}
 
 	createpolicyCmd := &cobra.Command{
-		Use:   "createpolicy",
-		Short: "Creates a policy in a local copy of source-policies",
+		Use:     "createpolicy",
+		GroupID: "policy",
+		Short:   "Creates a policy in a local copy of source-policies",
 		Long: `Creates a SLSA source policy in a local copy of source-policies.
 
 		The created policy should then be sent as a PR to slsa-framework/source-policies.`,

internal/cmd/policy.go

@@ -39,7 +39,8 @@ func (pco *policyCreateOpts) AddFlags(cmd *cobra.Command) {
 
 func addPolicy(parentCmd *cobra.Command) {
 	policyCmd := &cobra.Command{
-		Short: "tools to work with source policies",
+		GroupID: "policy",
+		Short:   "tools to work with source policies",
 		Long: fmt.Sprintf(`
 %s %s
 

internal/cmd/prov.go

@@ -40,8 +40,9 @@ func (po *provOptions) AddFlags(cmd *cobra.Command) {
 func addProv(parentCmd *cobra.Command) {
 	opts := provOptions{}
 	provCmd := &cobra.Command{
-		Use:   "prov",
-		Short: "Creates provenance for the given commit, but does not check policy.",
+		Use:     "prov",
+		GroupID: "assessment",
+		Short:   "Creates provenance for the given commit, but does not check policy.",
 		PreRunE: func(cmd *cobra.Command, args []string) error {
 			if len(args) > 0 {
 				if err := opts.ParseLocator(args[0]); err != nil {

internal/cmd/root.go

@@ -44,17 +44,45 @@ controls and much more.
 
 	rootCmd.PersistentFlags().StringVar(&githubToken, "github_token", "", "the github token to use for auth")
 
-	addCheckLevel(rootCmd)
-	addCheckLevelProv(rootCmd)
+	// Define command groups for better organization
+	rootCmd.AddGroup(
+		&cobra.Group{
+			ID:    "verification",
+			Title: "Verification Commands:",
+		},
+		&cobra.Group{
+			ID:    "assessment",
+			Title: "Assessment Commands:",
+		},
+		&cobra.Group{
+			ID:    "policy",
+			Title: "Policy Commands:",
+		},
+		&cobra.Group{
+			ID:    "configuration",
+			Title: "Configuration & Setup Commands:",
+		},
+	)
+
+	// Verification commands
 	addVerifyCommit(rootCmd)
-	addStatus(rootCmd)
-	addSetup(rootCmd)
 	addAudit(rootCmd)
-	addProv(rootCmd)
+
+	// Assessment commands
+	addStatus(rootCmd)
+	addCheckLevel(rootCmd)
+	addCheckLevelProv(rootCmd)
 	addCheckTag(rootCmd)
+	addProv(rootCmd)
+
+	// Policy commands
+	addPolicy(rootCmd)
 	addCreatePolicy(rootCmd)
+
+	// Configuration & setup commands
+	addSetup(rootCmd)
 	addAuth(rootCmd)
-	addPolicy(rootCmd)
+
 	return rootCmd
 }
 

internal/cmd/setup.go

@@ -52,7 +52,8 @@ func (so *setupOpts) Validate() error {
 
 func addSetup(parentCmd *cobra.Command) {
 	setupCmd := &cobra.Command{
-		Short: "configure SLSA source features in a repository",
+		GroupID: "configuration",
+		Short:   "configure SLSA source features in a repository",
 		Long: fmt.Sprintf(`
 %s %s
 

internal/cmd/status.go

@@ -47,7 +47,8 @@ func (so *statusOptions) AddFlags(cmd *cobra.Command) {
 func addStatus(parentCmd *cobra.Command) {
 	opts := &statusOptions{}
 	statusCmd := &cobra.Command{
-		Short: "Check the SLSA Source status of a repo/branch",
+		GroupID: "assessment",
+		Short:   "Check the SLSA Source status of a repo/branch",
 		Long: `
 sourcetool status: Check the SLSA Source status of a repo/branch
 

internal/cmd/verifycommit.go

@@ -40,8 +40,9 @@ func (vco *verifyCommitOptions) AddFlags(cmd *cobra.Command) {
 func addVerifyCommit(cmd *cobra.Command) {
 	opts := verifyCommitOptions{}
 	verifyCommitCmd := &cobra.Command{
-		Use:   "verifycommit",
-		Short: "Verifies the specified commit is valid",
+		Use:     "verifycommit",
+		GroupID: "verification",
+		Short:   "Verifies the specified commit is valid",
 		PreRunE: func(cmd *cobra.Command, args []string) error {
 			if len(args) > 0 {
 				if err := opts.ParseLocator(args[0]); err != nil {