Improving CLI Help Documentation for Complex Options

[knqyf263]

Description:

Currently, Trivy displays CLI flag help information in a single-line format via --help. While this works for simple options, it becomes problematic for flags with multiple possible values or extensive configuration options.

Background

We've encountered several cases where the current help format is insufficient:

1. The --severity-src flag has numerous possible sources, making the help text lengthy and hard to read (feat: add --vuln-severity-source flag #8269 (comment))
2. Users need a way to view available analyzers

• feat: add an option to skip the files greater than a particular size #7190
• Add ability to disable specific analyzers #3987

These lists are frequently updated, so any solution should support automated generation.

Proposed Solutions

1. Help Topics

Similar to Go's help command, which provides both command and topic-based help:

$ go help
...
Additional help topics:

        buildconstraint build constraints
        buildmode       build modes
        c               calling between Go and C
        cache           build and test caching
        environment     environment variables
        filetype        file types
        go.mod          the go.mod file
        gopath          GOPATH environment variable
        goproxy         module proxy protocol
        importpath      import path syntax
        modules         modules, module versions, and more
        module-auth     module authentication using go.sum
        packages        package lists and patterns
        private         configuration for downloading non-public code
        testflag        testing flags
        testfunc        testing functions
        vcs             controlling version control with GOVCS

Use "go help <topic>" for more information about that topic.

The Go command also provides detailed help for specific options:

$ go help build | grep buildmode
        -buildmode mode
                build mode to use. See 'go help buildmode' for more.
                and -asan flags. Using a -buildmode option that requires non-default compile
                created with -buildmode=shared.

$ go help buildmode
The 'go build' and 'go install' commands take a -buildmode argument which
indicates which kind of object file is to be built. Currently supported values
are:

        -buildmode=archive
                Build the listed non-main packages into .a files. Packages named
                main are ignored.
...

We could implement a similar UI in Trivy:

--disable-analyzers strings    specify a list of license to disable. See 'trivy help analyzers' for the full list.

$ trivy help -h
Help provides help for any command in the application.
Simply type 'trivy help <path to command>' or 'trivy help <topic>' for full details.

Usage:
  trivy help [command] [flags]
  trivy help [command]

Available Topics:
  analyzers   List all analyzers

$ trivy help analyzers
alma
alpine
amazon
apk
apk-repo
azure-arm
bundler
...

Pros

• Scalable for extensive documentation
• Can be automatically generated
• Keeps main help concise

Cons

• Help information is not immediately visible

PoC

Details

diff --git a/pkg/commands/app.go b/pkg/commands/app.go
index 7bedce99f..3883c364d 100644
--- a/pkg/commands/app.go
+++ b/pkg/commands/app.go
@@ -7,6 +7,8 @@ import (
        "fmt"
        "io"
        "os"
+       "sort"
+       "strings"
        "time"

        "github.com/spf13/cobra"
@@ -121,6 +123,22 @@ func NewApp() *cobra.Command {
                })
        }

+       rootCmd.InitDefaultHelpCmd()
+       helpCmd, _, _ := rootCmd.Find([]string{"help"})
+       customHelpCmd := *helpCmd
+       customHelpCmd.AddCommand(&cobra.Command{
+               Use:   "analyzers",
+               Short: "List all analyzers",
+               Run: func(cmd *cobra.Command, args []string) {
+                       analyzers := xstrings.ToStringSlice(analyzer.AllAnalyzers.Items())
+                       sort.Strings(analyzers)
+                       fmt.Println(strings.Join(analyzers, "\n"))
+               },
+       })
+       rootCmd.SetHelpCommand(&customHelpCmd)
+       rootCmd.RemoveCommand(helpCmd)
+       rootCmd.AddCommand(&customHelpCmd)
+
        return rootCmd
 }

diff --git a/pkg/fanal/analyzer/const.go b/pkg/fanal/analyzer/const.go
index d59d7285c..64cc211b4 100644
--- a/pkg/fanal/analyzer/const.go
+++ b/pkg/fanal/analyzer/const.go
@@ -2,6 +2,8 @@ package analyzer

 import (
        "github.com/aquasecurity/trivy/pkg/iac/detection"
+       "github.com/aquasecurity/trivy/pkg/set"
+       "github.com/samber/lo"
 )

 type Type string
@@ -148,6 +150,14 @@ const (
 )

 var (
+       AllAnalyzers = set.New[Type](lo.Flatten([][]Type{
+               TypeOSes,
+               TypeLanguages,
+               TypeLockfiles,
+               TypeIndividualPkgs,
+               TypeConfigFiles,
+       })...)
+
        // TypeOSes has all OS-related analyzers
        TypeOSes = []Type{
                TypeOSRelease,

2. Single-line Format (Current Style)

Continue with the current format and include all options:

Pros:

• Consistent with current UI
• Simple implementation

Cons:

• Becomes unreadable with many options (There are 62 analyzers as of today)
• Poor user experience for complex flags

3. Multi-line Format

Format complex options across multiple lines, similar to AWS CLI:

$ aws ec2 describe-instances help
...

OPTIONS
       --instance-ids (list)
          The instance IDs.

          Default: Describes all your instances.

          (string)

          Syntax:

          "string" "string" ...

       --dry-run | --no-dry-run (boolean)
          Checks whether you have the required permissions for the operation,
          without actually making the request, and provides an error response.
          If you have the required permissions, the error response is
          DryRunOperation . Otherwise, it is UnauthorizedOperation .

       --filters (list)
          The filters.

          o affinity - The affinity setting for an instance running on a
            Dedicated Host (default | host ).

          o architecture - The instance architecture (i386 | x86_64 | arm64 ).

          o availability-zone - The Availability Zone of the instance.

          o block-device-mapping.attach-time - The attach time for an EBS
            volume mapped to the instance, for example,
            2022-09-15T17:15:20.000Z .
...

Pros:

• Better readability
• Can show detailed information
• All information available in --help

Cons:

• Requires cobra template modifications
• Help output becomes longer

4. Auto-generated Documentation

Extend our current documentation generation (mage docs:generate) to include these lists.

Pros:

• Comprehensive documentation
• Can be version-controlled
• Supports rich formatting

Cons:

• Requires users to check documentation

Questions for Discussion

1. Which approach best serves our users?
2. Should we combine multiple approaches? (e.g., help topics + documentation)
3. How can we ensure the solution scales as we add more options?
4. What's the maintenance overhead for each approach?

@aquasecurity/trivy I would discuss the best path forward for improving our CLI help documentation.

[DmitriyLewen]

My thoughts:

• point 2 - unreadable for these cases.
• point 3 - I don't like this method. We have a lot of flags, so if you need to find a special flag - it may not be convenient to find the desired flag.
• point 1. I think we can add only 2 commands (with a list of analyzers + a list of data sources) to cli help.
  The difficulties in supporting this will be minimal + new analyzers/dataSources will be added automatically.
  I think we will add flags with a large number of available values ​​will be quite rare - so there should be no problems with scaling.

But if we want to make additional command for each subcommand/flag - I would prefer to use point 4 and the created pages in docs + update the mage docs:generate function, and add a link to the documentation to the help.