Files
reference/source/_posts/github-cli.md
T
FireIsGood a02928b905 fix: github-cli format
Adds headers propertly and fixes the codeblock format
2024-05-16 16:22:11 -07:00

237 lines
9.7 KiB
Markdown

---
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**
| Tool | 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` |
{.show-header}
**Mac OS**
| Tool | Install | Upgrade |
| :------- | :--------------------- | :--------------------------------------------- |
| Brew | `brew install gh` | `brew upgrade gh` |
| MacPorts | `sudo port install gh` | `sudo port selfupdate && sudo port upgrade gh` |
{.show-header}
**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 |