cli · andyfeller · Feb 27, 2025 · Feb 27, 2025 · Feb 27, 2025
@@ -51,7 +51,7 @@ func NewCmdSet(f *cmdutil.Factory, runF func(*SetOptions) error) *cobra.Command
 			invoked. This allows for chaining multiple commands via piping and redirection.
 		`, "`"),
 		Example: heredoc.Doc(`
-			# note: Command Prompt on Windows requires using double quotes for arguments
+			# Note: Command Prompt on Windows requires using double quotes for arguments
 			$ gh alias set pv 'pr view'
 			$ gh pv -w 123  #=> gh pr view -w 123
 

@@ -125,39 +125,39 @@ func NewCmdApi(f *cmdutil.Factory, runF func(*ApiOptions) error) *cobra.Command
 			into an outer JSON array.
 		`, "`"),
 		Example: heredoc.Doc(`
-			# list releases in the current repository
+			# List releases in the current repository
 			$ gh api repos/{owner}/{repo}/releases
 
-			# post an issue comment
+			# Post an issue comment
 			$ gh api repos/{owner}/{repo}/issues/123/comments -f body='Hi from CLI'
 
-			# post nested parameter read from a file
+			# Post nested parameter read from a file
 			$ gh api gists -F 'files[myfile.txt][content][email protected]'
 
-			# add parameters to a GET request
+			# Add parameters to a GET request
 			$ gh api -X GET search/issues -f q='repo:cli/cli is:open remote'
 
-			# set a custom HTTP header
+			# Set a custom HTTP header
 			$ gh api -H 'Accept: application/vnd.github.v3.raw+json' ...
 
-			# opt into GitHub API previews
+			# Opt into GitHub API previews
 			$ gh api --preview baptiste,nebula ...
 
-			# print only specific fields from the response
+			# Print only specific fields from the response
 			$ gh api repos/{owner}/{repo}/issues --jq '.[].title'
 
-			# use a template for the output
+			# Use a template for the output
 			$ gh api repos/{owner}/{repo}/issues --template \
 			  '{{range .}}{{.title}} ({{.labels | pluck "name" | join ", " | color "yellow"}}){{"\n"}}{{end}}'
 
-			# update allowed values of the "environment" custom property in a deeply nested array
-			gh api -X PATCH /orgs/{org}/properties/schema \
+			# Update allowed values of the "environment" custom property in a deeply nested array
+			$ gh api -X PATCH /orgs/{org}/properties/schema \
 			   -F 'properties[][property_name]=environment' \
 			   -F 'properties[][default_value]=production' \
 			   -F 'properties[][allowed_values][]=staging' \
 			   -F 'properties[][allowed_values][]=production'
 
-			# list releases with GraphQL
+			# List releases with GraphQL
 			$ gh api graphql -F owner='{owner}' -F name='{repo}' -f query='
 			  query($name: String!, $owner: String!) {
 			    repository(owner: $owner, name: $name) {
@@ -168,7 +168,7 @@ func NewCmdApi(f *cmdutil.Factory, runF func(*ApiOptions) error) *cobra.Command
 			  }
 			'
 
-			# list all repositories for a user
+			# List all repositories for a user
 			$ gh api graphql --paginate -f query='
 			  query($endCursor: String) {
 			    viewer {
@@ -183,7 +183,7 @@ func NewCmdApi(f *cmdutil.Factory, runF func(*ApiOptions) error) *cobra.Command
 			  }
 			'
 
-			# get the percentage of forks for the current user
+			# Get the percentage of forks for the current user
 			$ gh api graphql --paginate --slurp -f query='
 			  query($endCursor: String) {
 			    viewer {

@@ -47,7 +47,7 @@ func NewInspectCmd(f *cmdutil.Factory, runF func(*Options) error) *cobra.Command
 			timestamps, and if the included signatures match the provided public key.
 
 			This command cannot be used to verify a bundle. To verify a bundle, see the
-		 %[1]sgh at verify%[1]s command.
+			%[1]sgh at verify%[1]s command.
 
 			By default, this command prints a condensed table. To see full results, provide the
 			%[1]s--format=json%[1]s flag.

@@ -57,7 +57,7 @@ func NewTrustedRootCmd(f *cmdutil.Factory, runF func(*Options) error) *cobra.Com
 		`, "`"),
 		Example: heredoc.Doc(`
 			# Get a trusted_root.jsonl for both Sigstore Public Good and GitHub's instance
-			gh attestation trusted-root
+			$ gh attestation trusted-root
 		`),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if opts.Hostname == "" {

@@ -88,7 +88,8 @@ func NewCmdLogin(f *cmdutil.Factory, runF func(*LoginOptions) error) *cobra.Comm
 			prompting to create and upload a new key if one is not found. This can be skipped with
 			%[1]s--skip-ssh-key%[1]s flag.
 
-			For more information on OAuth scopes, <https://docs.github.com/en/developers/apps/building-oauth-apps/scopes-for-oauth-apps/>.
+			For more information on OAuth scopes, see
+			<https://docs.github.com/en/developers/apps/building-oauth-apps/scopes-for-oauth-apps/>.
 		`, "`"),
 		Example: heredoc.Doc(`
 			# Start interactive setup

@@ -74,20 +74,21 @@ func NewCmdRefresh(f *cmdutil.Factory, runF func(*RefreshOptions) error) *cobra.
 			inactive account, you will have to use %[1]sgh auth switch%[1]s to that account first before using
 			this command, and then switch back when you are done.
 
-			For more information on OAuth scopes, <https://docs.github.com/en/developers/apps/building-oauth-apps/scopes-for-oauth-apps/>.
+			For more information on OAuth scopes, see
+			<https://docs.github.com/en/developers/apps/building-oauth-apps/scopes-for-oauth-apps/>.
 		`, "`"),
 		Example: heredoc.Doc(`
+			# Open a browser to add write:org and read:public_key scopes
 			$ gh auth refresh --scopes write:org,read:public_key
-			# => open a browser to add write:org and read:public_key scopes
 
+			# Open a browser to ensure your authentication credentials have the correct minimum scopes
 			$ gh auth refresh
-			# => open a browser to ensure your authentication credentials have the correct minimum scopes
 
+			# Open a browser to idempotently remove the delete_repo scope
 			$ gh auth refresh --remove-scopes delete_repo
-			# => open a browser to idempotently remove the delete_repo scope
 
+			# Open a browser to re-authenticate with the default minimum scopes
 			$ gh auth refresh --reset-scopes
-			# => open a browser to re-authenticate with the default minimum scopes
 		`),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.Interactive = opts.IO.CanPrompt()

@@ -72,29 +72,29 @@ func NewCmdBrowse(f *cmdutil.Factory, runF func(*BrowseOptions) error) *cobra.Co
 		Use:  "browse [<number> | <path> | <commit-sha>]",
 		Args: cobra.MaximumNArgs(1),
 		Example: heredoc.Doc(`
+			# Open the home page of the current repository
 			$ gh browse
-			#=> Open the home page of the current repository
 
+			# Open the script directory of the current repository
 			$ gh browse script/
-			#=> Open the script directory of the current repository
 
+			# Open issue or pull request 217
 			$ gh browse 217
-			#=> Open issue or pull request 217
 
+			# Open commit page
 			$ gh browse 77507cd94ccafcf568f8560cfecde965fcfa63
-			#=> Open commit page
 
+			# Open repository settings
 			$ gh browse --settings
-			#=> Open repository settings
 
+			# Open main.go at line 312
 			$ gh browse main.go:312
-			#=> Open main.go at line 312
 
+			# Open main.go with the repository at head of bug-fix branch
 			$ gh browse main.go --branch bug-fix
-			#=> Open main.go with the repository at head of bug-fix branch
 
+			# Open main.go with the repository at commit 775007cd
 			$ gh browse main.go --commit=77507cd94ccafcf568f8560cfecde965fcfa63
-			#=> Open main.go with the repository at commit 775007cd
 		`),
 		Annotations: map[string]string{
 			"help:arguments": heredoc.Doc(`

@@ -41,23 +41,23 @@ func NewCmdList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Comman
 		Use:   "list",
 		Short: "List GitHub Actions caches",
 		Example: heredoc.Doc(`
-		# List caches for current repository
-		$ gh cache list
+			# List caches for current repository
+			$ gh cache list
 
-		# List caches for specific repository
-		$ gh cache list --repo cli/cli
+			# List caches for specific repository
+			$ gh cache list --repo cli/cli
 
-		# List caches sorted by least recently accessed
-		$ gh cache list --sort last_accessed_at --order asc
+			# List caches sorted by least recently accessed
+			$ gh cache list --sort last_accessed_at --order asc
 
-		# List caches that have keys matching a prefix (or that match exactly)
-		$ gh cache list --key key-prefix
+			# List caches that have keys matching a prefix (or that match exactly)
+			$ gh cache list --key key-prefix
 
-		# To list caches for a specific branch, replace <branch-name> with the actual branch name
-		$ gh cache list --ref refs/heads/<branch-name>
+			# List caches for a specific branch, replace <branch-name> with the actual branch name
+			$ gh cache list --ref refs/heads/<branch-name>
 
-		# To list caches for a specific pull request, replace <pr-number> with the actual pull request number
-		$ gh cache list --ref refs/pull/<pr-number>/merge
+			# List caches for a specific pull request, replace <pr-number> with the actual pull request number
+			$ gh cache list --ref refs/pull/<pr-number>/merge
 		`),
 		Aliases: []string{"ls"},
 		Args:    cobra.NoArgs,

@@ -10,6 +10,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/cli/cli/v2/internal/codespaces"
 	"github.com/cli/cli/v2/internal/codespaces/api"
 	"github.com/cli/cli/v2/internal/codespaces/portforwarder"
@@ -217,10 +218,12 @@ func getDevContainer(ctx context.Context, apiClient apiClient, codespace *api.Co
 
 func newPortsVisibilityCmd(app *App, selector *CodespaceSelector) *cobra.Command {
 	return &cobra.Command{
-		Use:     "visibility <port>:{public|private|org}...",
-		Short:   "Change the visibility of the forwarded port",
-		Example: "gh codespace ports visibility 80:org 3000:private 8000:public",
-		Args:    cobra.MinimumNArgs(1),
+		Use:   "visibility <port>:{public|private|org}...",
+		Short: "Change the visibility of the forwarded port",
+		Example: heredoc.Doc(`
+			$ gh codespace ports visibility 80:org 3000:private 8000:public
+		`),
+		Args: cobra.MinimumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return app.UpdatePortVisibility(cmd.Context(), selector, args)
 		},

@@ -29,16 +29,16 @@ func newViewCmd(app *App) *cobra.Command {
 		Use:   "view",
 		Short: "View details about a codespace",
 		Example: heredoc.Doc(`
-			# select a codespace from a list of all codespaces you own
+			# Select a codespace from a list of all codespaces you own
 			$ gh cs view
 
-			# view the details of a specific codespace
+			# View the details of a specific codespace
 			$ gh cs view -c codespace-name-12345
 
-			# view the list of all available fields for a codespace
+			# View the list of all available fields for a codespace
 			$ gh cs view --json
 
-			# view specific fields for a codespace
+			# View specific fields for a codespace
 			$ gh cs view --json displayName,machineDisplayName,state
 		`),
 		Args: noArgsConstraint,

@@ -29,7 +29,6 @@ func NewCmdConfigGet(f *cmdutil.Factory, runF func(*GetOptions) error) *cobra.Co
 		Short: "Print the value of a given configuration key",
 		Example: heredoc.Doc(`
 			$ gh config get git_protocol
-			https
 		`),
 		Args: cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {

@@ -542,7 +542,7 @@ func NewCmdExtension(f *cmdutil.Factory) *cobra.Command {
 				of the extension.
 			`, "`"),
 			Example: heredoc.Doc(`
-				# execute a label extension instead of the core gh label command
+				# Execute a label extension instead of the core gh label command
 				$ gh extension exec label
 			`),
 			Args:               cobra.MinimumNArgs(1),
@@ -573,16 +573,16 @@ func NewCmdExtension(f *cmdutil.Factory) *cobra.Command {
 				Short: "Create a new extension",
 				Example: heredoc.Doc(`
 					# Use interactively
-					gh extension create
+					$ gh extension create
 
 					# Create a script-based extension
-					gh extension create foobar
+					$ gh extension create foobar
 
 					# Create a Go extension
-					gh extension create --precompiled=go foobar
+					$ gh extension create --precompiled=go foobar
 
 					# Create a non-Go precompiled extension
-					gh extension create --precompiled=other foobar
+					$ gh extension create --precompiled=other foobar
 				`),
 				Args: cobra.MaximumNArgs(1),
 				RunE: func(cmd *cobra.Command, args []string) error {

@@ -59,19 +59,19 @@ func NewCmdCreate(f *cmdutil.Factory, runF func(*CreateOptions) error) *cobra.Co
 			By default, gists are secret; use %[1]s--public%[1]s to make publicly listed ones.
 		`, "`"),
 		Example: heredoc.Doc(`
-			# publish file 'hello.py' as a public gist
+			# Publish file 'hello.py' as a public gist
 			$ gh gist create --public hello.py
 
-			# create a gist with a description
+			# Create a gist with a description
 			$ gh gist create hello.py -d "my Hello-World program in Python"
 
-			# create a gist containing several files
+			# Create a gist containing several files
 			$ gh gist create hello.py world.py cool.txt
 
-			# read from standard input to create a gist
+			# Read from standard input to create a gist
 			$ gh gist create -
 
-			# create a gist from output piped from another command
+			# Create a gist from output piped from another command
 			$ cat cool.txt | gh gist create
 		`),
 		Args: func(cmd *cobra.Command, args []string) error {

@@ -38,19 +38,19 @@ func NewCmdDelete(f *cmdutil.Factory, runF func(*DeleteOptions) error) *cobra.Co
 		Use:   "delete {<id> | <url>}",
 		Short: "Delete a gist",
 		Long: heredoc.Docf(`
-		Delete a GitHub gist.
+			Delete a GitHub gist.
 
-		To delete a gist interactively, use %[1]sgh gist delete%[1]s with no arguments.
+			To delete a gist interactively, use %[1]sgh gist delete%[1]s with no arguments.
 
-		To delete a gist non-interactively, supply the gist id or url.
-	`, "`"),
+			To delete a gist non-interactively, supply the gist id or url.
+		`, "`"),
 		Example: heredoc.Doc(`
-		# delete a gist interactively
-		gh gist delete
+			# Delete a gist interactively
+			$ gh gist delete
 
-		# delete a gist non-interactively
-		gh gist delete 1234
-	`),
+			# Delete a gist non-interactively
+			$ gh gist delete 1234
+		`),
 		Args: cobra.MaximumNArgs(1),
 		RunE: func(c *cobra.Command, args []string) error {
 			if !opts.IO.CanPrompt() && !opts.Confirmed {

@@ -61,10 +61,10 @@ func NewCmdList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Comman
 			No highlights or other color is printed when output is redirected.
 		`, "`"),
 		Example: heredoc.Doc(`
-			# list all secret gists from your user account
+			# List all secret gists from your user account
 			$ gh gist list --secret
 
-			# find all gists from your user account mentioning "octo" anywhere
+			# Find all gists from your user account mentioning "octo" anywhere
 			$ gh gist list --filter octo --include-content
 		`),
 		Aliases: []string{"ls"},

@@ -47,10 +47,10 @@ func newCmdClone(f *cmdutil.Factory, runF func(*cloneOptions) error) *cobra.Comm
 			destination repository using the %[1]s--force%[1]s flag.
 		`, "`"),
 		Example: heredoc.Doc(`
-			# clone and overwrite labels from cli/cli repository into the current repository
+			# Clone and overwrite labels from cli/cli repository into the current repository
 			$ gh label clone cli/cli --force
 
-			# clone labels from cli/cli repository into a octocat/cli repository
+			# Clone labels from cli/cli repository into a octocat/cli repository
 			$ gh label clone cli/cli --repo octocat/cli
 		`),
 		Args: cmdutil.ExactArgs(1, "cannot clone labels: source-repository argument required"),

@@ -66,7 +66,7 @@ func newCmdCreate(f *cmdutil.Factory, runF func(*createOptions) error) *cobra.Co
 			The label color needs to be 6 character hex value.
 		`, "`"),
 		Example: heredoc.Doc(`
-			# create new bug label
+			# Create new bug label
 			$ gh label create bug --description "Something isn't working" --color E99695
 		`),
 		Args: cmdutil.ExactArgs(1, "cannot create label: name argument required"),

@@ -42,10 +42,10 @@ func newCmdEdit(f *cmdutil.Factory, runF func(*editOptions) error) *cobra.Comman
 			The label color needs to be 6 character hex value.
 		`, "`"),
 		Example: heredoc.Doc(`
-			# update the color of the bug label
+			# Update the color of the bug label
 			$ gh label edit bug --color FF0000
 
-			# rename and edit the description of the bug label
+			# Rename and edit the description of the bug label
 			$ gh label edit bug --name big-bug --description "Bigger than normal bug"
 		`),
 		Args: cmdutil.ExactArgs(1, "cannot update label: name argument required"),