--- title: Github CLI date: 2023-11-29 icon: background: bg-[#808080] tags: - Github - CICD - CLI categories: - Toolkit intro: A quick reference to Github CLI, an open-source command line tool that enables GitHub on your terminal. plugins: - copyCode --- Getting Started ------------ ### Installation **Windows** | | Install | Upgrade | | :--- | :--- | :--- | | | Install | Upgrade | | WinGet | ```winget install --id Github.cli``` | ```winget upgrade --id GitHub.cli``` | | Scoop | ```scoop install gh``` | ```scoop update gh``` | | Choco | ```choco install gh``` | ```choco upgrade gh``` | **Mac OS** | | Install | Upgrade | | :--- | :--- | :--- | | | Install | Upgrade | | Brew | ```brew install gh ``` | ```brew upgrade gh``` | | MacPorts | ```sudo port install gh``` | ```sudo port selfupdate && sudo port upgrade gh``` | **Linux** See the [install instructions](https://github.com/cli/cli/blob/trunk/docs/install_linux.md) for other Linux distributions. Installation Script: ```bash type -p curl >/dev/null || (sudo apt update && sudo apt install curl -y) curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \ && sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg \ && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \ && sudo apt update \ && sudo apt install gh -y ``` --- ### Basic Usage **Help and Documentation** Display command options: | Command | Description | | :--- | :--- | | ```gh help [command]``` | Help provides help for any command in the application. Simply type gh help [path to command] for full details. | **Authentication** | Command | Description | | :--- | :--- | | ```gh auth login``` | Default authentication with web-based browser | | ```gh auth logout``` | Removes the authentication configuration for a host | | ```gh auth refresh``` | Expand or fix the permission scopes for stored credentials | | ```gh auth setup-git``` | Configures git to use GitHub CLI as a credential helper | | ```gh auth status``` | Verifies and displays information about your authentication state | | ```gh auth token``` | Print the auth token gh is configured to use | With Github token: ```shell $ gh auth --with-token < token.txt ``` ### Repository Management **General** | Command | Description | | :--- | :--- | | ```gh repo create``` | Create a new GitHub repository | | ```gh repo list [target]``` | List repositories owned by a user or organization | **Targets** | Command | Description | | :--- | :--- | | ```gh repo archive [repo]``` | Archive a GitHub repository | | ```gh repo clone [dir]``` | Clone a GitHub repository locally | | ```gh repo delete [repo]``` | Delete a GitHub repository | | ```gh repo deploy-key``` | Manage deploy keys in a repository | | ```gh repo edit [repo]``` | Edit repository settings | | ```gh repo fork [repo]``` | Create a fork of a repository | | ```gh repo rename [name]``` | Rename a GitHub repository | | ```gh repo set-default [repo]``` | This command sets the default remote repository | | ```gh repo sync [dest-repo]``` | Sync destination repository from source repository | | ```gh repo view [repo]``` | Display the description and the README of a GitHub repository. | ### Issues **Search Issues** | Command | Description | | :--- | :--- | | ```gh search issues [query]``` | Search for issues on GitHub | **Examples** ```bash # search issues matching set of keywords "readme" and "typo" $ gh search issues readme typo # search issues matching phrase "broken feature" $ gh search issues "broken feature" # search issues and pull requests in cli organization $ gh search issues --include-prs --owner=cli # search open issues assigned to yourself $ gh search issues --assignee=@me --state=open # search issues with numerous comments $ gh search issues --comments=">100" # search issues without label "bug" $ gh search issues -- -label:bug ``` ### Pull Requests **Pull Request Actions** | Command | Description | | :--- | :--- | | ```gh pr create``` | Create a pull request on GitHub | | ```gh pr list``` | List pull requests in a GitHub repository | | ```gh pr status``` | Show status of relevant pull requests | **Example** ```shell $ gh pr status ``` Sample Output: ``` Current branch #12 Remove the test feature [user:patch-2] - All checks failing - Review required Created by you You have no open pull requests Requesting a code review from you #13 Fix tests [branch] - 3/4 checks failing - Review required #15 New feature [branch] - Checks passing - Approved ``` ### Github Actions **General Actions** | Command | Description | | :--- | :--- | | ```gh workflow disable``` | Disable a workflow, preventing it from running or showing up when listing workflows | | ```gh workflow enable``` | Enable a workflow, allowing it to be run and show up when listing workflows | | ```gh workflow list``` | List workflow files, hiding disabled workflows by default | | ```gh workflow run``` | Create a workflow_dispatch event for a given workflow | | ```gh workflow view``` | View the summary of a workflow | **Running Actions** | Command | Description | | :--- | :--- | | ```gh run cancel``` | Cancel a workflow run | | ```gh run delete``` | Delete a workflow run | | ```gh run download``` | Download artifacts generated by a GitHub Actions workflow run | | ```gh run list``` | List recent workflow runs | | ```gh run rerun``` | Rerun an entire run, only failed jobs, or a specific job from a run | | ```gh run view``` | View a summary of a workflow run | | ```gh run watch``` | Watch a run until it completes, showing its progress | ### Aliases **General Alias Settings** | Command | Description | | :--- | :--- | | ```gh alias delete``` | Delete set aliases | | ```gh alias import``` | Import aliases from the contents of a YAML file | | ```gh alias list``` | Prints out all of the aliases gh is configured to use | | ```gh alias set``` | Define a word that will expand to a full gh command when invoked | ### Releases **General Actions** | Command | Description | | :--- | :--- | | ```gh release create``` | Create a new GitHub Release for a repository | | ```gh release list``` | List releases in a repository | **Target Commands** | Command | Description | | :--- | :--- | |```gh release delete``` | Delete a release | |```gh release delete-asset``` | Delete an asset from a release | |```gh release download``` | Download assets from a GitHub release | |```gh release edit``` | Edit a release | |```gh release upload``` | Upload asset files to a GitHub Release | |```gh release view``` | View information about a GitHub Release | ### Configuration **Targeted Settings** | Command | Description | | :--- | :--- | | ```gh config clear-cache``` | Clear the cli cache | | ```gh config get``` | Print the value of a given configuration key | | ```gh config list``` | Print a list of configuration keys and values | | ```gh config set``` | Update configuration with a value for the given key |