[Aug 24, 2021] Top level CLI docs set (#20628)

Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Co-authored-by: Mislav Marohnić <mislav@github.com>
Co-authored-by: Laura Coursen <lecoursen@github.com>

content/github-cli/github-cli/about-github-cli.md

@@ -0,0 +1,30 @@
+---
+title: About GitHub CLI
+intro: '{% data reusables.cli.cli-intro %}'
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghae: '*'
+topics:
+  - CLI
+type: overview
+redirect_from:
+  - /github/getting-started-with-github/github-cli
+  - /github/getting-started-with-github/using-github/github-cli
+  - /actions/guides/managing-github-actions-with-github-cli
+---
+## About {% data variables.product.prodname_cli %}
+
+{% data reusables.cli.about-cli %}
+
+{% data reusables.cli.cli-features %}
+
+For more information about what you can do with {% data variables.product.prodname_cli %}, see the [{% data variables.product.prodname_cli %} manual](https://cli.github.com/manual).
+
+## Installing {% data variables.product.prodname_cli %}
+
+View installation instructions {% data variables.product.prodname_cli %} for macOS, Windows, and Linux on the [{% data variables.product.prodname_cli %} page](https://cli.github.com).
+
+## Sharing feedback
+
+If you have feedback or feature requests, you can open an issue in the [`cli/cli` repository](https://github.com/cli/cli).

content/github-cli/github-cli/creating-github-cli-extensions.md

@@ -0,0 +1,152 @@
+---
+title: Creating GitHub CLI extensions
+intro: 'Learn how to share new {% data variables.product.prodname_cli %} commands with other users by creating custom extensions for {% data variables.product.prodname_cli %}.'
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghae: '*'
+topics:
+  - CLI
+---
+
+## About {% data variables.product.prodname_cli %} extensions
+
+{% data reusables.cli.cli-extensions %} For more information about how to use {% data variables.product.prodname_cli %} extensions, see "[Using {% data variables.product.prodname_cli %} extensions](/github-cli/github-cli/using-github-cli-extensions)."
+
+You need a repository for each extension that you create. The repository name must start with `gh-`. The rest of the repository name is the name of the extension. At the root of the repository, there must be an executable file with the same name as the repository. This file will be executed when the extension is invoked.
+
+{% note %}
+
+**Note**: We recommend that the executable file is a bash script because bash is a widely available interpreter. You may use non-bash scripts, but the user must have the necessary interpreter installed in order to use the extension.
+
+{% endnote %}
+
+## Creating an extension with `gh extension create`
+
+You can use the `gh extension create` command to create a project for your extension, including a bash script that contains some starter code.
+
+1. Set up a new extension by using the `gh extension create` subcommand. Replace `EXTENSION-NAME` with the name of your extension.
+
+    ```shell
+    gh extension create <em>EXTENSION-NAME</em>
+    ```
+
+1. Follow the printed instructions to finalize and optionally publish your extension.
+
+## Creating an extension manually
+
+1. Create a local directory called `gh-EXTENSION-NAME` for your extension. Replace `EXTENSION-NAME` with the name of your extension. For example, `gh-whoami`.
+
+1. In the directory that you created, add an executable file with the same name as the directory.
+
+  {% note %}
+
+  **Note:** Make sure that your file is executable. On Unix, you can execute `chmod +x file_name` in the command line to make `file_name` executable. On Windows, you can run `git init -b main`, `git add file_name`, then `git update-index --chmod=+x file_name`.
+
+  {% endnote %}
+
+1. Write your script in the executable file. For example:
+
+  ```bash
+  #!/bin/bash
+  set -e
+  exec gh api user --jq '"You are @\(.login) (\(.name))."'
+  ```
+
+1. From your directory, install the extension as a local extension.
+
+   ```bash
+   gh extension install .
+   ```
+
+1. Verify that your extension works. Replace `EXTENSION-NAME` with the name of your extension. For example, `whoami`.
+
+   ```shell
+   gh <em>EXTENSION-NAME</em>
+   ```
+
+1. From your directory, create a repository to publish your extension. Replace `EXTENSION-NAME` with the name of your extension.
+
+   ```shell
+   git init -b main
+   gh repo create gh-<em>EXTENSION-NAME</em> --confirm
+   git add . && git commit -m "initial commit" && git push --set-upstream origin main
+   ```
+
+1. Optionally, to help other users discover your extension, add the repository topic `gh-extension`. This will make the extension appear on the [`gh-extension` topic page](https://github.com/topics/gh-extension). For more information about how to add a repository topic, see "[Classifying your repository with topics](/github/administering-a-repository/managing-repository-settings/classifying-your-repository-with-topics)."
+
+## Tips for writing {% data variables.product.prodname_cli %} extensions
+
+### Handling arguments and flags
+
+All command line arguments following a `gh my-extension-name` command will be passed to the extension script. In a bash script, you can reference arguments with `$1`, `$2`, etc. You can use arguments to take user input or to modify the behavior of the script.
+
+For example, this script handles multiple flags. When the script is called with the `-h` or `--help` flag, the script prints help text instead of continuing execution. When the script is called with the `--name` flag, the script sets the next value after the flag to `name_arg`. When the script is called with the `--verbose` flag, the script prints a different greeting.
+
+```bash
+#!/bin/bash
+set -e
+
+verbose=""
+name_arg=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+  --verbose)
+    verbose=1
+    ;;
+  --name)
+    name_arg="$2"
+    shift
+    ;;
+  -h|--help)
+    echo "Add help text here."
+    exit 0
+    ;;
+  esac
+  shift
+done
+
+if [ -z "$name_arg" ]
+then
+  echo "You haven't told us your name."
+elif [ -z "$verbose" ]
+then
+  echo "Hi $name_arg"
+else
+  echo "Hello and welcome, $name_arg"
+fi
+```
+
+### Calling core commands in non-interactive mode
+
+Some {% data variables.product.prodname_cli %} core commands will prompt the user for input. When scripting with those commands, a prompt is often undesirable. To avoid prompting, supply the necessary information explicitly via arguments. 
+
+For example, to create an issue programmatically, specify the title and body:
+
+```bash
+gh issue create --title "My Title" --body "Issue description"
+```
+
+### Fetching data programatically
+
+Many core commands support the `--json` flag for fetching data programatically. For example, to return a JSON object listing the number, title, and mergeability status of pull requests:
+```bash
+gh pr list --json number,title,mergeStateStatus
+```
+
+If there is not a core command to fetch specific data from GitHub, you can use the [`gh api`](https://cli.github.com/manual/gh_api) command to access the GitHub API. For example, to fetch information about the current user:
+```bash
+gh api user
+```
+
+All commands that output JSON data also have options to filter that data into something more immediately usable by scripts. For example, to get the current user's name:
+
+```bash
+gh api user --jq '.name'
+```
+
+For more information, see [`gh help formatting`](https://cli.github.com/manual/gh_help_formatting).
+
+## Next steps
+
+To see more examples of {% data variables.product.prodname_cli %} extensions, look at [repositories with the `gh-extension` topic](https://github.com/topics/gh-extension).

content/github-cli/github-cli/github-cli-reference.md

@@ -0,0 +1,29 @@
+---
+title: GitHub CLI reference
+intro: 'You can view all of the {% data variables.product.prodname_cli %} commands in your terminal or in the {% data variables.product.prodname_cli %} manual.'
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghae: '*'
+topics:
+  - CLI
+type: reference
+---
+
+To view all {% data variables.product.prodname_cli %} commands, see the [{% data variables.product.prodname_cli %} manual](https://cli.github.com/manual/gh_help_reference) or use the `reference` command.
+
+```shell
+gh reference
+```
+
+To view the environment variables that can be used with {% data variables.product.prodname_cli %}, see the [{% data variables.product.prodname_cli %} manual](https://cli.github.com/manual/gh_help_environment) or use the `environment` command.
+
+```shell
+gh environment
+```
+
+To view the configuration settings that can be used with {% data variables.product.prodname_cli %}, see the [{% data variables.product.prodname_cli %} manual](https://cli.github.com/manual/gh_config) or use the `config` command.
+
+```shell
+gh config
+```

content/github-cli/github-cli/index.md

@@ -0,0 +1,15 @@
+---
+title: GitHub CLI
+shortTitle: GitHub CLI
+intro: '{% data reusables.cli.about-cli %}'
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghae: '*'
+children:
+  - /about-github-cli
+  - /quickstart
+  - /creating-github-cli-extensions
+  - /using-github-cli-extensions
+  - /github-cli-reference
+---

content/github-cli/github-cli/quickstart.md

@@ -0,0 +1,46 @@
+---
+title: GitHub CLI quickstart
+intro: 'Start using {% data variables.product.prodname_cli %} to work with {% data variables.product.company_short %} in the command line.'
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghae: '*'
+topics:
+  - CLI
+type: overview
+allowTitleToDifferFromFilename: true
+shortTitle: Quickstart
+---
+
+## About {% data variables.product.prodname_cli %}
+
+{% data reusables.cli.about-cli %}
+
+## Getting started
+
+1. [Install](https://github.com/cli/cli#installation) {% data variables.product.prodname_cli %} on macOS, Windows, or Linux.
+1. In the command line, authenticate to {% data variables.product.company_short %}.
+
+  ```shell
+  gh auth login
+  ```
+
+  {% ifversion not fpt %}
+  To authenticate to {% data variables.product.product_location %}, use the `--hostname` flag.
+
+  ```shell
+  gh auth login --hostname <em>hostname</em>
+  ```
+
+  {% endif %}
+1. Start working with {% data variables.product.company_short %} in the command line. For example, find an issue to work on with `gh issue status` or `gh issue list --assignee @me`. Create a pull request with `gh pr create`. Review a pull request with `gh pr checkout`, `gh pr diff` and `gh pr review`.
+
+## Next steps
+
+- Tell {% data variables.product.prodname_cli %} which text editor to use for commands that open a text editor. For example, enter `gh config set editor "code -w"` to set your preferred text editor to {% data variables.product.prodname_vscode %}. For more information, see [`gh config set`](https://cli.github.com/manual/gh_config_set).
+
+- Define aliases for commands that you commonly run. For example, if you run `gh alias set prd "pr create --draft"`, you will then be able to run `gh prd` to quickly open a draft pull request. For more information, see [`gh alias`](https://cli.github.com/manual/gh_alias).
+
+- Create or add custom commands with {% data variables.product.prodname_cli %} extensions. For more information, see "[Using {% data variables.product.prodname_cli %} extensions](/github-cli/github-cli/using-github-cli-extensions)" and "[Creating {% data variables.product.prodname_cli %} extensions](/github-cli/github-cli/creating-github-cli-extensions)."
+
+- For more information about all of the commands that you can run with {% data variables.product.prodname_cli %}, see "[{% data variables.product.prodname_cli %} reference](/github-cli/github-cli/github-cli-reference)."

content/github-cli/github-cli/using-github-cli-extensions.md

@@ -0,0 +1,66 @@
+---
+title: Using GitHub CLI extensions
+intro: 'Learn how to use custom extensions written by other {% data variables.product.prodname_cli %} users.'
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghae: '*'
+topics:
+  - CLI
+---
+
+## About {% data variables.product.prodname_cli %} extensions
+
+{% note %}
+
+**Note:** Extensions outside of {% data variables.product.product_name %} and {% data variables.product.prodname_cli %} are not certified by {% data variables.product.product_name %} and are governed by separate terms of service, privacy policy, and support documentation. To mitigate risk when using third-party extensions, audit the source code of the extension before installing or updating the extension.
+
+{% endnote %}
+
+{% data reusables.cli.cli-extensions %} For more information about how to create {% data variables.product.prodname_cli %} extensions, see "[Creating {% data variables.product.prodname_cli %} extensions](/github-cli/github-cli/creating-github-cli-extensions)."
+
+Extensions are locally installed and are scoped to the user. Therefore, if you access {% data variables.product.prodname_cli %} from a different machine or another user accesses {% data variables.product.prodname_cli %} from the same machine, the extension will not be available.
+
+## Finding extensions
+
+You can find extensions by browsing [repositories with the `gh-extension` topic](https://github.com/topics/gh-extension).
+
+## Installing extensions
+
+To install an extension, use the `extensions install` subcommand. Replace the `owner/repo` parameter with the name of the extension, such as `octocat/gh-whoami`.{% ifversion ghes %} If the extension is on {% data variables.product.prodname_ghe_server %}, also include the hostname, such as `https://ghe.io/octocat/gh-whoami`.{% endif %}
+
+```shell
+gh extension install <em>owner/repo</em>
+```
+
+If you already have an extension by the same name installed, the command will fail. For example, if you have installed `octocat/gh-whoami`, you must uninstall it before installing `hubot/gh-whoami`.
+
+## Viewing installed extensions
+
+To view all installed extensions, use the `extensions list` subcommand. The output will also tell you which extensions have updates available.
+
+```shell
+gh extension list
+```
+
+## Updating extensions
+
+To update an extension, use the `extensions upgrade` subcommand. Replace the `extension` parameter with the name of the extension.
+
+```shell
+gh extension upgrade <em>extension</em>
+```
+
+To update all installed extensions, use the `--all` flag.
+
+```shell
+gh extension upgrade --all
+```
+
+## Uninstalling extensions
+
+To uninstall an extension, use the `extensions remove` subcommand. Replace the `extension` parameter with the name of the extension.
+
+```shell
+gh extension remove <em>extension</em>
+```

content/github-cli/index.md

@@ -0,0 +1,34 @@
+---
+title: GitHub CLI
+shortTitle: GitHub CLI
+intro: '{% data reusables.cli.about-cli %}'
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghae: '*'
+children:
+  - /github-cli
+introLinks:
+  overview: /github-cli/github-cli/about-github-cli
+  quickstart: /github-cli/github-cli/quickstart
+  reference: /github-cli/github-cli/github-cli-reference
+featuredLinks:
+  guides: 
+    - /github-cli/github-cli/creating-github-cli-extensions
+    - /github-cli/github-cli/using-github-cli-extensions
+    - /actions/guides/using-github-cli-in-workflows
+  popular:
+    - /github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
+    - /issues/tracking-your-work-with-issues/creating-an-issue
+    - /github/authenticating-to-github/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account
+    - /get-started/quickstart/create-a-repo
+    - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally
+    - /github/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request
+    - /get-started/quickstart/fork-a-repo
+    - /github/creating-cloning-and-archiving-repositories/cloning-a-repository-from-github/cloning-a-repository
+  popularHeading: Popular CLI tasks
+changelog:
+  label: cli
+layout: product-landing
+beta_product: false
+---