GitHub CLI: o gh no terminal
O GitHub CLI é a ferramenta de linha de comando de código aberto do GitHub, chamada pelo comando gh, que leva pull requests, issues, workflows do Actions e releases para o terminal. Ele conversa com a API do GitHub usando o token da sua autenticação, por isso o mesmo comando que você digita funciona dentro de um script, de um agente ou de um job do Actions.
Ficha e sumário da página
- Referência técnica
- GitHub CLI v2.104.0
- Revisão
- 13 de novembro de 2026
- Conteúdo
- Documentação oficial consultada
Uma ferramenta para o GitHub, separada do Git
O Git cuida do histórico local, dos commits às branches enviadas com push. O GitHub CLI cuida do que existe só na plataforma, como o pull request e a release. Pela documentação oficial, o gh leva para o terminal os pull requests e as issues, junto com o GitHub Actions e outros recursos da plataforma. Os dois convivem no mesmo fluxo: o git push envia a branch e o gh pr create abre a proposta de merge a partir dela.
O projeto é aberto, com código no repositório cli/cli sob licença MIT. Ele roda no macOS, no Windows e no Linux, com instalação pelo Homebrew, pelo WinGet, pelos pacotes oficiais para Debian, Ubuntu e as distribuições baseadas em RPM ou por binários pré-compilados de cada release. O gh funciona com o GitHub.com, com o GitHub Enterprise Cloud e com as versões suportadas do GitHub Enterprise Server. Nos runners hospedados do GitHub Actions, a ferramenta já vem instalada.
A versão de referência deste portal é a v2.104.0, publicada em 12 de novembro de 2026. Ela trouxe uma confirmação extra no gh repo delete para repositórios privados ou internos com forks. Na mesma versão, o gh auth status mostra no terminal o erro original quando a falha vem do limite de requisições, do servidor ou da rede.
Os grupos de comandos
O gh agrupa os comandos por recurso do GitHub. Cada grupo tem subcomandos para criar, listar, ver e alterar aquele recurso. A grade abaixo reúne os grupos que aparecem no caminho do commit à release, com os nomes do manual da v2.104.0:
gh repoClona, cria, mostra e apaga repositórios.gh prAbre, revisa, confere as checagens e faz o merge de pull requests.gh issueAbre, lista, comenta e fecha issues.gh runLista e acompanha as execuções dos workflows do Actions.gh releaseCria, lista, mostra e baixa releases.gh apiChama qualquer endpoint da API do GitHub com a sua autenticação.
O manual lista outros grupos, como gh secret e gh variable para os valores do Actions, gh workflow para disparar workflows manuais, gh ruleset para os rulesets das branches e gh extension para os comandos criados pela comunidade. O gh api cobre o que nenhum grupo cobre: ele faz a requisição autenticada para qualquer endpoint da API REST ou GraphQL e devolve o JSON, que um script lê para consultar o que a interface não mostra.
Autenticação e escolha do repositório
O gh auth login autentica o terminal no GitHub e guarda o token para os próximos comandos. Em scripts e jobs, o token chega por variável de ambiente: o GH_TOKEN tem prioridade sobre as credenciais guardadas, com o GITHUB_TOKEN aceito como segunda opção. Num job do Actions, a documentação orienta definir GH_TOKEN com o valor de secrets.GITHUB_TOKEN em cada passo que chama o gh, o que entrega ao comando o token criado para aquele job. O repositório vem da pasta atual: dentro de um clone, o gh lê o remoto e sabe em qual repositório agir.
As variáveis de ambiente mudam esse comportamento sem alterar o comando. O arquivo abaixo reúne as que mais aparecem em scripts e agentes, separadas pelo que cada uma controla. A lista completa, com as 34 variáveis da v2.104.0, está na página de variáveis de ambiente do GitHub CLI:
.env do script
Autenticação e alvo
GH_TOKEN=- Token de acesso usado no lugar da autenticação guardada pelo gh auth login.
GH_HOST=- O host do GitHub, como um Enterprise Server, quando o comando não informa e a pasta atual não indica qual é.
GH_REPO=- O repositório alvo no formato [HOST/]DONO/REPO, para comandos que agiriam no repositório da pasta atual.
Execução sem interação
GH_PROMPT_DISABLED=- Desliga as perguntas interativas, para o script não parar esperando resposta.
GH_PAGER=- O programa de paginação que recebe a saída padrão, como o less.
NO_COLOR=- Com qualquer valor, tira as cores da saída, útil em logs de CI e em arquivos.
O gh em scripts e agentes
O comando que você digita à mão também roda numa automação. A opção --json de comandos como gh pr list e gh release view devolve campos escolhidos em JSON. A opção --jq filtra esse JSON na própria chamada. Um script de release, por exemplo, confere se a tag já tem release com gh release view e só cria uma nova quando a consulta falha.
Os agentes de código usam o gh pelo mesmo caminho. O repositório cli/cli descreve uma skill de agente para conduzir o gh a partir de agentes de código, instalada com gh skill install. A nota da v2.104.0 cita esses agentes de forma direta: um workflow sem interação ou um agente que apaga um repositório privado com forks precisa declarar a opção --accept-cascading-deletion-of-private-forks, mesmo com --yes, porque os forks privados somem junto.
As releases do próprio gh aparecem no changelog do GitHub CLI, com um artigo em português para cada versão. O próximo assunto é o que o GitHub vigia no repositório sem você chamar nenhum comando: os alertas de dependências, os segredos expostos e os avisos de segurança, na página Segurança do repositório.