Generate CLI docs (#497)

* Generate CLI docs

* Fixes

Makefile

@@ -109,14 +109,16 @@ build:
 		-o bin/replicated \
 		cli/main.go
 
-.PHONY: docs
-docs:
-	go run ./docs/
-
-.PHONE: release
+.PHONY: release
 release:
 	dagger call release \
 		--one-password-service-account-production env:OP_SERVICE_ACCOUNT_PRODUCTION \
 		--version $(version) \
 		--github-token env:GITHUB_TOKEN \
 		--progress plain
+
+.PHONY: docs
+docs:
+	dagger --progress plain call generate-docs \
+		--github-token env:GITHUB_TOKEN \
+		--progress plain

cli/cmd/api_get.go

@@ -17,12 +17,8 @@ uses your local credentials and prints the response unmodified.
 
 We recommend piping the output to jq for easier reading.
 
-Pass the PATH of the request as the final argument. Do not include the host or version.
-
-Example:
-  replicated api get /v3/apps
-  
-`,
+Pass the PATH of the request as the final argument. Do not include the host or version.`,
+		Example:      `replicated api get /v3/apps`,
 		RunE:         r.apiGet,
 		SilenceUsage: true,
 		Args:         cobra.ExactArgs(1),

cli/cmd/api_patch.go

@@ -17,12 +17,8 @@ uses your local credentials and prints the response unmodified.
 
 We recommend piping the output to jq for easier reading.
 
-Pass the PATH of the request as the final argument. Do not include the host or version.
-
-Example:
-  replicated api patch /v3/customer/2VffY549paATVfHSGpJhjh6Ehpy -b '{"name":"Valuable Customer"}'
-  
-`,
+Pass the PATH of the request as the final argument. Do not include the host or version.`,
+		Example:      `replicated api patch /v3/customer/2VffY549paATVfHSGpJhjh6Ehpy -b '{"name":"Valuable Customer"}'`,
 		RunE:         r.apiPatch,
 		SilenceUsage: true,
 		Args:         cobra.ExactArgs(1),

cli/cmd/api_post.go

@@ -17,12 +17,8 @@ uses your local credentials and prints the response unmodified.
 
 We recommend piping the output to jq for easier reading.
 
-Pass the PATH of the request as the final argument. Do not include the host or version.
-
-Example:
-  replicated api post /v3/app/2EuFxKLDxKjPNk2jxMTmF6Vxvxu/channel -b '{"name":"marc-waz-here"}'
-  
-`,
+Pass the PATH of the request as the final argument. Do not include the host or version.`,
+		Example:      `replicated api post /v3/app/2EuFxKLDxKjPNk2jxMTmF6Vxvxu/channel -b '{"name":"marc-waz-here"}'`,
 		RunE:         r.apiPost,
 		SilenceUsage: true,
 		Args:         cobra.ExactArgs(1),

cli/cmd/api_put.go

@@ -17,12 +17,8 @@ uses your local credentials and prints the response unmodified.
 
 We recommend piping the output to jq for easier reading.
 
-Pass the PATH of the request as the final argument. Do not include the host or version.
-
-Example:
-  replicated api put /v3/app/2EuFxKLDxKjPNk2jxMTmF6Vxvxu/channel/2QLPm10JPkta7jO3Z3Mk4aXTPyZ -b '{"name":"marc-waz-here2"}'
-  
-`,
+Pass the PATH of the request as the final argument. Do not include the host or version.`,
+		Example:      `replicated api put /v3/app/2EuFxKLDxKjPNk2jxMTmF6Vxvxu/channel/2QLPm10JPkta7jO3Z3Mk4aXTPyZ -b '{"name":"marc-waz-here2"}'`,
 		RunE:         r.apiPut,
 		SilenceUsage: true,
 		Args:         cobra.ExactArgs(1),

cli/cmd/app.go

@@ -20,23 +20,23 @@ Use the various subcommands to:
 - View details of a specific application
 - Update application settings
 - Delete applications from your account`,
-		Example: `  # List all applications
-  replicated app ls
+		Example: `# List all applications
+replicated app ls
 
-  # Create a new application
-  replicated app create "My New App"
+# Create a new application
+replicated app create "My New App"
 
-  # View details of a specific application
-  replicated app inspect "My App Name"
+# View details of a specific application
+replicated app inspect "My App Name"
 
-  # Delete an application
-  replicated app delete "App to Remove"
+# Delete an application
+replicated app delete "App to Remove"
 
-  # Update an application's settings
-  replicated app update "My App" --channel stable
+# Update an application's settings
+replicated app update "My App" --channel stable
 
-  # List applications with custom output format
-  replicated app ls --output json`,
+# List applications with custom output format
+replicated app ls --output json`,
 	}
 	parent.AddCommand(cmd)
 

cli/cmd/app_create.go

@@ -29,14 +29,15 @@ and managed using the KOTS platform. When you create a new app, it will be set u
 with default configurations, which you can later customize.
 
 The NAME argument is required and will be used as the application's name.`,
-		Example: `  # Create a new app named "My App"
-  replicated app create "My App"
+		Example: `# Create a new app named "My App"
+replicated app create "My App"
 
-  # Create a new app and output the result in JSON format
-  replicated app create "Another App" --output json
+# Create a new app and output the result in JSON format
+replicated app create "Another App" --output json
 
-  # Create a new app with a specific name and view details in table format
-  replicated app create "Custom App" --output table`,
+# Create a new app with a specific name and view details in table format
+replicated app create "Custom App" --output table`,
+		Args: cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := context.Background()
 			if integrationTest != "" {

cli/cmd/app_ls.go

@@ -27,17 +27,17 @@ filter the results to show only applications that match the given name or ID.
 
 The output can be customized using the --output flag to display results in
 either table or JSON format.`,
-		Example: `  # List all applications
-  replicated app ls
+		Example: `# List all applications
+replicated app ls
 
-  # Search for a specific application by name
-  replicated app ls "My App"
+# Search for a specific application by name
+replicated app ls "My App"
 
-  # List applications and output in JSON format
-  replicated app ls --output json
+# List applications and output in JSON format
+replicated app ls --output json
 
-  # Search for an application and display results in table format
-  replicated app ls "App Name" --output table`,
+# Search for an application and display results in table format
+replicated app ls "App Name" --output table`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := context.Background()
 			if integrationTest != "" {

cli/cmd/app_rm.go

@@ -30,14 +30,14 @@ This command allows you to permanently remove an application from your account.
 Once deleted, the application and all associated data will be irretrievably lost.
 
 Use this command with caution as there is no way to undo this operation.`,
-		Example: `  # Delete a app named "My App"
-  replicated app delete "My App"
+		Example: `# Delete a app named "My App"
+replicated app delete "My App"
 
-  # Delete an app and skip the confirmation prompt
-  replicated app delete "Another App" --force
+# Delete an app and skip the confirmation prompt
+replicated app delete "Another App" --force
 
-  # Delete an app and output the result in JSON format
-  replicated app delete "Custom App" --output json`,
+# Delete an app and output the result in JSON format
+replicated app delete "Custom App" --output json`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := context.Background()
 			if integrationTest != "" {

cli/cmd/channel_create.go

@@ -8,12 +8,10 @@ import (
 
 func (r *runners) InitChannelCreate(parent *cobra.Command) {
 	cmd := &cobra.Command{
-		Use:   "create",
-		Short: "Create a new channel in your app",
-		Long: `Create a new channel in your app and print the channel on success.
-
-  Example:
-  replicated channel create --name Beta --description 'New features subject to change'`,
+		Use:     "create",
+		Short:   "Create a new channel in your app",
+		Long:    `Create a new channel in your app and print the channel on success.`,
+		Example: `replicated channel create --name Beta --description 'New features subject to change'`,
 	}
 	parent.AddCommand(cmd)
 

cli/cmd/channel_disable_semantic_versioning.go

@@ -9,12 +9,10 @@ import (
 
 func (r *runners) InitChannelDisableSemanticVersioning(parent *cobra.Command) {
 	cmd := &cobra.Command{
-		Use:   "disable-semantic-versioning CHANNEL_ID",
-		Short: "Disable semantic versioning for CHANNEL_ID",
-		Long: `Disable semantic versioning for the CHANNEL_ID.
-
- Example:
- replicated channel disable-semantic-versioning CHANNEL_ID`,
+		Use:     "disable-semantic-versioning CHANNEL_ID",
+		Short:   "Disable semantic versioning for CHANNEL_ID",
+		Long:    `Disable semantic versioning for the CHANNEL_ID.`,
+		Example: `replicated channel disable-semantic-versioning CHANNEL_ID`,
 	}
 	parent.AddCommand(cmd)
 	cmd.RunE = r.channelDisableSemanticVersioning

cli/cmd/channel_enable_semantic_versioning.go

@@ -9,12 +9,10 @@ import (
 
 func (r *runners) InitChannelEnableSemanticVersioning(parent *cobra.Command) {
 	cmd := &cobra.Command{
-		Use:   "enable-semantic-versioning CHANNEL_ID",
-		Short: "Enable semantic versioning for CHANNEL_ID",
-		Long: `Enable semantic versioning for the CHANNEL_ID.
-
- Example:
- replicated channel enable-semantic-versioning CHANNEL_ID`,
+		Use:     "enable-semantic-versioning CHANNEL_ID",
+		Short:   "Enable semantic versioning for CHANNEL_ID",
+		Long:    `Enable semantic versioning for the CHANNEL_ID.`,
+		Example: `replicated channel enable-semantic-versioning CHANNEL_ID`,
 	}
 	parent.AddCommand(cmd)
 	cmd.RunE = r.channelEnableSemanticVersioning

cli/cmd/cluster.go

@@ -17,17 +17,17 @@ func (r *runners) InitClusterCommand(parent *cobra.Command) *cobra.Command {
 		Use:   "cluster",
 		Short: "Manage test Kubernetes clusters.",
 		Long:  `The 'cluster' command allows you to manage and interact with Kubernetes clusters used for testing purposes. With this command, you can create, list, remove, and manage node groups within clusters, as well as retrieve information about available clusters.`,
-		Example: `  # Create a single-node EKS cluster
-  replicated cluster create --distribution eks --version 1.31
+		Example: `# Create a single-node EKS cluster
+replicated cluster create --distribution eks --version 1.31
 
-  # List all clusters
-  replicated cluster ls
+# List all clusters
+replicated cluster ls
 
-  # Remove a specific cluster by ID
-  replicated cluster rm <cluster-id>
+# Remove a specific cluster by ID
+replicated cluster rm <cluster-id>
 
-  # List all nodegroups in a specific cluster
-  replicated cluster nodegroup ls <cluster-id>`,
+# List all nodegroups in a specific cluster
+replicated cluster nodegroup ls <cluster-id>`,
 	}
 	parent.AddCommand(cmd)
 

cli/cmd/cluster_addon.go

@@ -16,17 +16,17 @@ func (r *runners) InitClusterAddon(parent *cobra.Command) *cobra.Command {
 		Long: `The 'cluster addon' command allows you to manage add-ons installed on a test cluster. Add-ons are additional components or services that can be installed and configured to enhance or extend the functionality of the cluster.
 
 You can use various subcommands to create, list, remove, or check the status of add-ons on a cluster. This command is useful for adding databases, object storage, monitoring, security, or other specialized tools to your cluster environment.`,
-		Example: `  # List all add-ons installed on a cluster
-  replicated cluster addon ls CLUSTER_ID
+		Example: `# List all add-ons installed on a cluster
+replicated cluster addon ls CLUSTER_ID
 
-  # Remove an add-on from a cluster
-  replicated cluster addon rm CLUSTER_ID --id ADDON_ID
+# Remove an add-on from a cluster
+replicated cluster addon rm CLUSTER_ID --id ADDON_ID
 
-  # Create an object store bucket add-on for a cluster
-  replicated cluster addon create object-store CLUSTER_ID --bucket-prefix mybucket
+# Create an object store bucket add-on for a cluster
+replicated cluster addon create object-store CLUSTER_ID --bucket-prefix mybucket
 
-  # List add-ons with JSON output
-  replicated cluster addon ls CLUSTER_ID --output json`,
+# List add-ons with JSON output
+replicated cluster addon ls CLUSTER_ID --output json`,
 	}
 	parent.AddCommand(cmd)
 

cli/cmd/cluster_addon_create.go

@@ -9,11 +9,11 @@ func (r *runners) InitClusterAddonCreate(parent *cobra.Command) *cobra.Command {
 		Use:   "create",
 		Short: "Create cluster add-ons.",
 		Long:  `Create new add-ons for a cluster. This command allows you to add functionality or services to a cluster by provisioning the required add-ons.`,
-		Example: `  # Create an object store bucket add-on for a cluster
-  replicated cluster addon create object-store CLUSTER_ID --bucket-prefix mybucket
+		Example: `# Create an object store bucket add-on for a cluster
+replicated cluster addon create object-store CLUSTER_ID --bucket-prefix mybucket
 
-  # Perform a dry run for creating an object store add-on
-  replicated cluster addon create object-store CLUSTER_ID --bucket-prefix mybucket --dry-run`,
+# Perform a dry run for creating an object store add-on
+replicated cluster addon create object-store CLUSTER_ID --bucket-prefix mybucket --dry-run`,
 	}
 	parent.AddCommand(cmd)
 

cli/cmd/cluster_addon_create_objectstore.go

@@ -17,25 +17,21 @@ func (r *runners) InitClusterAddonCreateObjectStore(parent *cobra.Command) *cobr
 	cmd := &cobra.Command{
 		Use:   "object-store CLUSTER_ID --bucket-prefix BUCKET_PREFIX",
 		Short: "Create an object store bucket for a cluster.",
-		Long: `Creates an object store bucket for a cluster, requiring a bucket name prefix. The bucket name will be auto-generated using the format "[BUCKET_PREFIX]-[ADDON_ID]-cmx". This feature provisions an object storage bucket that can be used for storage in your cluster environment.
+		Long:  `Creates an object store bucket for a cluster, requiring a bucket name prefix. The bucket name will be auto-generated using the format "[BUCKET_PREFIX]-[ADDON_ID]-cmx". This feature provisions an object storage bucket that can be used for storage in your cluster environment.`,
+		Example: `# Create an object store bucket with a specified prefix
+replicated cluster addon create object-store 05929b24 --bucket-prefix mybucket
 
-Examples:
-  # Create an object store bucket with a specified prefix
-  replicated cluster addon create object-store CLUSTER_ID --bucket-prefix mybucket
+# Create an object store bucket and wait for it to be ready (up to 5 minutes)
+replicated cluster addon create object-store 05929b24 --bucket-prefix mybucket --wait 5m
 
-  # Create an object store bucket and wait for it to be ready (up to 5 minutes)
-  replicated cluster addon create object-store CLUSTER_ID --bucket-prefix mybucket --wait 5m
+# Perform a dry run to validate inputs without creating the bucket
+replicated cluster addon create object-store 05929b24 --bucket-prefix mybucket --dry-run
 
-  # Perform a dry run to validate inputs without creating the bucket
-  replicated cluster addon create object-store CLUSTER_ID --bucket-prefix mybucket --dry-run
+# Create an object store bucket and output the result in JSON format
+replicated cluster addon create object-store 05929b24 --bucket-prefix mybucket --output json
 
-  # Create an object store bucket and output the result in JSON format
-  replicated cluster addon create object-store CLUSTER_ID --bucket-prefix mybucket --output json
-
-  # Create an object store bucket with a custom prefix and wait for 10 minutes
-  replicated cluster addon create object-store CLUSTER_ID --bucket-prefix custom-prefix --wait 10m`,
-		Example: `$ replicated cluster addon create object-store 05929b24 --bucket-prefix mybucket
-  05929b24    Object Store    pending         {"bucket_prefix":"mybucket"}`,
+# Create an object store bucket with a custom prefix and wait for 10 minutes
+replicated cluster addon create object-store 05929b24 --bucket-prefix custom-prefix --wait 10m`,
 		Args: cobra.ExactArgs(1),
 		RunE: func(_ *cobra.Command, cmdArgs []string) error {
 			r.args.clusterAddonCreateObjectStoreClusterID = cmdArgs[0]

cli/cmd/cluster_addon_ls.go

@@ -20,14 +20,14 @@ func (r *runners) InitClusterAddonLs(parent *cobra.Command) *cobra.Command {
 		Long: `The 'cluster addon ls' command allows you to list all add-ons for a specific cluster. This command provides a detailed overview of the add-ons currently installed on the cluster, including their status and any relevant configuration details.
 
 This can be useful for monitoring the health and configuration of add-ons or performing troubleshooting tasks.`,
-		Example: `  # List add-ons for a cluster with default table output
-  replicated cluster addon ls CLUSTER_ID
+		Example: `# List add-ons for a cluster with default table output
+replicated cluster addon ls CLUSTER_ID
 
-  # List add-ons for a cluster with JSON output
-  replicated cluster addon ls CLUSTER_ID --output json
+# List add-ons for a cluster with JSON output
+replicated cluster addon ls CLUSTER_ID --output json
 
-  # List add-ons for a cluster with wide table output
-  replicated cluster addon ls CLUSTER_ID --output wide`,
+# List add-ons for a cluster with wide table output
+replicated cluster addon ls CLUSTER_ID --output wide`,
 		Args: cobra.ExactArgs(1),
 		RunE: func(_ *cobra.Command, cmdArgs []string) error {
 			args.clusterID = cmdArgs[0]

cli/cmd/cluster_addon_rm.go

@@ -21,8 +21,8 @@ func (r *runners) InitClusterAddonRm(parent *cobra.Command) *cobra.Command {
 		Long: `The 'cluster addon rm' command allows you to remove a specific add-on from a cluster by specifying the cluster ID and the add-on ID.
 
 This command is useful when you want to deprovision an add-on that is no longer needed or when troubleshooting issues related to specific add-ons. The add-on will be removed immediately, and you will receive confirmation upon successful removal.`,
-		Example: `  # Remove an add-on with ID 'abc123' from cluster 'cluster456'
-  replicated cluster addon rm cluster456 --id abc123`,
+		Example: `# Remove an add-on with ID 'abc123' from cluster 'cluster456'
+replicated cluster addon rm cluster456 --id abc123`,
 		Args: cobra.ExactArgs(1),
 		RunE: func(_ *cobra.Command, cmdArgs []string) error {
 			args.clusterID = cmdArgs[0]