minor usage improvements

pkg/cmd/run/rerun/rerun.go

@@ -31,7 +31,7 @@ func NewCmdRerun(f *cmdutil.Factory, runF func(*RerunOptions) error) *cobra.Comm
 
 	cmd := &cobra.Command{
 		Use:   "rerun [<run-id>]",
-		Short: "Rerun a given run",
+		Short: "Rerun a failed run",
 		Args:  cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			// support `-R, --repo` override

pkg/cmd/run/view/view.go

@@ -91,20 +91,20 @@ func NewCmdView(f *cmdutil.Factory, runF func(*ViewOptions) error) *cobra.Comman
 		Short: "View a summary of a workflow run",
 		Args:  cobra.MaximumNArgs(1),
 		Example: heredoc.Doc(`
-		  # Interactively select a run to view, optionally drilling down to a job
-		  $ gh run view
-
-		  # View a specific run
-		  $ gh run view 12345
-
+			# Interactively select a run to view, optionally selecting a single job
+			$ gh run view
+			
+			# View a specific run
+			$ gh run view 12345
+			
 			# View a specific job within a run
 			$ gh run view --job 456789
-
+			
 			# View the full log for a specific job
 			$ gh run view --log --job 456789
-
-		  # Exit non-zero if a run failed
-		  $ gh run view 0451 --exit-status && echo "run pending or passed"
+			
+			# Exit non-zero if a run failed
+			$ gh run view 0451 --exit-status && echo "run pending or passed"
 		`),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			// support `-R, --repo` override

pkg/cmd/run/watch/watch.go

@@ -7,6 +7,7 @@ import (
 	"runtime"
 	"time"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/cli/cli/api"
 	"github.com/cli/cli/internal/ghrepo"
 	"github.com/cli/cli/pkg/cmd/run/shared"
@@ -40,8 +41,15 @@ func NewCmdWatch(f *cmdutil.Factory, runF func(*WatchOptions) error) *cobra.Comm
 	}
 
 	cmd := &cobra.Command{
-		Use:   "watch <run-selector>",
+		Use:   "watch <run-id>",
 		Short: "Watch a run until it completes, showing its progress",
+		Example: heredoc.Doc(`
+			# Watch a run until it's done
+			gh run watch
+
+			# Run some other command when the run is finished
+			gh run watch && notify-send "run is done!"
+		`),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			// support `-R, --repo` override
 			opts.BaseRepo = f.BaseRepo

pkg/cmd/workflow/disable/disable.go

@@ -31,6 +31,7 @@ func NewCmdDisable(f *cmdutil.Factory, runF func(*DisableOptions) error) *cobra.
 	cmd := &cobra.Command{
 		Use:   "disable [<workflow ID> | <workflow name>]",
 		Short: "Disable a workflow",
+		Long:  "Disable a workflow, preventing it from running or showing up when listing workflows.",
 		Args:  cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			// support `-R, --repo` override

pkg/cmd/workflow/enable/enable.go

@@ -31,6 +31,7 @@ func NewCmdEnable(f *cmdutil.Factory, runF func(*EnableOptions) error) *cobra.Co
 	cmd := &cobra.Command{
 		Use:   "enable [<workflow ID> | <workflow name>]",
 		Short: "Enable a workflow",
+		Long:  "Enable a workflow, allowing it to be run and show up when listing workflows.",
 		Args:  cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			// support `-R, --repo` override

pkg/cmd/workflow/list/list.go

@@ -34,7 +34,8 @@ func NewCmdList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Comman
 
 	cmd := &cobra.Command{
 		Use:   "list",
-		Short: "List GitHub Actions workflows",
+		Short: "List workflows",
+		Long:  "List workflow files, hiding disabled workflows by default.",
 		Args:  cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			// support `-R, --repo` override

pkg/cmd/workflow/run/run.go

@@ -47,7 +47,7 @@ func NewCmdRun(f *cmdutil.Factory, runF func(*RunOptions) error) *cobra.Command
 
 	cmd := &cobra.Command{
 		Use:   "run [<workflow-ID> | <workflow-name>]",
-		Short: "Create a dispatch event for a workflow, starting a run",
+		Short: "Run a workflow by creating a workflow_dispatch event",
 		Long: heredoc.Doc(`
 			Create a workflow_dispatch event for a given workflow.