# GitHub CLI 빠른 참조

*저장소, 이슈, PR, Actions, 릴리즈, API*

> Source: GitHub CLI Documentation (cli.github.com) · MIT

## 설정

### 설치

| Command | Description |
|---------|-------------|
| `brew install gh` | macOS - Homebrew |
| `sudo apt install gh` | Debian / Ubuntu |
| `winget install GitHub.cli` | Windows - winget |
| `conda install gh` | conda-forge |

### 인증

```
gh auth login                  # interactive login
gh auth login --with-token < token.txt
gh auth status                 # check auth state
gh auth refresh -s repo,gist   # add scopes
```

### 설정

```
gh config set editor vim
gh config set pager less
gh config set git_protocol ssh
gh config list
```

## 저장소

### 저장소 명령

```
gh repo create my-app --public --clone
gh repo clone owner/repo
gh repo fork owner/repo --clone
gh repo view owner/repo --web
```

### 저장소 옵션

| Command | Description |
|---------|-------------|
| `--public \| --private` | 저장소 공개 여부 설정 |
| `--template owner/repo` | 템플릿 저장소에서 생성 |
| `--clone` | 생성 후 클론 |
| `--add-readme` | README로 초기화 |
| `gh repo list owner` | 소유자의 저장소 목록 |
| `gh repo delete owner/repo` | 저장소 삭제 (확인 필요) |
| `gh repo rename new-name` | 현재 저장소 이름 변경 |
| `gh repo archive owner/repo` | 저장소 아카이브 |

## 이슈

### 이슈 관리

```
gh issue create --title "Bug" --body "Details here"
gh issue list --state open --label bug
gh issue view 42
gh issue close 42 --reason completed
```

### 이슈 옵션

| Command | Description |
|---------|-------------|
| `--assignee @me` | 본인에게 할당 |
| `--label bug,urgent` | 레이블 추가 |
| `--milestone v2.0` | 마일스톤 설정 |
| `--project "Board"` | 프로젝트에 추가 |
| `gh issue edit 42` | 이슈 대화형 편집 |
| `gh issue reopen 42` | 닫힌 이슈 다시 열기 |
| `gh issue comment 42 -b "msg"` | 이슈에 댓글 추가 |
| `gh issue pin 42` | 이슈 저장소에 고정 |

## 풀 리퀘스트

### PR 생성 & 관리

```
gh pr create --title "feat: add auth" --body "..."
gh pr create --fill          # title/body from commits
gh pr list --state open
gh pr view 123 --web
```

### 리뷰 & 머지

```
gh pr checkout 123           # check out PR branch
gh pr diff 123               # view PR diff
gh pr review 123 --approve
gh pr merge 123 --squash --delete-branch
```

### PR 옵션

| Command | Description |
|---------|-------------|
| `--draft` | 드래프트 PR로 생성 |
| `--reviewer user1,user2` | 리뷰어 요청 |
| `--base main` | 베이스 브랜치 설정 |
| `--merge \| --squash \| --rebase` | 머지 전략 |
| `--auto` | 검사 통과 시 자동 머지 |
| `--delete-branch` | 머지 후 브랜치 삭제 |
| `gh pr ready 123` | 드래프트 PR을 준비 완료로 표시 |

## Actions

### 워크플로우 명령

```
gh run list                         # recent runs
gh run view 12345                   # run details
gh run view 12345 --log-failed      # failed step logs
gh run watch 12345                  # live status
```

### 실행 & 관리

```
gh workflow run deploy.yml --ref main
gh workflow list
gh workflow view deploy.yml
gh run rerun 12345 --failed   # rerun failed jobs
```

### Actions 옵션

| Command | Description |
|---------|-------------|
| `-f key=value` | workflow_dispatch에 입력 전달 |
| `--json` | JSON으로 출력 |
| `-b branch` | 브랜치로 필터 |
| `gh run download 12345` | 실행 아티팩트 다운로드 |
| `gh cache list` | Actions 캐시 목록 |
| `gh cache delete KEY` | 캐시 항목 삭제 |

## 릴리즈

### 릴리즈 관리

```
gh release create v1.0.0 --generate-notes
gh release create v1.0.0 ./dist/*.tar.gz
gh release list
gh release view v1.0.0
```

### 릴리즈 옵션

| Command | Description |
|---------|-------------|
| `--title "Release v1.0"` | 릴리즈 제목 설정 |
| `--notes "Changelog here"` | 릴리즈 노트 인라인 설정 |
| `--notes-file CHANGELOG.md` | 파일에서 노트 가져오기 |
| `--generate-notes` | 커밋에서 자동 생성 |
| `--draft` | 드래프트로 생성 |
| `--prerelease` | 사전 릴리즈로 표시 |
| `--latest` | 최신 릴리즈로 표시 |
| `gh release download v1.0.0` | 릴리즈 에셋 다운로드 |
| `gh release delete v1.0.0` | 릴리즈 삭제 |
| `gh release edit v1.0.0` | 릴리즈 메타데이터 편집 |

## Gist

### Gist 명령

```
gh gist create file.py -d "My snippet"
gh gist create file1.js file2.js   # multi-file gist
gh gist list
gh gist view <id>
```

### Gist 옵션

| Command | Description |
|---------|-------------|
| `-d "description"` | Gist 설명 설정 |
| `--public` | 공개 Gist 생성 (기본: 비공개) |
| `--web` | 브라우저에서 Gist 열기 |
| `gh gist edit <id>` | Gist 파일 편집 |
| `gh gist clone <id>` | Gist 로컬 클론 |
| `gh gist delete <id>` | Gist 삭제 |

## API

### API 호출

```
gh api repos/owner/repo
gh api repos/owner/repo/issues --method POST \
  -f title="Bug" -f body="Details"
gh api graphql -f query='{ viewer { login } }'
```

### 출력 형식 지정

```
gh api repos/owner/repo --jq '.stargazers_count'
gh api repos/owner/repo --template '{{.full_name}}'
gh pr list --json number,title --jq '.[].title'
```

### API 옵션

| Command | Description |
|---------|-------------|
| `--method GET\|POST\|PUT\|DELETE` | HTTP 메서드 |
| `-f key=value` | 문자열 필드 설정 |
| `-F key=@file` | 파일에서 필드 설정 |
| `--jq 'expression'` | jq 문법으로 JSON 필터 |
| `--template 'tmpl'` | Go 템플릿으로 형식 지정 |
| `--paginate` | 모든 페이지 가져오기 |
| `-H 'Accept: ...'` | 커스텀 헤더 설정 |

## 별칭

### 별칭 관리

```
gh alias set co 'pr checkout'
gh alias set bugs 'issue list --label bug'
gh alias set last 'run list -L 1'
gh alias list
```

### 고급 별칭

```
# Alias with shell command
gh alias set --shell pv 'gh pr view --json url --jq .url | pbcopy'

# Delete alias
gh alias delete co
```

### 별칭 팁

| Command | Description |
|---------|-------------|
| `gh alias set name 'cmd'` | 단순 별칭 생성 |
| `--shell` | 셸을 통해 실행 (파이프 지원) |
| `gh alias list` | 정의된 모든 별칭 표시 |
| `gh alias delete name` | 별칭 제거 |

## 일반 패턴

### 일상 워크플로우

```
gh issue list --assignee @me        # my open issues
gh pr status                        # PRs needing attention
gh pr checks 123                    # CI status for PR
gh run list -b main -L 5            # recent CI runs
```

### 검색

```
gh search repos --language rust --stars ">1000"
gh search issues --repo owner/repo "memory leak"
gh search prs --state open --review required
```

### 유용한 플래그

| Command | Description |
|---------|-------------|
| `--json field1,field2` | 특정 필드를 JSON으로 출력 |
| `--jq 'expr'` | JSON 출력 필터 |
| `-L N` | 결과를 N개로 제한 |
| `--web` | 브라우저에서 결과 열기 |
| `-R owner/repo` | 특정 저장소 대상 지정 |
| `GH_TOKEN=xxx` | 환경 변수로 인증 |