GitHub CLI(gh) 사용법: 터미널에서 GitHub 200% 활용하기

GitHub에서 이슈를 확인하려고 브라우저를 열고, PR을 만들려고 또 브라우저를 열고… 터미널에서 코딩하다가 브라우저와 터미널 사이를 왔다 갔다 하는 게 은근히 번거롭지 않으셨나요?

GitHub REST API를 curl로 직접 호출하는 방법도 있지만 URL과 헤더를 매번 타이핑하는 건 솔직히 고통스럽죠. 그래서 GitHub이 만든 게 바로 gh라는 공식 CLI 도구입니다. 터미널을 떠나지 않고도 이슈부터 PR, 릴리스까지 다 처리할 수 있어요.

이번 글에서는 gh CLI의 설치부터 실무에서 자주 쓰는 핵심 명령어까지 살펴보겠습니다.

gh CLI란?

gh는 GitHub이 공식으로 만든 커맨드라인 도구입니다. 이슈나 PR, 릴리스, 저장소 관리 등 GitHub 웹사이트에서 하던 거의 모든 작업을 터미널에서 할 수 있게 해줘요. Git이 버전 관리 도구라면 gh는 GitHub 플랫폼 자체를 다루는 도구라고 보면 됩니다.

curl로 REST API를 호출할 때와 비교하면 차이가 확 느껴지는데요. 예를 들어 이슈 목록을 가져오는 걸 비교해보면:

# curl로 REST API 직접 호출
curl -H "Authorization: Bearer $GH_TOKEN" \
  https://api.github.com/repos/DaleSeo/blog/issues

# gh CLI 사용
gh issue list

URL을 외울 필요도 없고, 인증 헤더를 매번 붙일 필요도 없습니다. gh가 현재 디렉토리의 Git 리모트 정보를 읽어서 어떤 저장소인지 알아서 파악해요.

설치

운영체제별로 패키지 매니저를 사용해서 간단히 설치할 수 있습니다.

macOS에서는 Homebrew로 설치하면 됩니다.

brew install gh

Windows에서는 winget이나 scoop을 사용하면 편합니다.

winget install --id GitHub.cli

Linux(Debian/Ubuntu)에서는 apt로 설치할 수 있습니다.

sudo apt install gh

설치가 됐으면 버전을 확인해볼까요?

gh --version

gh version 2.87.3 (2026-02-19)

인증

gh를 사용하려면 먼저 GitHub 계정으로 로그인해야 합니다. gh auth login 명령어를 실행하면 대화형으로 인증 과정을 안내해줍니다.

gh auth login

실행하면 몇 가지 질문이 나옵니다. GitHub.com을 사용한다면 기본값 그대로 엔터를 누르면 되고, 인증 방식은 브라우저를 통한 로그인이 가장 간편합니다.

? What account do you want to log into? GitHub.com
? What is your preferred protocol for Git operations on this host? HTTPS
? Authenticate Git with your GitHub credentials? Yes
? How would you like to authenticate GitHub CLI? Login with a web browser

! First copy your one-time code: XXXX-XXXX
Press Enter to open github.com in your browser...

브라우저에서 코드를 입력하면 인증이 완료됩니다. 이후에는 별도 토큰 관리 없이 gh 명령어를 바로 쓸 수 있어요.

인증이 잘 됐는지 확인해봅시다.

gh auth status

github.com
  ✓ Logged in to github.com account DaleSeo (keyring)
  - Active account: true
  - Git operations protocol: https
  - Token: gho_************************************
  - Token scopes: 'gist', 'read:org', 'repo', 'workflow'

참고로 여러 GitHub 계정을 쓴다면 gh auth login을 다시 실행해서 계정을 추가하고, gh auth switch로 전환할 수도 있습니다.

저장소 관리

gh를 사용하면 저장소를 만들고 복제하는 작업이 훨씬 간결해집니다.

새 저장소를 만들 때는 gh repo create를 쓰면 됩니다.

# 대화형으로 저장소 생성
gh repo create

# 옵션을 직접 지정
gh repo create my-project --public --clone

--public 플래그는 공개 저장소로, --clone은 생성 후 바로 로컬에 복제까지 해줍니다. --private을 쓰면 비공개 저장소가 되고요.

기존 저장소를 복제할 때도 URL을 복사할 필요 없이 소유자/저장소 형식으로 지정하면 됩니다.

gh repo clone DaleSeo/blog

저장소 목록도 한눈에 볼 수 있어요.

# 내 저장소 목록
gh repo list

# 특정 사용자나 조직의 저장소 목록
gh repo list DaleSeo --limit 5

포크(fork)도 명령어 하나로 됩니다.

gh repo fork DaleSeo/blog --clone

원본 저장소를 포크하면서 로컬에 복제까지 한 번에 처리할 수 있어서 오픈소스 기여를 시작할 때 편리합니다.

이슈 관리

이슈 관리는 gh CLI가 특히 빛을 발하는 영역입니다. 브라우저를 열지 않고도 이슈를 만들고 확인하고 닫을 수 있으니까요.

현재 저장소의 이슈 목록부터 확인해볼까요?

gh issue list

Showing 3 of 3 open issues in DaleSeo/blog

ID   TITLE                         LABELS   UPDATED
#42  다크모드 깜빡임 수정          bug      about 2 hours ago
#38  검색 성능 개선                 enhance  about 3 days ago
#35  태그 페이지 SEO 최적화                  about 1 week ago

특정 조건으로 필터링할 수도 있습니다.

# 라벨로 필터링
gh issue list --label "bug"

# 담당자로 필터링
gh issue list --assignee "@me"

# 닫힌 이슈도 보기
gh issue list --state closed --limit 10

새 이슈를 만들 때는 gh issue create를 사용합니다.

# 대화형으로 이슈 생성
gh issue create

# 옵션을 직접 지정
gh issue create --title "버그가 있어요" --body "검색이 안 됩니다"

이슈의 상세 내용을 확인하거나 댓글을 달거나 상태를 바꾸는 것도 간단합니다.

# 이슈 상세 보기
gh issue view 42

# 브라우저에서 열기
gh issue view 42 --web

# 댓글 달기
gh issue comment 42 --body "확인했습니다. 수정 중이에요."

# 이슈 닫기
gh issue close 42

PR 관리

PR 작업은 아마 gh CLI를 가장 많이 쓰게 되는 분야일 겁니다. 브랜치에서 작업을 마치고 PR을 만드는 흐름이 정말 자연스러워요.

현재 브랜치에서 바로 PR을 생성할 수 있습니다.

gh pr create

대화형으로 제목이나 본문, 리뷰어 등을 물어봅니다. 옵션을 직접 지정할 수도 있고요.

gh pr create --title "다크모드 깜빡임 수정" \
  --body "초기 로드 시 깜빡임 현상을 해결했습니다." \
  --reviewer DaleSeo \
  --label "bug"

PR 목록도 바로 볼 수 있습니다.

gh pr list

Showing 2 of 2 open pull requests in DaleSeo/blog

ID   TITLE                   BRANCH               UPDATED
#43  다크모드 깜빡임 수정    fix/dark-mode-flash   about 5 minutes ago
#40  검색 인덱스 개선        feat/search-index     about 1 day ago

다른 사람의 PR을 로컬에서 확인하고 싶을 때는 gh pr checkout이 유용합니다.

# PR 브랜치를 로컬로 체크아웃
gh pr checkout 43

이 명령어 하나로 해당 PR의 브랜치를 가져와서 체크아웃까지 해줍니다. 리모트를 추가하고 fetch하고 checkout하는 과정을 일일이 할 필요가 없어요.

코드 리뷰도 터미널에서 바로 할 수 있습니다.

# PR의 변경 사항 확인
gh pr diff 43

# 리뷰 승인
gh pr review 43 --approve

# 수정 요청
gh pr review 43 --request-changes --body "이 부분 수정이 필요합니다."

PR 병합도 간단합니다.

# 기본 병합
gh pr merge 43

# squash 병합
gh pr merge 43 --squash

# 병합 후 브랜치 삭제
gh pr merge 43 --squash --delete-branch

릴리스 관리

릴리스를 만들고 관리하는 것도 터미널에서 바로 됩니다.

# 릴리스 생성 (커밋 로그로 노트 자동 생성)
gh release create v1.0.0 --generate-notes

# 제목과 본문을 직접 지정
gh release create v1.0.0 --title "v1.0.0" --notes "첫 번째 릴리스입니다."

# 파일을 첨부해서 릴리스
gh release create v1.0.0 ./dist/*.zip

--generate-notes 옵션은 이전 릴리스 이후의 커밋과 PR을 바탕으로 릴리스 노트를 자동 생성해줘서 꽤 편리합니다.

릴리스 목록 확인과 다운로드도 가능합니다.

# 릴리스 목록
gh release list

# 특정 릴리스의 에셋 다운로드
gh release download v1.0.0

GitHub Actions 연동

gh CLI는 CI/CD 워크플로우를 모니터링하고 관리하는 데도 유용합니다.

워크플로우 실행 목록을 한번 봅시다.

gh run list

STATUS  TITLE                  WORKFLOW   BRANCH   EVENT   ID          ELAPSED  AGE
✓       다크모드 깜빡임 수정   CI         fix/dm   push    12827612    2m30s    5m
✓       검색 인덱스 개선       CI         feat/si  push    12827500    3m12s    1h
✗       메인 빌드              E2E Test   main     push    12827488    1m45s    2h

실패한 워크플로우의 로그를 바로 확인할 수 있어서 디버깅이 편합니다.

# 특정 실행의 상세 정보
gh run view 12827488

# 실패한 로그만 확인
gh run view 12827488 --log-failed

워크플로우를 수동으로 트리거하는 것도 됩니다.

gh workflow run ci.yml --ref main

GitHub Actions 워크플로우 파일 안에서 gh CLI를 사용할 수도 있는데요. GITHUB_TOKEN이 자동으로 제공되기 때문에 별도 인증 없이 바로 쓸 수 있습니다.

name: Auto Label
on:
  issues:
    types: [opened]

jobs:
  label:
    runs-on: ubuntu-latest
    permissions:
      issues: write
    steps:
      - name: Add label
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh issue edit ${{ github.event.issue.number }} \
            --add-label "triage" \
            --repo ${{ github.repository }}

이 주제에 대해서는 GitHub Actions의 권한 설정에서 더 자세하게 다루고 있으니 참고해보세요.

gh api로 REST API 호출

gh CLI에 내장된 명령어만으로 부족할 때가 있습니다. 그럴 때 gh api로 GitHub REST API를 직접 호출할 수 있어요. curl과 비슷하지만 인증을 알아서 처리해주고 페이지네이션까지 자동으로 해준다는 게 다릅니다.

# 현재 사용자 정보 조회
gh api user

# 저장소의 최근 커밋 5개
gh api repos/DaleSeo/blog/commits --jq '.[0:5] | .[].commit.message'

# POST 요청으로 이슈 생성
gh api repos/DaleSeo/blog/issues -f title="테스트 이슈" -f body="gh api로 만든 이슈입니다"

--jq 옵션은 JSON 응답을 jq 표현식으로 가공할 수 있게 해줘요. API 응답에서 원하는 필드만 뽑아내거나 변환할 때 유용합니다.

페이지네이션이 필요한 API도 --paginate 플래그 하나로 해결됩니다.

# 모든 이슈를 가져오기 (페이지네이션 자동 처리)
gh api repos/DaleSeo/blog/issues --paginate --jq '.[].title'

curl로 Link 헤더를 파싱해가며 다음 페이지를 요청하던 번거로움이 사라지죠.

검색

gh CLI로 GitHub의 검색 엔진을 터미널에서 바로 활용할 수도 있습니다.

# 저장소 검색
gh search repos "astro blog" --language TypeScript

# 코드 검색
gh search code "getPublishedPosts" --repo DaleSeo/blog

# 이슈 검색
gh search issues "dark mode bug" --state open --limit 5

# PR 검색
gh search prs "fix" --repo DaleSeo/blog --state merged

검색 결과에서 바로 상세 정보를 확인하거나 브라우저로 열어볼 수 있어서 웹사이트를 왔다 갔다 할 필요가 없어요.

유용한 팁

몇 가지 알아두면 편한 기능을 소개할게요.

우선 --web 플래그는 대부분의 명령어에서 사용할 수 있는데, 터미널 결과 대신 브라우저에서 해당 페이지를 열어줍니다. 터미널에서 작업하다가 웹 UI가 필요한 순간에 바로 전환할 수 있어요.

# 현재 저장소를 브라우저에서 열기
gh browse

# 특정 이슈를 브라우저에서 열기
gh issue view 42 --web

# PR을 브라우저에서 열기
gh pr view 43 --web

또한 gh alias로 자주 쓰는 명령어에 단축어를 만들 수 있습니다.

# 내 PR 목록을 보는 단축어
gh alias set my-prs 'pr list --author @me'

# 사용
gh my-prs

그리고 출력 형식을 JSON으로 바꿔서 다른 도구와 조합하는 것도 가능합니다.

# JSON으로 출력
gh issue list --json number,title,labels

# jq와 조합
gh issue list --json number,title --jq '.[] | "\(.number): \(.title)"'

마치며

gh CLI를 쓰면 GitHub 작업 대부분을 터미널에서 해결할 수 있습니다. PR 생성부터 리뷰, 병합까지 흐름이 끊기지 않는 게 가장 큰 장점이에요.

GitHub REST API를 curl로 직접 호출하는 방법이 API 구조를 이해하는 데 도움이 된다면 gh CLI는 그 위에서 실무 생산성을 높여주는 도구입니다. AI에게 GitHub 작업을 맡기고 싶다면 GitHub MCP 서버도 한번 살펴보세요.

더 자세한 명령어와 옵션은 GitHub CLI 공식 매뉴얼에서 확인할 수 있습니다.