GitHub CLI (gh) — Guía de inicio

Instalación

# macOS
brew install gh

# Windows (con winget)
winget install --id GitHub.cli

# Windows (con Scoop)
scoop install gh

# Linux (Debian/Ubuntu)
sudo apt install gh

# O desde https://cli.github.com

Autenticación

gh auth login

Te pregunta:

1. What account? → GitHub.com
2. Preferred protocol? → HTTPS
3. Authenticate Git with your GitHub credentials? → Yes
4. How would you like to authenticate? → Login with a web browser (recomendado)

Para verificar:

gh auth status

Repositorios

gh repo create mi-proyecto --public --description "Mi proyecto" --clone
# --private / --internal
# --add-readme
# --gitignore node
# --license mit

gh repo clone usuario/repo                       # clonar
gh repo fork usuario/repo                        # fork
gh repo view usuario/repo --web                  # abrir en navegador
gh repo edit --description "Nueva descripción"   # editar metadata

Issues

gh issue create --title "Bug en X" --body "Pasos para reproducir..." --label bug
gh issue list                                     # listar
gh issue list --label bug --state open           # filtrar
gh issue view 42                                  # ver detalle
gh issue close 42 --comment "Resuelto en #123"   # cerrar
gh issue reopen 42                                # reabrir
gh issue delete 42                                # borrar

Pull Requests

gh pr create --title "Feature X" --body "Descripción..." --base main
gh pr list                                         # listar PRs
gh pr view 42                                      # ver detalle
gh pr checkout 42                                  # bajar PR localmente
gh pr review 42 --approve                         # aprobar
gh pr review 42 --request-changes --body "..."
gh pr merge 42                                     # mergear (merge commit)
gh pr merge 42 --squash                            # merge con squash
gh pr merge 42 --rebase                            # merge con rebase
gh pr close 42                                     # cerrar sin mergear

Workflows (Actions)

gh workflow list                                  # listar workflows
gh workflow view deploy.yml                       # ver detalle
gh workflow run deploy.yml                        # lanzar manualmente
gh workflow enable deploy.yml                     # habilitar
gh workflow disable deploy.yml                    # deshabilitar
gh run list                                        # listar ejecuciones
gh run view 12345                                  # ver ejecución
gh run watch 12345                                 # seguir en vivo
gh run rerun 12345                                 # re-ejecutar
gh run cancel 12345                                # cancelar

Releases

gh release create v1.0.0 --notes "Primera versión estable"
gh release list
gh release upload v1.0.0 ./build/*.zip            # subir binarios
gh release delete v1.0.0

Gists (snippets)

gh gist create ./script.py --public --desc "Script útil"
gh gist list
gh gist view <id>
gh gist clone <id>

Aliases (atajos personalizados)

gh alias set prs 'pr list --author @me --state open'
gh alias set pv 'pr view'
gh alias set co 'pr checkout'

# Ahora puedes hacer:
gh prs
gh pv 42
gh co 42

Aliases de git extendidos

gh añade comandos a git:

git pr create            # = gh pr create
git issue list           # = gh issue list
git repo view            # = gh repo view

Scripting con JSON

Casi todos los comandos aceptan --json para scripting:

gh issue list --json number,title,labels --jq '.[] | select(.labels | length > 0) | .number'
gh pr list --json number,title,author --jq '.[] | "\(.number): \(.title) by \(.author.login)"'

Recursos

• Documentación oficial
• Manual completo