GitHub CLI (gh)
Interaja com o GitHub a partir da linha de comando: repositórios, releases, issues, PRs, discussões, pesquisa, revisão de código e Actions.
Verificado com gh 2.95.0.
Diretrizes do Agente
- Para arquivos ou diretórios remotos conhecidos, use
gh repo read-file/gh repo read-dir(pré-visualização nogh2.95). Para versões mais antigas doghou necessidades somente de API, use o fallback da API de conteúdos em Padrões de API. - Quando uma tarefa exigir pesquisa em vários arquivos ou explorar código desconhecido onde os caminhos não são conhecidos antecipadamente, clone para um diretório temporário (
gh repo clone owner/repo <temp-dir> -- --depth 1) e use ferramentas locais de leitura de arquivos e pesquisa. - Prefira a saída de texto padrão em vez de
--jsonpara leitura/visualização — é mais eficiente em tokens. Use--jsoncom--jqsomente ao extrair campos específicos programaticamente. Para descobrir campos suportados, execute o comando com--jsone sem lista de campos, e então solicite apenas os campos necessários. - Ao visualizar logs ou diffs, escopo a saída primeiro (ex.:
--name-only,--log-failed) antes de buscar o conteúdo completo. - A flag
--repoé desnecessária ao executar dentro de um repositório clonado — o repositório do diretório atual é usado por padrão. Paragh api, use o caminho explícito (repos/OWNER/REPO/...) ou defina a variável de ambienteGH_REPO. - Use este skill para fluxos de trabalho cobertos. Quando uma flag ou campo necessário estiver faltando aqui, um comando falhar com uma flag desconhecida/alterada, ou o comando estiver marcado como pré-visualização, verifique a ajuda desse comando específico (ex.:
gh pr diff --help).
Segurança
- Operações de escrita (
create,edit,comment,review,close,merge,delete,rerun,run cancel,workflow run/enable/disable, mutações de discussão) modificam o estado do GitHub. Confirme com o usuário antes de executar, especialmente em repositórios que você não possui. gh apicom--method POST/PUT/PATCH/DELETEenvia solicitações de escrita. Verifique novamente o endpoint e o payload. O método padrão é GET (seguro); adicionar parâmetros-f/-Fmuda o padrão para POST.- Operações destrutivas (
delete,close,merge --admin) podem ser irreversíveis. Exigem confirmação explícita do usuário.
Pré-requisitos
Verifique se o gh está instalado e autenticado antes de executar comandos:
gh --version
gh auth status
Se não estiver autenticado, guie o usuário através de gh auth login.
Flags Comuns
Estas flags estão disponíveis em muitos grupos de comandos, mas o suporte varia por comando:
--repo OWNER/REPO— Segmentar um repositório diferente (padrão: repositório do diretório atual). Também aceita URLs completas.--json FIELDS— Saída como JSON com campos especificados. Passe sem valor para listar campos disponíveis.--jq EXPRESSION— Filtrar saída JSON usando sintaxe jq. Requer--json.--template STRING— Formatar saída JSON usando um template Go (alternativa ao--jq).--web— Abrir o recurso no navegador em vez de exibir no terminal.--limit N— Número máximo de resultados para comandos de lista (o padrão é geralmente 30).
Repositórios
Visualizar
Exibir a descrição, README, estrelas, detalhamento de linguagem e outros metadados de um repositório.
gh repo view owner/repo
gh repo view owner/repo --json name,description,defaultBranchRef,languages,stargazerCount
Clonar
Clonar um repositório localmente. Configura automaticamente o remote e, para forks, configura o remote upstream.
gh repo clone owner/repo [target-directory]
Ler conteúdo remoto de repositório
Para leituras rápidas de arquivos ou diretórios conhecidos, use os comandos de leitura de repositório (pré-visualização no gh 2.95):
# Arquivo conhecido
gh repo read-file src/main.py --repo owner/repo --ref main
# Diretório conhecido
gh repo read-dir src --repo owner/repo --ref main
# Fallback para versões mais antigas do gh
gh api "repos/OWNER/REPO/contents/src/main.py?ref=main" -H "Accept: application/vnd.github.raw+json"
Para formas de saída, limites de tamanho de arquivo e ressalvas de listagem de diretórios, veja Padrões de API. Para exploração de vários arquivos, clone em vez disso (veja Diretrizes do Agente).
Listar repositórios
Listar repositórios pertencentes a um usuário ou organização, com filtros opcionais de linguagem e visibilidade.
gh repo list owner --limit 30
Releases
Listar
Listar releases em um repositório, ordenados por data de criação (mais recentes primeiro). Padrão: exibir todos os releases, incluindo pré-lançamentos e rascunhos.
gh release list --repo owner/repo --limit 10
Flags:
--exclude-pre-releases— Excluir pré-lançamentos--exclude-drafts— Excluir rascunhos
Campos JSON principais: tagName, name, publishedAt, isLatest, isDraft, isPrerelease, isImmutable
Visualizar (changelog, assets)
Exibir o corpo do changelog, tag, assets e metadados de um release. Omita a tag para visualizar o último release.
gh release view --repo owner/repo # Último release
gh release view v1.2.0 --repo owner/repo # Tag específica
gh release view v1.2.0 --json tagName,body,assets,publishedAt
Campos JSON principais: tagName, name, body, assets, author, publishedAt, isDraft, isPrerelease, isImmutable, url
Issues
Listar
Listar issues em um repositório, filtradas por estado, label, responsável ou consulta de pesquisa. Padrão: apenas issues abertas.
gh issue list --repo owner/repo
gh issue list --repo owner/repo --state all --label bug --assignee @me
gh issue list --repo owner/repo --search "error no:assignee sort:created-asc"
Flags:
--state VALUE—open(padrão),closed,all--label NAME— Filtrar por label (repita para múltiplas)--assignee LOGIN— Filtrar por responsável (@mepara si)--search QUERY— Sintaxe de pesquisa do GitHub
Campos JSON principais: number, title, state, stateReason, author, labels, assignees, createdAt, updatedAt, url
Visualizar
Exibir o título, corpo, labels, responsáveis e status de uma issue. Use --comments para incluir o tópico completo de comentários.
gh issue view 123
gh issue view 123 --comments
gh issue view 123 --json title,body,labels,comments,state
Criar
Criar uma nova issue com título, corpo, labels e responsáveis.
gh issue create --title "Bug: descrição" --body "Detalhes..." --label bug --assignee user1
Editar
Atualizar o título, corpo, labels, responsáveis ou milestone de uma issue. Todas as flags podem ser combinadas em uma única chamada.
Flags:
--title TEXT/--body TEXT— Atualizar título ou corpo--add-label NAME/--remove-label NAME— Modificar labels--add-assignee LOGIN/--remove-assignee LOGIN— Modificar responsáveis--milestone NAME/--remove-milestone— Definir ou remover milestone
Comentar
Adicionar um comentário a uma issue existente.
gh issue comment 123 --body "Texto do comentário"
Fechar / Reabrir
Fechar ou reabrir uma issue. Opcionalmente, especifique um motivo de fechamento e deixe um comentário.
gh issue close 123 --comment "Corrigido no PR #456" --reason "not planned"
gh issue close 123 --duplicate-of 456
gh issue reopen 123
Motivos de fechamento: completed (padrão), not planned, duplicate.
Status
Mostrar um resumo das issues relevantes para você: atribuídas a você, mencionando você e abertas por você.
gh issue status
Para tipos de issue, sub-issues, relacionamentos pai, dependências de bloqueio e seus campos JSON (requer hosts GitHub suportados), veja Referência de Issues.
Pull Requests
Use estes comandos para visualizar e inspecionar PRs. Para criar, mesclar, revisar e gerenciar PRs, veja Referência de Pull Requests.
Listar
Listar pull requests em um repositório, filtrados por estado, autor, label ou consulta de pesquisa. Padrão: apenas PRs abertos.
gh pr list --repo owner/repo
gh pr list --repo owner/repo --state all --author @me --label "needs-review"
gh pr list --repo owner/repo --search "status:success review:required"
gh pr list --repo owner/repo --app dependabot
Flags:
--state VALUE—open(padrão),closed,merged,all--draft— Filtrar por estado de rascunho--author LOGIN/--assignee LOGIN— Filtrar por autor ou responsável--label NAME— Filtrar por label--search QUERY— Sintaxe de pesquisa do GitHub--app NAME— Filtrar por autor do GitHub App (ex.:dependabot)
Campos JSON principais: number, title, state, author, headRefName, baseRefName, labels, reviewDecision, isDraft, statusCheckRollup, files, commits, reviews, url
Visualizar
Exibir o título, corpo, status de revisão, verificações e outros metadados de um PR. Sem argumento, mostra o PR para o branch atual. Use --comments para incluir o tópico de comentários.
gh pr view 123
gh pr view 123 --comments
gh pr view 123 --json title,body,files,commits,reviews,reviewDecision
Status
Mostrar um resumo dos PRs relevantes para você: o PR do branch atual, PRs que você criou e PRs onde sua revisão é solicitada.
gh pr status
Discussões
Use gh discussion para Discussões de repositório (pré-visualização no gh 2.94). Comece com comandos de leitura e verifique flags com --help porque o conjunto de comandos está em pré-visualização:
gh discussion list --repo owner/repo --limit 10
gh discussion view 123 --repo owner/repo --comments
Para criar, editar, comentar, tópicos de resposta, formas de saída JSON e padrões de fallback GraphQL, veja Referência de Discussões.
Pesquisa
Pesquisar no GitHub por issues, PRs, código, commits e repositórios. Use gh issue list / gh pr list para um repositório; use gh search ... para consultas entre repositórios ou em toda a organização.
Para a sintaxe completa de consulta de pesquisa, veja a documentação de pesquisa do GitHub. Para flags específicas de cada subcomando, execute gh search <subcommand> --help.
Limites de taxa: As APIs de pesquisa têm limites de taxa mais rigorosos do que a API principal. A pesquisa de código é a mais restritiva (~10/min autenticado; requer autenticação). Outros comandos de pesquisa permitem ~30/min autenticado ou ~10/min não autenticado. Verifique a cota atual com gh api rate_limit --jq '.resources | {search, code_search}'.
Quando clonar em vez disso: Veja Diretrizes do Agente para quando clonar vs. usar a API.
Bots e apps: Para autores de GitHub App como Dependabot, use --app dependabot; --author dependabot filtra contas de usuário, não autores de app.
Reconhecimento: Ao pesquisar um repositório desconhecido, verifique primeiro sua linguagem primária para selecionar os valores corretos de --extension e --language:
gh repo view owner/repo --json primaryLanguage --jq '.primaryLanguage.name'
Issues
Pesquisar issues entre repositórios usando palavras-chave, labels, estado ou sintaxe de pesquisa do GitHub.
gh search issues "error handling" --repo owner/repo
gh search issues --label bug --state open --assignee @me
gh search issues --app dependabot --repo owner/repo
gh search issues --involves username --comments ">10" --repo owner/repo
Flags principais: --repo, --owner, --state, --label, --assignee, --author, --app, --involves, --comments, --match, --sort, --include-prs.
PRs
Pesquisar pull requests entre repositórios. Suporta filtragem por autor, status de revisão, estado de merge e status de rascunho.
gh search prs "refactor" --repo owner/repo
gh search prs --review-requested @me --state open
gh search prs --app dependabot --repo owner/repo
gh search prs --author username --merged --repo owner/repo
Flags principais: --repo, --owner, --state, --merged, --draft, --author, --assignee, --app, --label, --review, --review-requested, --base, --head, --checks, --sort.
Código
Pesquisar dentro do conteúdo de arquivos em repositórios GitHub. Retorna apenas linhas correspondentes (sem números de linha, sem contexto circundante). Útil para localizar arquivos contendo um padrão, mas acompanhe com leituras de arquivo ou clone o repositório para entender a lógica do código.
Limitações: Usa um mecanismo de pesquisa legado (os resultados podem não corresponder ao github.com). Pesquisa apenas o branch padrão. Apenas arquivos com menos de 384 KB são indexados. Toda consulta deve incluir pelo menos um termo de pesquisa (pesquisas apenas com qualificadores como --extension ts sozinhas falharão). Não suporta --sort ou --order — os resultados são sempre classificados por relevância.
gh search code "functionName" --repo owner/repo
gh search code "createServer" --repo owner/repo --extension ts
gh search code "lint" --repo owner/repo --filename package.json
Flags principais: --repo, --owner, --extension, --filename, --language, --match, --size.
Campos JSON principais: path, repository, sha, textMatches, url.
O campo textMatches fornece contexto de fragmento com posições de correspondência em nível de caractere — use --json path,textMatches quando precisar de mais contexto do que a saída de texto padrão fornece.
Commits
Pesquisar commits por texto de mensagem, autor, data do committer ou hash.
gh search commits "fix bug" --repo owner/repo
gh search commits --author username --committer-date ">2024-01-01"
gh search commits --hash abc1234
Flags principais: --repo, --owner, --author, --committer, --author-date, --committer-date, --author-name, --author-email, --hash, --merge, --sort.
Repositórios
Pesquisar por repositórios por palavra-chave, linguagem, tópico, estrelas, licença ou proprietário. Nota: --repo não está disponível neste subcomando — use --owner para filtrar por proprietário.
gh search repos "keyword" --language python --sort stars --order desc
gh search repos --topic cli --stars ">1000" --language go
Flags principais: --owner, --language, --topic, --stars, --forks, --license, --created, --updated, --match, --sort, --include-forks, --visibility.
Excluindo qualificadores (prefixo de hífen)
Consultas de pesquisa com exclusões como -label:bug precisam de sintaxe especial para evitar interpretação de flag do shell. Todas as flags (ex.: --limit) devem aparecer antes de --; qualquer coisa após -- é interpretada como texto de consulta de pesquisa:
# Shells tipo Unix
gh search issues -- "my query -label:bug"
# PowerShell
gh --% search issues -- "my query -label:bug"
…
[truncado para tradução]