GitHub CLI: La guía completa para dejar de usar el navegador

Dejá de perder tiempo abriendo GitHub en el browser. Con "gh" manejás repos, Pull Requests, Issues, workflows y releases directamente desde la terminal.

🗺️ ¿Qué vas a aprender en este artículo?

Esta guía está pensada para developers y engineers que ya conocen Git y quieren llevar su flujo de trabajo al siguiente nivel. No importa si usás Mac, Linux o Windows — la GitHub CLI funciona en todos.

Al terminar de leerla vas a saber:

• Qué es gh y en qué se diferencia de git
• Gestionar repositorios completos desde la terminal: crear, clonar, forkear y listar
• Manejar el ciclo completo de Pull Requests: crear, revisar, aprobar y mergear sin tocar el navegador
• Crear y cerrar Issues con filtros, labels y assignees
• Disparar y monitorear GitHub Actions en tiempo real, como un tail -f de tu pipeline
• Publicar Releases con assets y notas de cambios
• Usar Gists para compartir snippets y configuraciones
• Gestionar SSH keys directamente desde la terminal
• Un flujo profesional completo: desde crear el repositorio hasta deployar, sin abrir el navegador una sola vez

💡 Nivel: Intermedio — se asume conocimiento básico de Git y terminal.
⏱️ Tiempo estimado de lectura: 20 minutos.

🤔 ¿Qué es la GitHub CLI?

La GitHub CLI (interfaz de línea de comandos de GitHub) es una herramienta oficial desarrollada por GitHub que te permite interactuar con prácticamente todas las funcionalidades de la plataforma directamente desde tu terminal, sin necesidad de abrir el navegador.

Antes de que existiera gh, el flujo de trabajo típico de un developer era algo así:

1. Escribís código en la terminal
2. Hacés git push
3. Abrís el navegador
4. Navegás hasta el repositorio
5. Creás el Pull Request manualmente
6. Volvés a la terminal

Con la GitHub CLI, ese flujo se comprime a dos pasos: git push y gh pr create. Todo desde la misma ventana, sin interrupciones, sin cambiar de contexto.

La CLI no reemplaza a git — son herramientas complementarias. Mientras git maneja el control de versiones local y la sincronización con el remoto, gh maneja todo lo que ocurre sobre el repositorio en la plataforma de GitHub: los Pull Requests, los Issues, los Actions, los Releases y más.

⚙️ Instalación y autenticación

Instalación

# 🍎 macOS
brew install gh

# 🐧 Linux (Debian/Ubuntu)
sudo apt install gh

# 🪟 Windows
winget install GitHub.cli

Para otras distribuciones de Linux o métodos alternativos, podés consultar la documentación oficial.

Una vez instalada, verificá que todo funcionó correctamente:

$ gh version
# gh version 2.45.0 (2025-07-18 Ubuntu 2.45.0-1ubuntu0.3)
# https://github.com/cli/cli/releases/tag/v2.45.0

🔑 Autenticación

Una vez instalada, el primer paso es conectar la CLI con tu cuenta de GitHub:

gh auth login

El comando te guía por un flujo interactivo donde podés autenticarte vía browser o pegando un token de acceso personal. Podés verificar que todo funcionó correctamente con:

gh auth status
# ✓ Logged in to github.com as tu-usuario

📁 Gestión de repositorios

Crear y clonar repos

# Crear un repositorio público
gh repo create mi-proyecto --public

# Crear uno privado y clonarlo automáticamente
gh repo create mi-api --private --clone

# Clonar un repo sin copiar la URL completa
gh repo clone usuario/mi-repo

La ventaja de gh repo clone sobre git clone es que no necesitás copiar la URL: alcanza con escribir usuario/repo y la CLI resuelve el resto.

Fork, view y list

# Forkear un repositorio y clonarlo en un solo comando
gh repo fork usuario/repo --clone

# Ver información del repo actual
gh repo view

# Abrirlo directamente en el navegador
gh repo view --web

# Listar tus repositorios
gh repo list usuario --limit 20

🔀 Pull Requests: el flujo completo desde la terminal

Los Pull Requests son probablemente donde la GitHub CLI aporta más valor. Todo el ciclo de vida de un PR — creación, revisión, aprobación y merge — se puede manejar sin salir de la terminal.

✏️ Crear un PR

# PR básico
gh pr create --title "feat: login con OAuth" --body "Descripción del cambio"

# PR con reviewers y labels
# Nota: para múltiples labels o reviewers, repetí el flag
gh pr create \
  --title "fix: crash en login" \
  --body "Corregido el bug reportado en #15" \
  --reviewer usuario1 \
  --reviewer usuario2 \
  --label bug \
  --label enhancement

🔍 Revisar y trabajar con PRs existentes

# Listar PRs abiertos
gh pr list

# Filtrar por estado o autor
gh pr list --state merged --author "@me"

# Ver detalles de un PR específico
gh pr view 42

# Cambiar a la rama de un PR para revisarlo localmente
gh pr checkout 42

💡 gh pr checkout es especialmente útil: en lugar de tener que buscar el nombre de la rama del PR, simplemente usás el número y la CLI hace todo el trabajo.

Otro comando muy útil para el día a día es gh pr status, que muestra de un vistazo el estado de todos los PRs relacionados con la rama en la que estás parado — los que abriste vos, los que te asignaron para revisar y los que mencionan tu usuario:

gh pr status
# Current branch
#   #42  feat: nueva funcionalidad  [open]
#
# Created by you
#   #38  fix: bug en login  [merged]
#
# Requesting a code review from you
#   #41  chore: actualizar deps  [open]

✅ Revisar y mergear

# Aprobar un PR
gh pr review 42 --approve

# Solicitar cambios con comentario
gh pr review 42 --request-changes --body "Falta manejar el error 404"

# Mergear con squash y eliminar la rama
gh pr merge 42 --squash --delete-branch

# Mergear con rebase
gh pr merge 42 --rebase

🐛 Issues: gestioná bugs y features sin abrir el browser

Los Issues son la forma principal de rastrear bugs, tareas y mejoras en GitHub. Con gh podés crear, filtrar, asignar y cerrar issues sin interrumpir tu flujo en la terminal — y como verás más adelante, también podés integrarlos en scripts de CI para que se creen automáticamente ante un fallo.

# Crear un issue con label y assignee
gh issue create \
  --title "Bug: crash en login" \
  --label bug \
  --assignee "@me"

# Listar issues filtrados por label
gh issue list --label bug

# Ver detalles de un issue
gh issue view 15

# Cerrarlo con un comentario
gh issue close 15 --comment "Resuelto en PR #42"

🤖 Caso de uso DevOps: issues automáticos desde pipelines

Una práctica muy útil es integrar gh issue create en scripts de monitoreo o alertas. Por ejemplo, si un job de CI detecta un error crítico, puede crear automáticamente un issue en el repositorio con los detalles del fallo:

gh issue create \
  --title "🚨 Deploy fallido en producción" \
  --body "El job deploy.yml falló en el step 'Run migrations'. Ver logs: $RUN_URL" \
  --label "bug" \
  --label "producción" \
  --assignee devops-team

⚡ GitHub Actions: controlá tus pipelines desde la terminal

🔧 Workflows

# Ver todos los workflows del repositorio
gh workflow list

# Disparar un workflow manualmente
gh workflow run deploy.yml

# En una rama específica
gh workflow run deploy.yml --ref staging

📊 Monitorear ejecuciones

# Ver las últimas ejecuciones
gh run list

# Filtrar por workflow
gh run list --workflow deploy.yml

# Ver los logs de una ejecución
gh run view 123456 --log

# Monitorear en tiempo real (como un tail -f de tu pipeline)
gh run watch 123456

💡 gh run watch es especialmente poderoso en contextos de CI/CD: podés disparar un deploy con gh workflow run y quedarte mirando el progreso en tiempo real, todo desde la misma sesión de terminal.

🏷️ Releases: publicá versiones sin tocar el navegador

Un Release en GitHub es una versión empaquetada de tu proyecto, asociada a un tag de git. Permite distribuir binarios, documentación y notas de cambios de forma estructurada. Es el mecanismo estándar para publicar versiones de software en GitHub.

# Crear un release estable
gh release create v1.0.0 \
  --title "v1.0.0 — Primera versión estable" \
  --notes "Changelog: autenticación, API REST, Docker support"

# Release con un archivo adjunto (binario, zip, etc.)
gh release create v1.0.0 ./dist/app.zip \
  --title "v1.0.0" \
  --notes "Descargá el binario precompilado"

# Pre-release
gh release create v2.0.0-beta --prerelease

# Listar todos los releases
gh release list

# Descargar los assets de un release
gh release download v1.0.0
gh release download v1.0.0 --pattern "*.zip"

📝 ¿Qué es un Gist?

Un Gist es una forma rápida de compartir fragmentos de código, configuraciones, scripts o notas de texto a través de GitHub. Podés pensarlo como un repositorio ultra-simplificado: tiene soporte para múltiples archivos, versionado con git, y podés hacerlo público (visible para cualquiera) o secreto (accesible solo con el link).

Los Gists son ideales para: - 🤝 Compartir un script de bash con un colega - 🗂️ Guardar configuraciones de herramientas como .vimrc, .zshrc o archivos de Docker Compose - 📌 Publicar snippets de código como referencia rápida - 📓 Tomar notas técnicas versionadas

Gists desde la terminal

# Crear un Gist público desde un archivo
gh gist create script.sh --public --desc "Script de deploy automático"

# Crear un Gist desde múltiples archivos
gh gist create archivo1.sh archivo2.yml --public

# Listar tus Gists
gh gist list

# Ver un Gist específico
gh gist view <gist-id>

# Editar un Gist
gh gist edit <gist-id>

🔑 SSH Keys: agregá tu clave directamente desde la terminal

Si configurás una máquina nueva y necesitás agregar tu clave SSH a GitHub, ya no hace falta que entres a Settings en el browser:

# Generar una clave SSH (si no tenés una)
ssh-keygen -t ed25519 -C "tu@email.com"

# Agregarla a GitHub directamente
gh ssh-key add ~/.ssh/id_ed25519.pub --title "Mi laptop de trabajo"

# Listar las claves registradas
gh ssh-key list

🚀 Flujo profesional: ejemplo completo

Este es un flujo real combinando git y gh desde cero — creando el repositorio hasta el deploy — sin abrir el navegador una sola vez:

# 1️⃣ Crear el repositorio en GitHub y clonarlo localmente en un solo paso
gh repo create mi-org/mi-proyecto \
  --private \
  --clone \
  --description "Mi nuevo proyecto"

cd mi-proyecto

# 2️⃣ Inicializar el proyecto y hacer el primer commit
# gh repo create con --clone ya configura la rama por defecto (main)
echo "# mi-proyecto" > README.md
git add .
git commit -m "chore: initial commit"
git push -u origin main

# 3️⃣ Crear una rama para la nueva funcionalidad
git checkout -b feature/nueva-funcionalidad

# ... escribís el código ...

# 4️⃣ Commitear y pushear la feature
git add .
git commit -m "feat: nueva funcionalidad"
git push origin feature/nueva-funcionalidad

# 5️⃣ Abrir el PR con reviewers directamente desde la terminal
gh pr create \
  --title "feat: nueva funcionalidad" \
  --body "Resuelve #23" \
  --reviewer colega1 \
  --reviewer colega2

# 6️⃣ Verificar que el CI pasó y monitorear en tiempo real
gh run list --limit 1
gh run watch <run-id>

# 7️⃣ Una vez aprobado, mergear y eliminar la rama
gh pr merge --squash --delete-branch

# 8️⃣ Publicar el release con tag y notas
gh release create v1.0.0 \
  --title "v1.0.0 — Primera versión" \
  --notes "Nueva funcionalidad incluida"

# 9️⃣ Disparar el deploy y monitorear
gh workflow run deploy.yml --ref main
gh run watch

💡 Con --clone en gh repo create, GitHub crea el repo remoto y lo clona localmente en un solo comando. No hace falta git init ni configurar el remote manualmente — gh lo deja todo listo.

📋 Resumen de comandos

🏁 Conclusión

La GitHub CLI no es solo un atajo: es un cambio de paradigma en cómo interactuás con la plataforma. Al mantenerte en la terminal durante todo el flujo, eliminás las interrupciones de cambio de contexto que fragmentan la concentración y ralentizan el trabajo.

Si estás construyendo pipelines de CI/CD, automatizando flujos de trabajo o simplemente querés ser más eficiente en tu día a día como developer o engineer, la GitHub CLI es una herramienta que no debería faltar en tu setup.

¿Qué explorar después?

Una vez que tengas gh incorporado a tu flujo diario, hay tres caminos naturales para seguir profundizando:

• Alias de shell — podés crear shortcuts para los comandos que más usás. Por ejemplo: alias pr='gh pr create' o alias prs='gh pr status' en tu .zshrc o .bashrc.
• Integración con scripts de CI/CD — combiná gh issue create y gh run watch en tus pipelines de GitHub Actions para automatizar notificaciones, crear issues ante fallos o disparar deploys encadenados.
• GitHub CLI Extensions — la CLI soporta extensiones de la comunidad instalables con gh extension install. Hay extensiones para dashboards, visualización de workflows, gestión de proyectos y más.

¿Querés profundizar en algún comando o caso de uso específico? Dejá tu consulta en los comentarios o escribinos por las redes.

⚠️ Nota sobre los comandos: todos los ejemplos de este artículo fueron verificados contra la documentación oficial de GitHub CLI. Algunas aclaraciones importantes: "@me" requiere comillas en bash/zsh para que el shell no interprete el @ incorrectamente; para múltiples labels o reviewers hay que repetir el flag (--label bug --label enhancement). Si encontrás alguna diferencia con tu versión instalada, consultala con gh <comando> --help.