# GitHub CLI 常用命令筆記

最近 [GitHub CLI](https://cli.github.com/) 用的很開心，因為用了 [GitHub Copilot Coding Agent](https://docs.github.com/en/copilot/concepts/coding-agent), [OpenAI Codex CLI](https://github.com/openai/codex/), [Gemini CLI](https://github.com/google-gemini/gemini-cli/) 與 [Claude Code](https://www.anthropic.com/claude-code) 之後，有越來越多專案都開始移往 GitHub 平台，而我在寫 [GitHub Actions](https://github.com/features/actions) workflows 的時候，也非常愛用 [GitHub CLI](https://cli.github.com/) 幫我操作 GitHub Issues 與 PRs，超級方便。這篇文章我打算記錄一些比較常用的參數與命令，以備日後快速查找參考。

![](https://stwillblogassets.blob.core.windows.net/files/images/external/stwillblogassets.blob.core.windows.net/f9652b24b4ea57fadc65-0e97a59f-cfec-4d4e-add7-b74ee6cdfb62.jpg)

### 安裝 GitHub CLI

GitHub CLI 支援 macOS, Linux, BSD 與 Windows 平台，安裝方式參見: [https://github.com/cli/cli#installation](https://github.com/cli/cli#installation)

以下是 Windows 的安裝方法：

-   [WinGet](https://learn.microsoft.com/zh-tw/windows/package-manager/winget/?WT.mc_id=DT-MVP-4015686)
    
    ```bash
    # 安裝
    winget install --id GitHub.cli
    
    # 升級
    winget upgrade --id GitHub.cli
    ```
    
-   [scoop](https://scoop.sh/)
    
    ```bash
    # 安裝
    scoop install gh
    
    # 升級
    scoop update gh
    ```
    
-   [Chocolatey](https://chocolatey.org/install)
    
    ```bash
    # 安裝
    choco install gh
    
    # 升級
    choco upgrade gh
    ```
    

### 初始化登入

GitHub CLI 有兩種認證方式：

1.  使用 [gh auth login](https://cli.github.com/manual/gh_auth_login) 登入，用你的 GitHub 身份進行操作
    
    這是最常見的使用方式，可以用你的 GitHub 身份執行完整的 GitHub CLI 功能，包含 [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/github-flow/using-github-copilot-in-the-command-line)。
    
2.  直接讀取 `GH_TOKEN` 或 `GITHUB_TOKEN` [環境變數](https://cli.github.com/manual/gh_help_environment) (免走登入程序)
    
    你要事先建立 GitHub PAT ([personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)) 並將其設定到 `GH_TOKEN` 或 `GITHUB_TOKEN` 環境變數中 (二選一即可)。
    
    💡 注意: 透過[環境變數](https://cli.github.com/manual/gh_help_environment)認證是無法使用 [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/github-flow/using-github-copilot-in-the-command-line) 的，但是可以在建立 PAT 金鑰時設定較為精細的權限，對於自動化任務來說，是比較適合的授權方式。
    
    詳見: [Managing your personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
    

設定好之後，可以用以下命令查看登入狀態：

```bash
gh auth status
```

### 設定慣用編輯器

由於我們可能會需要在命令列直接建立 Issue，所以偶爾會需要編輯器來編寫文字。

-   設定 Visual Studio Code 做為預設的文字編輯器
    
    ```bash
    gh config set editor "code --wait"
    ```
    
-   設定 vim 做為預設的文字編輯器
    
    ```bash
    gh config set editor "vim"
    ```
    

你可以用以下命令測試開啟編輯器編輯內容：

```bash
gh issue create
```

或是透過以下命令在 Feature Branch 建立 PR 時，也需要文字編輯器撰寫一些內容：

```bash
gh pr create --draft --assignee @me
```

### 常見命令整理

💡 提醒: 大部分的 `gh` 命令都只要在 git 工作目錄執行，就會自動從 `git remote` 找到 GitHub Repo 的網址。

-   Repos
    
    查看目前 Repo 的相關資訊
    
    ```bash
    gh repo view
    ```
    
    查看任意 Repo 的相關資訊
    
    ```bash
    gh repo view doggy8088/TampermonkeyUserscripts
    ```
    
    直接 Fork 某個 Repo 並直接將這份 Fork 過的 Repo 給 Clone 到本地
    
    ```bash
    gh repo fork cli/cli
    ```
    
    直接將目前已經 Clone 的 Repo 建立一個 Fork repo 並將 origin 更名為 upstream，然後 origin 會換成 forked remote
    
    ```bash
    gh repo fork
    ```
    
-   Clone
    
    ```bash
    # Method 1
    gh repo clone cli/cli
    
    # Method 2
    gh repo clone https://github.com/cli/cli
    ```
    
    > Method 2 就是把 `git` 換成 `gh repo` 而已，但可以簡寫 `cli/cli`。
    
-   Checkout / PR
    
    自動取出 `PR #12` 的分支內容
    
    ```bash
    gh pr checkout 12
    ```
    
    也可以直接輸入網址來取出 PR 的分支
    
    ```bash
    gh pr checkout https://github.com/doggy8088/duotify-form-autofill/pull/6
    ```
    
    顯示目前 PR 的狀態
    
    ```bash
    gh pr status
    ```
    
-   Issues / PRs
    
    基本上 Issues 與 PRs 用法大多相同，許多命令 `gh issue` 換成 `gh pr` 就可以用，不過 PR 會綁定一個分支，通常要 `gh pr checkout NN` 之後才能查看狀態。
    
    快速列出跟自己有關的 Issues
    
    ```bash
    gh issue status
    ```
    
    列出 Issues
    
    ```bash
    # 列出所有 Open 的 Issues (預設只會傳回 30 筆)
    gh issue list
    # 列出所有 Closed 的 Issues
    gh issue list -s closed
    # 列出所有 Issues
    gh issue list -s all
    # 列出我建立的 Issues
    gh issue list --author '@me'
    # 列出我建立的 Issues
    gh issue list --assignee 'user'
    # 列出所有 kind/bug 標籤的 Issues 且要回傳最多 100 筆
    gh issue list -l 'kind/bug' -L 100
    ```
    
    查看單一個 Issue 的明細
    
    ```bash
    # 查看 Issue 主要內容
    gh pr view 21
    # 查看 Issue 主要內容並列出所有留言
    gh pr view 21 --comments
    # 直接開啟瀏覽器查看 Issue 內容
    gh pr view 21 --web
    ```
    
    建立 Issue
    
    ```bash
    # 互動式建立 Issue
    gh issue create
    
    # 透過瀏覽器建立 Issue
    gh issue create --web
    
    # 非互動方式建立 Issue
    gh issue create --title "Issue title" --body "Issue body"
    ```
    
    替 Issue 加上表情符號 (需透過 [gh api](https://cli.github.com/manual/gh_api) 呼叫)
    
    ```bash
    # 直接在某個 Issue 的主文 `+1` 按讚
    gh api -X POST /repos/doggy8088/plaud-web-uploader/issues/43/reactions -f content='+1'
    
    # 取得某個 Issue 的主文的所有表情符號清單
    gh api -X GET /repos/doggy8088/plaud-web-uploader/issues/43/reactions
    
    # 刪除表情符號(Reaction)，這裡 209967036 是當初按讚時的 Reaction ID
    gh api -X DELETE /repos/doggy8088/plaud-web-uploader/issues/43/reactions/209967036
    ```
    
    > 詳細參考: [REST API endpoints for reactions](https://docs.github.com/en/rest/reactions/reactions?apiVersion=2022-11-28)
    
-   設定 gh 的 alias 命令
    
    假設你經常需要列出自己的工作
    
    ```bash
    # 定義名為 mywork 的別名
    gh alias set my 'issue list --assignee @me'
    
    # 未來直接執行 gh my 就等於 gh issue list --assignee @me
    gh my
    ```
    
    假設你經常需要列出提到自己的 Issues
    
    ```bash
    # 你可以定義更有語意的 alias 別名
    gh alias set 'issue mine' 'issue list --mention @me'
    
    # 未來直接執行 gh issue mine 就等於 gh issue list --mention @me
    gh issue mine
    ```
    
    假設你經常需要列出標籤為 bugs 的 Issues
    
    ```bash
    # 定義名為 bugs 的別名
    gh alias set bugs 'issue list --label=kind/bug'
    # 定義名為 bugs 的別名並直接覆蓋現有的別名
    gh alias set bugs 'issue list --label=kind/bug' --clobber
    
    # 未來直接執行 gh bugs 就等於 gh issue list --label=kind/bug
    gh bugs
    ```
    
    列出所有的 gh aliases
    
    ```bash
    gh alias list
    ```
    

### GitHub CLI 的擴充功能

1.  [GitHub Copilot in the CLI](https://github.com/github/gh-copilot)
    
    ```bash
    # 一定要用 GitHub CLI OAuth 登入
    gh auth login --web
    
    # 安裝或升級 GitHub Copilot CLI
    gh extension install github/gh-copilot --force
    
    # 使用 GitHub Copilot 建議一個命令
    gh copilot suggest "Install and configure git lfs"
    
    # 使用 GitHub Copilot 解釋一個命令 (僅限英文回應)
    gh copilot explain 'git lfs migrate import --everything --include="*.gz,*.png,*.jar"'
    ```
    
2.  [gh-dash](https://github.com/dlvhdr/gh-dash)
    
    用 TUI 視覺化的方式呈現 Issues 與 PRs，非常美觀，少大很多命令！👍
    
    ```bash
    gh extension install dlvhdr/gh-dash
    
    gh dash
    ```
    
3.  [GitHub Actions Importer](https://github.com/github/gh-actions-importer)
    
    [GitHub Actions Importer](https://docs.github.com/en/actions/migrating-to-github-actions/automating-migration-with-github-actions-importer) 可協助您規劃、測試及自動化從 Azure DevOps、Bamboo、Bitbucket、CircleCI、GitLab、Jenkins、Travis CI 平台遷移至 GitHub Actions！👍
    
    GitHub Actions Importer 以 Docker 容器形式散佈，並且此擴充功能可與官方 GitHub CLI 互動以操作 Docker 容器。
    
    ```bash
    # 安裝
    gh extension install github/gh-actions-importer
    
    # 更新
    gh actions-importer update
    
    # 設定
    gh actions-importer configure
    ```
    
4.  [GitHub Enterprise Importer CLI](https://github.com/github/gh-gei)
    
    [GitHub Enterprise Importer](https://docs.github.com/en/migrations/using-github-enterprise-importer) (GEI，前身為 Octoshift) 是一個高度可自訂的 API 優先遷移方案，旨在協助您將企業遷移至 GitHub Enterprise Cloud。GEI-CLI 將 GEI API 包裝成跨平台的命令列應用程式，以簡化您的遷移體驗自訂。
    
    ```bash
    # 安裝 Azure DevOps to GitHub 擴充功能
    gh extension install github/gh-ado2gh
    
    # 查看用法
    gh ado2gh --help
    
    # 詳見 Azure DevOps to GitHub Usage
    # https://github.com/github/gh-gei?tab=readme-ov-file#azure-devops-to-github-usage
    ```
    
5.  [GitHub Skyline](https://github.com/github/gh-skyline)
    
    可以自動產生你在 GitHub 貢獻圖，會自動輸出 3D 列印專用的 STL 檔案。
    
    ```bash
    # 安裝
    gh extension install github/gh-skyline
    
    # 產生
    gh skyline
    gh skyline --output my-skyline.stl
    gh skyline --full
    gh skyline --year 2024
    gh skyline --year 2024 --user doggy8088
    gh skyline --year 2014-2024 --user doggy8088
    ```
    

### 相關連結

-   [GitHub CLI | Take GitHub to the command line](https://cli.github.com/)
-   [GitHub CLI 使用手冊](https://cli.github.com/manual/)
-   [GitHub CLI 環境變數](https://cli.github.com/manual/gh_help_environment)
-   [GitHub CLI 命令參數清單](https://cli.github.com/manual/gh)
-   [cli/cli: GitHub's official command line tool](https://github.com/cli/cli?tab=readme-ov-file)