Merge pull request #1370 from cli/docs-environment

Document supported environment variables

command/help.go

@@ -131,6 +131,9 @@ func rootHelpFunc(command *cobra.Command, args []string) {
 	if command.Example != "" {
 		helpEntries = append(helpEntries, helpEntry{"EXAMPLES", command.Example})
 	}
+	if _, ok := command.Annotations["help:environment"]; ok {
+		helpEntries = append(helpEntries, helpEntry{"ENVIRONMENT VARIABLES", command.Annotations["help:environment"]})
+	}
 	helpEntries = append(helpEntries, helpEntry{"LEARN MORE", `
 Use "gh <command> <subcommand> --help" for more information about a command.
 Read the manual at https://cli.github.com/manual`})

command/root.go

@@ -111,9 +111,28 @@ var RootCmd = &cobra.Command{
 	$ gh pr checkout 321
 	`),
 	Annotations: map[string]string{
-		"help:feedback": `
-Fill out our feedback form https://forms.gle/umxd3h31c7aMQFKG7
-Open an issue using “gh issue create -R cli/cli”`},
+		"help:feedback": heredoc.Doc(`
+			Fill out our feedback form https://forms.gle/umxd3h31c7aMQFKG7
+			Open an issue using “gh issue create -R cli/cli”
+		`),
+		"help:environment": heredoc.Doc(`
+			GITHUB_TOKEN: an authentication token for API requests. Setting this avoids being
+			prompted to authenticate and overrides any previously stored credentials.
+
+			GH_REPO: specify the GitHub repository in "OWNER/REPO" format for commands that
+			otherwise operate on a local repository.
+
+			GH_EDITOR, GIT_EDITOR, VISUAL, EDITOR (in order of precedence): the editor tool to use
+			for authoring text.
+
+			BROWSER: the web browser to use for opening links.
+
+			DEBUG: set to any value to enable verbose output to standard error. Include values "api"
+			or "oauth" to print detailed information about HTTP requests or authentication flow.
+
+			NO_COLOR: avoid printing ANSI escape sequences for color output.
+		`),
+	},
 }
 
 var versionCmd = &cobra.Command{

pkg/cmd/api/api.go

@@ -86,29 +86,34 @@ original query accepts an '$endCursor: String' variable and that it fetches the
 			$ gh api repos/:owner/:repo/releases
 
 			$ gh api graphql -F owner=':owner' -F name=':repo' -f query='
-				query($name: String!, $owner: String!) {
-					repository(owner: $owner, name: $name) {
-						releases(last: 3) {
-							nodes { tagName }
-						}
-					}
-				}
+			  query($name: String!, $owner: String!) {
+			    repository(owner: $owner, name: $name) {
+			      releases(last: 3) {
+			        nodes { tagName }
+			      }
+			    }
+			  }
 			'
 			
 			$ gh api graphql --paginate -f query='
-				query($endCursor: String) {
-					viewer {
-						repositories(first: 100, after: $endCursor) {
-							nodes { nameWithOwner }
-							pageInfo {
-								hasNextPage
-								endCursor
-							}
-						}
-					}
-				}
+			  query($endCursor: String) {
+			    viewer {
+			      repositories(first: 100, after: $endCursor) {
+			        nodes { nameWithOwner }
+			        pageInfo {
+			          hasNextPage
+			          endCursor
+			        }
+			      }
+			    }
+			  }
 			'
 		`),
+		Annotations: map[string]string{
+			"help:environment": heredoc.Doc(`
+				GITHUB_TOKEN: an authentication token for API requests.
+			`),
+		},
 		Args: cobra.ExactArgs(1),
 		RunE: func(c *cobra.Command, args []string) error {
 			opts.RequestPath = args[0]