참조
상호작용 정책
gh는 비-TTY 컨텍스트에서 올바르게 작동합니다: 페이저를 건너뛰고, ANSI 색상을 제거하며, 프롬프트 대신 유용한 오류 메시지를 빠르게 출력합니다(예: must provide --title and --body when not running interactively). GH_PAGER를 설정하거나 --no-pager를 전달할 필요가 없습니다(해당 플래그는 존재하지 않습니다).
JSON 파싱
gh의 사람이 읽기 쉬운 출력은 열 형식입니다. 구조화된 데이터가 필요하다면:
--json field1,field2,...를 추가하여 구조화된 출력을 가져옵니다.- 필드 목록 없이
--json과 함께 명령어를 실행하면 사용 가능한 전체 필드 집합이 출력되므로, 필요한 필드를 선택하세요. - 별도의
jq로 파이핑하지 않고 필터링하려면--jq '<expr>'을 사용하세요. - 원하는 형태의 텍스트 출력이 필요할 때는 (
--json과 함께)--template '<go-template>'을 사용하세요. 단,--template/-T는 일부 명령어(예:gh pr create -T,gh issue create -T)에서 본문 템플릿 플래그와 충돌할 수 있으므로, 사용하기 전에 항상--help를 확인하세요.
페이지네이션과 자동 잘림
목록 명령어는 결과를 제한합니다.
gh issue list,gh pr list,gh search ...:-L N(--limit N)을 전달하세요. 기본값은 보통 30입니다.gh issue list/gh pr list는--json을 통해totalCount와 같은 집계 합계를 제공하지 않습니다. 실제 합계가 필요하다면gh api graphql을 사용하여totalCount를 쿼리하세요. 그렇지 않으면-L을 현재 호출의 상한선으로 간주하세요.- 원시 API 호출에는
gh api --paginate <path>를 사용하세요.--jq와 (선택적으로)--slurp를 결합하여 하나의 배열로 조합합니다.
저장소 대상 지정
gh는 현재 작업 디렉터리의 git 리모트에서 저장소를 추론합니다.
해결된 CWD 저장소를 재정의하려면 --repo OWNER/REPO (-R)을 전달하세요.
검색 vs 목록
gh search issues|prs|code|repos|commits|users는 GitHub의 검색 인덱스를 사용하며 전체 검색 구문(is:open,author:,label:,repo:owner/name,in:title, ...)을 지원합니다. 전체 쿼리를 따옴표로 묶인 하나의 문자열로 전달하세요.--search와 동일한 방식입니다:gh search issues "is:open author:foo repo:cli/cli". 교차 저장소 또는 작성자/레이블로 필터링된 경우에 사용하는 것이 좋습니다.gh issue list --search "..."및gh pr list --search "..."는 동일한 구문을 허용하지만 하나의 저장소로 범위가 제한됩니다.
--json으로 노출되지 않는 항목은 gh api로 대체
때때로 유용한 데이터가 형식화된 명령어에 포함되지 않는 경우가 있습니다. 예:
- PR의 리뷰 스레드 댓글:
gh api repos/{owner}/{repo}/pulls/{n}/comments(gh pr view의--comments플래그는 이슈 수준 댓글만 표시합니다). - 임의 GraphQL:
gh api graphql -f query='...' -F var=value. - REST 단축키:
gh api repos/{owner}/{repo}/...- 리모트가 감지된 저장소에서 실행할 때{owner}/{repo}자리 표시자가 자동으로 채워집니다. 결정성을 원한다면 리터럴로 전달하세요.
인증
gh auth status는 활성 호스트, 사용자, 그리고 어떤 환경 변수가 적용되고 있는지 출력합니다.gh auth status --json이 지원됩니다.
기타 참고 사항
gh pr checkout <n>은 브랜치를 전환합니다. 읽기만 필요하다면gh pr diff <n>또는gh pr view <n>을 사용하세요.NO_COLOR,CLICOLOR_FORCE,GH_FORCE_TTY가 적용됩니다. 에이전트 환경 내에서 TTY 스타일 출력(색상, 표, 페이저, 상호작용)을 원한다면GH_FORCE_TTY=1을 설정하세요. 필요하지 않으면 설정하지 마세요.