GitHub CLI

Administra pull requests, issues, repositorios y flujos de trabajo directamente desde la terminal con gh.

Recipe

Tarjeta de referencia rápida — lista para copiar y pegar.

# Autenticar
gh auth login
 
# Crear un pull request
gh pr create --title "feat: add auth page" --body "Adds login and signup forms"
 
# Listar PRs abiertos
gh pr list
 
# Cambiar a un PR localmente
gh pr checkout 42
 
# Fusionar un PR
gh pr merge 42 --squash --delete-branch
 
# Crear un issue
gh issue create --title "Bug: sidebar flickers" --label bug
 
# Ver repositorio en el navegador
gh browse

Cuándo usarlo: Cualquier operación de GitHub que normalmente harías en el navegador — PRs, issues, releases, Actions.

Working Example

# Flujo completo de PR desde la terminal
git checkout -b feature/search
# ... escribe código ...
git add src/components/Search.tsx src/app/search/page.tsx
git commit -m "feat: add search page with debounced input"
git push -u origin feature/search
 
# Crear PR con cuerpo
gh pr create --title "feat: add search page" --body "## Summary
- Debounced search input with 300ms delay
- Server-side filtering via search params
- Loading skeleton during fetch
 
## Test plan
- [ ] Type in search box, verify debounce
- [ ] Check URL updates with search param
- [ ] Verify loading state appears"
 
# Verificar estado de CI
gh pr checks 42
 
# Ver diff del PR
gh pr diff 42
 
# Fusionar cuando esté listo
gh pr merge 42 --squash --delete-branch

Lo que esto demuestra:

Flujo de trabajo de funcionalidad de extremo a extremo sin abandonar la terminal
El cuerpo del PR soporta Markdown completo
--squash combina todos los commits en un único commit limpio en main
--delete-branch limpia la rama remota después de fusionar

Deep Dive

Comandos de Pull Request

# Crear PR (interactivo — solicita título, cuerpo, revisores)
gh pr create
 
# Crear PR con revisores y labels
gh pr create --title "fix: resolve hydration error" \
  --reviewer teammate1,teammate2 \
  --label "bug,priority:high"
 
# Crear PR en borrador
gh pr create --draft --title "WIP: new dashboard"
 
# Listar PRs con filtros
gh pr list --state open --author @me
gh pr list --label "needs-review"
gh pr list --search "is:open draft:false"
 
# Ver detalles del PR
gh pr view 42
gh pr view 42 --web  # abre en navegador
 
# Revisar un PR
gh pr checkout 42
gh pr review 42 --approve
gh pr review 42 --request-changes --body "Need to handle the loading state"
gh pr review 42 --comment --body "Looks good, minor suggestion on line 45"
 
# Opciones de merge
gh pr merge 42 --merge          # merge commit
gh pr merge 42 --squash         # squash and merge
gh pr merge 42 --rebase         # rebase and merge
gh pr merge 42 --auto --squash  # auto-merge cuando pasen las verificaciones
 
# Cerrar sin fusionar
gh pr close 42

Comandos de Issue

# Crear issue (interactivo)
gh issue create
 
# Crear con labels y asignee
gh issue create \
  --title "Add dark mode support" \
  --body "Users have requested a dark mode toggle in settings." \
  --label "enhancement,ui" \
  --assignee @me
 
# Listar issues
gh issue list
gh issue list --label "bug" --state open
gh issue list --assignee @me
 
# Ver y administrar
gh issue view 15
gh issue close 15
gh issue reopen 15
 
# Agregar un comentario
gh issue comment 15 --body "Fixed in PR #42"
 
# Transferir issue a otro repositorio
gh issue transfer 15 org/other-repo

Comandos de Repositorio

# Clonar un repositorio
gh repo clone owner/repo
 
# Crear un nuevo repositorio
gh repo create my-app --private --clone
gh repo create my-app --public --template nextjs/template
 
# Hacer fork de un repositorio
gh repo fork owner/repo --clone
 
# Ver información del repositorio
gh repo view
gh repo view owner/repo --web
 
# Listar tus repositorios
gh repo list --language typescript --sort updated
 
# Establecer tópicos del repositorio
gh repo edit --add-topic "nextjs,react,typescript"

Comandos de GitHub Actions / Flujos de Trabajo

# Listar ejecuciones de flujo recientes
gh run list
 
# Ver una ejecución específica
gh run view 12345
 
# Observar una ejecución en progreso
gh run watch 12345
 
# Volver a ejecutar un trabajo fallido
gh run rerun 12345 --failed
 
# Disparar un flujo de trabajo manualmente
gh workflow run deploy.yml --ref main
 
# Listar flujos de trabajo
gh workflow list
gh workflow view deploy.yml

Comandos de Release

# Crear un release
gh release create v1.0.0 --title "v1.0.0" --notes "Initial release"
 
# Crear release con notas auto-generadas
gh release create v1.1.0 --generate-notes
 
# Crear un release en borrador
gh release create v2.0.0-beta --draft --prerelease
 
# Listar releases
gh release list
 
# Descargar assets del release
gh release download v1.0.0

Acceso a API

# Llamar a cualquier endpoint REST de GitHub
gh api repos/owner/repo/pulls/42/comments
 
# Crear un comentario vía API
gh api repos/owner/repo/issues/15/comments \
  -f body="Automated comment from CLI"
 
# Consulta GraphQL
gh api graphql -f query='
  query {
    repository(owner: "vercel", name: "next.js") {
      stargazerCount
      description
    }
  }
'
 
# Paginar resultados
gh api repos/owner/repo/issues --paginate --jq '.[].title'

Gotchas

Cosas que te pueden morder. Cada gotcha incluye qué sale mal, por qué sucede y la solución.

Problemas de scope de autenticación — gh devuelve errores 403 para ciertas operaciones. Solución: Vuelve a autenticarte con los scopes requeridos: gh auth login --scopes repo,read:org.
Rama base incorrecta — El PR apunta a la rama base equivocada. Solución: Especifica explícitamente: gh pr create --base main.
Auto-merge no habilitado — gh pr merge --auto falla silenciosamente. Solución: Habilita auto-merge en la configuración del repositorio primero (Settings > General > Allow auto-merge).
Checkout obsoleto — gh pr checkout no extrae los últimos cambios si ya tienes la rama. Solución: Ejecuta git pull después del checkout, o elimina la rama local primero.

Alternatives

Otras formas de resolver el mismo problema — y cuándo cada una es la mejor opción.

Alternativa	Usar Cuando	No Usar Cuando
GitHub web UI	Revisiones complejas de PR con comentarios en línea	Operaciones rápidas o scripting
`hub` CLI (legacy)	Ya integrado en scripts existentes	Nuevos proyectos — `gh` es el sucesor oficial
GitHub API directamente	Integraciones personalizadas o scripts de CI	Flujos de trabajo interactivos en terminal
Extensión GitHub de VS Code	Prefieres una GUI dentro de tu editor	Flujos de trabajo orientados a terminal

FAQs

¿Cómo autentico GitHub CLI por primera vez?

gh auth login

Sigue los prompts interactivos para elegir HTTPS o SSH y autentica vía navegador
Tu token se almacena de forma segura y se reutiliza para comandos posteriores

¿Cómo creo un PR en borrador desde la terminal?

gh pr create --draft --title "WIP: new feature"

Los PRs en borrador señalan que el trabajo no está listo para revisión
Convierte a listo mediante gh pr ready 42

¿Cuál es la diferencia entre --squash, --merge y --rebase al fusionar un PR?

--squash combina todos los commits en un único commit en la rama destino
--merge crea un merge commit preservando todos los commits individuales
--rebase reproduce los commits individualmente encima de la rama destino (historial lineal)

¿Cómo verifico el estado de CI de un PR desde la línea de comandos?

gh pr checks 42

Lista todas las ejecuciones de verificación y su estado pass/fail/pending
Usa gh pr checks 42 --watch para seguir en tiempo real

Gotcha: ¿Por qué gh pr merge --auto falla silenciosamente?

El auto-merge debe estar habilitado primero en la configuración del repositorio
Ve a Settings > General > "Allow auto-merge" y habilítalo
Las reglas de protección de rama con verificaciones requeridas también deben configurarse

¿Cómo creo un issue y me lo asigno a mí mismo?

gh issue create --title "Bug: form validation" --assignee @me --label bug

@me es una abreviatura para tu nombre de usuario de GitHub

¿Puedo llamar a endpoints arbitrarios de la API de GitHub con gh?

gh api repos/owner/repo/pulls/42/comments
gh api graphql -f query='{ viewer { login } }'

gh api maneja la autenticación automáticamente
Soporta tanto endpoints REST como GraphQL

¿Cómo vuelvo a ejecutar solo los trabajos fallidos en un flujo de trabajo de GitHub Actions?

gh run rerun 12345 --failed

Esto ahorra tiempo omitiendo trabajos que ya pasaron

Gotcha: Usé gh pr checkout pero el código está desactualizado. ¿Por qué?

Si ya tenías la rama localmente, gh pr checkout cambia a ella sin extraer
Ejecuta git pull después del checkout para obtener los últimos cambios

¿Cómo creo un PR que apunta a una rama diferente a la predeterminada?

gh pr create --base develop --title "feat: new feature"

Sin --base, el PR apunta a la rama predeterminada del repositorio (normalmente main)

¿Cómo agrego revisores y labels con tags relacionados con TypeScript a un PR?

gh pr create --title "fix: type error in utils" \
  --reviewer teammate1 \
  --label "bug,typescript"

Los labels ya deben existir en el repositorio

¿Cómo listo solo mis PRs abiertos en todos los repositorios?

gh pr list --state open --author @me

Agrega --repo owner/repo para limitar a un repositorio específico

Essential Git Commands — Operaciones Git básicas para uso diario
Merging & Rebasing — Estrategias de integración de ramas
Git Utilities — Stash, bisect, cherry-pick y otras herramientas avanzadas

GitHub CLI

Administra pull requests, issues, repositorios y flujos de trabajo directamente desde la terminal con gh.

Recipe

Tarjeta de referencia rápida — lista para copiar y pegar.

# Autenticar
gh auth login
 
# Crear un pull request
gh pr create --title "feat: add auth page" --body "Adds login and signup forms"
 
# Listar PRs abiertos
gh pr list
 
# Cambiar a un PR localmente
gh pr checkout 42
 
# Fusionar un PR
gh pr merge 42 --squash --delete-branch
 
# Crear un issue
gh issue create --title "Bug: sidebar flickers" --label bug
 
# Ver repositorio en el navegador
gh browse

Cuándo usarlo: Cualquier operación de GitHub que normalmente harías en el navegador — PRs, issues, releases, Actions.

Working Example

# Flujo completo de PR desde la terminal
git checkout -b feature/search
# ... escribe código ...
git add src/components/Search.tsx src/app/search/page.tsx
git commit -m "feat: add search page with debounced input"
git push -u origin feature/search
 
# Crear PR con cuerpo
gh pr create --title "feat: add search page" --body "## Summary
- Debounced search input with 300ms delay
- Server-side filtering via search params
- Loading skeleton during fetch
 
## Test plan
- [ ] Type in search box, verify debounce
- [ ] Check URL updates with search param
- [ ] Verify loading state appears"
 
# Verificar estado de CI
gh pr checks 42
 
# Ver diff del PR
gh pr diff 42
 
# Fusionar cuando esté listo
gh pr merge 42 --squash --delete-branch

Lo que esto demuestra:

Flujo de trabajo de funcionalidad de extremo a extremo sin abandonar la terminal
El cuerpo del PR soporta Markdown completo
--squash combina todos los commits en un único commit limpio en main
--delete-branch limpia la rama remota después de fusionar

Deep Dive

Comandos de Pull Request

# Crear PR (interactivo — solicita título, cuerpo, revisores)
gh pr create
 
# Crear PR con revisores y labels
gh pr create --title "fix: resolve hydration error" \
  --reviewer teammate1,teammate2 \
  --label "bug,priority:high"
 
# Crear PR en borrador
gh pr create --draft --title "WIP: new dashboard"
 
# Listar PRs con filtros
gh pr list --state open --author @me
gh pr list --label "needs-review"
gh pr list --search "is:open draft:false"
 
# Ver detalles del PR
gh pr view 42
gh pr view 42 --web  # abre en navegador
 
# Revisar un PR
gh pr checkout 42
gh pr review 42 --approve
gh pr review 42 --request-changes --body "Need to handle the loading state"
gh pr review 42 --comment --body "Looks good, minor suggestion on line 45"
 
# Opciones de merge
gh pr merge 42 --merge          # merge commit
gh pr merge 42 --squash         # squash and merge
gh pr merge 42 --rebase         # rebase and merge
gh pr merge 42 --auto --squash  # auto-merge cuando pasen las verificaciones
 
# Cerrar sin fusionar
gh pr close 42

Comandos de Issue

# Crear issue (interactivo)
gh issue create
 
# Crear con labels y asignee
gh issue create \
  --title "Add dark mode support" \
  --body "Users have requested a dark mode toggle in settings." \
  --label "enhancement,ui" \
  --assignee @me
 
# Listar issues
gh issue list
gh issue list --label "bug" --state open
gh issue list --assignee @me
 
# Ver y administrar
gh issue view 15
gh issue close 15
gh issue reopen 15
 
# Agregar un comentario
gh issue comment 15 --body "Fixed in PR #42"
 
# Transferir issue a otro repositorio
gh issue transfer 15 org/other-repo

Comandos de Repositorio

# Clonar un repositorio
gh repo clone owner/repo
 
# Crear un nuevo repositorio
gh repo create my-app --private --clone
gh repo create my-app --public --template nextjs/template
 
# Hacer fork de un repositorio
gh repo fork owner/repo --clone
 
# Ver información del repositorio
gh repo view
gh repo view owner/repo --web
 
# Listar tus repositorios
gh repo list --language typescript --sort updated
 
# Establecer tópicos del repositorio
gh repo edit --add-topic "nextjs,react,typescript"

Comandos de GitHub Actions / Flujos de Trabajo

# Listar ejecuciones de flujo recientes
gh run list
 
# Ver una ejecución específica
gh run view 12345
 
# Observar una ejecución en progreso
gh run watch 12345
 
# Volver a ejecutar un trabajo fallido
gh run rerun 12345 --failed
 
# Disparar un flujo de trabajo manualmente
gh workflow run deploy.yml --ref main
 
# Listar flujos de trabajo
gh workflow list
gh workflow view deploy.yml

Comandos de Release

# Crear un release
gh release create v1.0.0 --title "v1.0.0" --notes "Initial release"
 
# Crear release con notas auto-generadas
gh release create v1.1.0 --generate-notes
 
# Crear un release en borrador
gh release create v2.0.0-beta --draft --prerelease
 
# Listar releases
gh release list
 
# Descargar assets del release
gh release download v1.0.0

Acceso a API

# Llamar a cualquier endpoint REST de GitHub
gh api repos/owner/repo/pulls/42/comments
 
# Crear un comentario vía API
gh api repos/owner/repo/issues/15/comments \
  -f body="Automated comment from CLI"
 
# Consulta GraphQL
gh api graphql -f query='
  query {
    repository(owner: "vercel", name: "next.js") {
      stargazerCount
      description
    }
  }
'
 
# Paginar resultados
gh api repos/owner/repo/issues --paginate --jq '.[].title'

Gotchas

Cosas que te pueden morder. Cada gotcha incluye qué sale mal, por qué sucede y la solución.

Problemas de scope de autenticación — gh devuelve errores 403 para ciertas operaciones. Solución: Vuelve a autenticarte con los scopes requeridos: gh auth login --scopes repo,read:org.
Rama base incorrecta — El PR apunta a la rama base equivocada. Solución: Especifica explícitamente: gh pr create --base main.
Auto-merge no habilitado — gh pr merge --auto falla silenciosamente. Solución: Habilita auto-merge en la configuración del repositorio primero (Settings > General > Allow auto-merge).
Checkout obsoleto — gh pr checkout no extrae los últimos cambios si ya tienes la rama. Solución: Ejecuta git pull después del checkout, o elimina la rama local primero.

Alternatives

Otras formas de resolver el mismo problema — y cuándo cada una es la mejor opción.

Alternativa	Usar Cuando	No Usar Cuando
GitHub web UI	Revisiones complejas de PR con comentarios en línea	Operaciones rápidas o scripting
`hub` CLI (legacy)	Ya integrado en scripts existentes	Nuevos proyectos — `gh` es el sucesor oficial
GitHub API directamente	Integraciones personalizadas o scripts de CI	Flujos de trabajo interactivos en terminal
Extensión GitHub de VS Code	Prefieres una GUI dentro de tu editor	Flujos de trabajo orientados a terminal

FAQs

¿Cómo autentico GitHub CLI por primera vez?

gh auth login

Sigue los prompts interactivos para elegir HTTPS o SSH y autentica vía navegador
Tu token se almacena de forma segura y se reutiliza para comandos posteriores

¿Cómo creo un PR en borrador desde la terminal?

gh pr create --draft --title "WIP: new feature"

Los PRs en borrador señalan que el trabajo no está listo para revisión
Convierte a listo mediante gh pr ready 42

¿Cuál es la diferencia entre --squash, --merge y --rebase al fusionar un PR?

--squash combina todos los commits en un único commit en la rama destino
--merge crea un merge commit preservando todos los commits individuales
--rebase reproduce los commits individualmente encima de la rama destino (historial lineal)

¿Cómo verifico el estado de CI de un PR desde la línea de comandos?

gh pr checks 42

Lista todas las ejecuciones de verificación y su estado pass/fail/pending
Usa gh pr checks 42 --watch para seguir en tiempo real

Gotcha: ¿Por qué gh pr merge --auto falla silenciosamente?

El auto-merge debe estar habilitado primero en la configuración del repositorio
Ve a Settings > General > "Allow auto-merge" y habilítalo
Las reglas de protección de rama con verificaciones requeridas también deben configurarse

¿Cómo creo un issue y me lo asigno a mí mismo?

gh issue create --title "Bug: form validation" --assignee @me --label bug

@me es una abreviatura para tu nombre de usuario de GitHub

¿Puedo llamar a endpoints arbitrarios de la API de GitHub con gh?

gh api repos/owner/repo/pulls/42/comments
gh api graphql -f query='{ viewer { login } }'

gh api maneja la autenticación automáticamente
Soporta tanto endpoints REST como GraphQL

¿Cómo vuelvo a ejecutar solo los trabajos fallidos en un flujo de trabajo de GitHub Actions?

gh run rerun 12345 --failed

Esto ahorra tiempo omitiendo trabajos que ya pasaron

Gotcha: Usé gh pr checkout pero el código está desactualizado. ¿Por qué?

Si ya tenías la rama localmente, gh pr checkout cambia a ella sin extraer
Ejecuta git pull después del checkout para obtener los últimos cambios

¿Cómo creo un PR que apunta a una rama diferente a la predeterminada?

gh pr create --base develop --title "feat: new feature"

Sin --base, el PR apunta a la rama predeterminada del repositorio (normalmente main)

¿Cómo agrego revisores y labels con tags relacionados con TypeScript a un PR?

gh pr create --title "fix: type error in utils" \
  --reviewer teammate1 \
  --label "bug,typescript"

Los labels ya deben existir en el repositorio

¿Cómo listo solo mis PRs abiertos en todos los repositorios?

gh pr list --state open --author @me

Agrega --repo owner/repo para limitar a un repositorio específico

Essential Git Commands — Operaciones Git básicas para uso diario
Merging & Rebasing — Estrategias de integración de ramas
Git Utilities — Stash, bisect, cherry-pick y otras herramientas avanzadas

GitHub CLI

Buscar en la documentación

GitHub CLI