SuperAPI AI Directory

gh-cli

Coding & development

View repository

Updated 10-16 07:15

About this skill

GitHub CLI (gh)

Referencia completa de GitHub CLI (gh) para trabajar con GitHub desde la terminal.

Version Check

Documentado para: v2.87.3 (February 2026)

Antes de usar esta referencia, verifica tu version:

gh --version

Si tu version difiere significativamente de v2.87.3, algunos comandos o flags pueden haber cambiado. Consulta gh help <command> para confirmar.

Top Commands (por frecuencia de uso real)

# PRs — el grupo mas usado
gh pr view 123                         # Ver PR (con --web para browser)
gh pr comment 123 --body "LGTM!"      # Comentar PR
gh pr create --draft --title "feat: X" # Crear PR
gh pr diff 123                         # Ver diff
gh pr checks 123 --watch               # Watch CI checks
gh pr review 123 --approve             # Aprobar PR
gh pr merge 123 --squash --delete-branch
gh pr list --author @me --json number,title

# API — segundo mas usado
gh api repos/owner/repo --jq '.stargazers_count'
gh api /user --jq '.login'
gh api graphql -f query='{ viewer { login } }'

# Repos
gh repo view                           # Info del repo actual
gh repo create my-repo --public --clone
gh repo clone owner/repo

# Runs (CI)
gh run view 123456 --log               # Ver logs del run
gh run list --workflow ci.yml --limit 5
gh run watch 123456 --exit-status      # Watch con exit code
gh run rerun 123456                    # Re-ejecutar run fallido

# Search
gh search prs "is:open review:required"
gh search issues "label:bug state:open"
gh search commits "fix critical"

# Auth
gh auth status                         # Ver cuenta activa
gh auth switch                         # Cambiar cuenta
gh auth login                          # Login interactivo

Quick Start

# Instalar
brew install gh          # macOS
# Ver references/auth-config.md para Linux/Windows

# Autenticarse
gh auth login

# Configurar git
gh auth setup-git

# Verificar
gh auth status

CLI Structure

gh
├── auth                    # Autenticacion
│   ├── login, logout, refresh, setup-git, status, switch, token
├── browse                  # Abrir en browser
├── repo                    # Repositorios
│   ├── create, list, clone, view, edit, delete, fork, sync
│   ├── archive, unarchive, rename, set-default
│   └── autolink, deploy-key, gitignore, license
├── issue                   # Issues
│   ├── create, list, view, edit, close, reopen, comment, delete
│   └── develop, lock, unlock, pin, unpin, transfer, status
├── pr                      # Pull Requests
│   ├── create, list, view, checkout, diff, merge, close, reopen
│   ├── edit, comment, review, ready, checks, status
│   └── lock, unlock, revert, update-branch
├── project                 # Projects v2
│   ├── create, list, view, edit, delete, close, copy
│   ├── field-create, field-delete, field-list
│   └── item-add, item-create, item-edit, item-delete, item-list, item-archive
├── release                 # Releases
│   ├── create, list, view, edit, delete, download, upload
│   └── delete-asset, verify, verify-asset
├── run                     # Workflow Runs (Actions)
│   ├── list, view, watch, rerun, cancel, delete, download
├── workflow                # Workflows (Actions)
│   ├── list, view, run, enable, disable
├── cache                   # Actions Caches
│   ├── list, delete
├── secret                  # Actions Secrets
│   ├── list, set, delete
├── variable                # Actions Variables
│   ├── list, get, set, delete
├── gist                    # Gists
│   ├── create, list, view, edit, delete, rename, clone
├── codespace               # Codespaces
│   ├── create, list, view, ssh, code, stop, delete, logs, ports, cp
├── search                  # Busqueda
│   ├── code, commits, issues, prs, repos
├── org                     # Organizaciones
│   └── list
├── label                   # Labels
│   ├── create, list, edit, delete, clone
├── api                     # Requests directos a la API
├── alias                   # Aliases de comandos
│   ├── set, list, delete, import
├── extension               # Extensiones
│   ├── install, list, search, upgrade, remove, create, browse
├── config                  # Configuracion
│   ├── get, set, list, clear-cache
├── ssh-key / gpg-key       # Claves SSH/GPG
├── ruleset                 # Rulesets
│   ├── list, view, check
├── attestation             # Atestaciones de artefactos
├── completion              # Shell completion
├── status                  # Overview de notificaciones
└── agent-task              # Agent tasks (preview)

Que Comando Usar

Necesidad Comando Ejemplo
Crear PR desde branch actual gh pr create gh pr create --title "feat: X" --draft
Ver estado de mis PRs/issues gh pr status / gh issue status gh pr status
Checkout PR de otro dev gh pr checkout gh pr checkout 123
Mergear PR gh pr merge gh pr merge 123 --squash --delete-branch
Crear issue con labels gh issue create gh issue create --title "Bug" --labels bug
Crear branch desde issue gh issue develop gh issue develop 123 --branch fix/123
Ver CI status de un PR gh pr checks gh pr checks 123 --watch
Trigger workflow manual gh workflow run gh workflow run deploy.yml --ref main
Ver logs de un run gh run view gh run view 123 --log
Buscar codigo en GitHub gh search code gh search code "TODO" --repo owner/repo
Hacer request a la API gh api gh api /repos/owner/repo --jq '.stargazers_count'
Crear release con assets gh release create gh release create v1.0 --notes-file CHANGELOG.md *.tar.gz
Gestionar secrets de CI gh secret set echo "$TOKEN" | gh secret set MY_SECRET
Fork + sync gh repo fork + gh repo sync gh repo fork owner/repo --clone

Common Workflows

PR desde Issue

gh issue develop 123 --branch feature/issue-123
# ... hacer cambios, commit, push
gh pr create --title "Fix #123" --body "Closes #123"

Bulk Operations con jq

# Cerrar issues stale
gh issue list --search "label:stale" --json number --jq '.[].number' | \
  xargs -I {} gh issue close {} --comment "Closing as stale"

# Agregar label a PRs pendientes de review
gh pr list --search "review:required" --json number --jq '.[].number' | \
  xargs -I {} gh pr edit {} --add-label needs-review

CI/CD Watch

gh workflow run ci.yml --ref main
gh run list --workflow ci.yml --limit 1 --json databaseId --jq '.[0].databaseId' | \
  xargs -I {} gh run watch {} --exit-status  # exit-status: non-zero si falla (util para scripts)

Nota: Para crear archivos YAML de GitHub Actions, ver la skill github-actions. Esta skill cubre los comandos CLI para interactuar con workflows y runs existentes.

Setup de Repo Nuevo

gh repo create my-project --public --clone --gitignore node --license mit
cd my-project
gh label create bug --color "d73a4a"
gh label create enhancement --color "a2eeef"

Global Flags

Flag Uso
--json FIELDS Output JSON con campos especificos
--jq EXPR Filtrar JSON output (syntax jq)
--template STR Formatear con Go template
--web Abrir en browser
--repo OWNER/REPO Seleccionar otro repo
--hostname HOST GitHub Enterprise hostname
--paginate Paginar resultados grandes

JSON + jq Patterns

# Listar campos disponibles
gh pr list --json 2>&1 | head -5

# Filtrar por condicion
gh pr list --json number,title --jq '.[] | select(.number > 100)'

# Extraer valores anidados
gh repo view --json owner,name --jq '.owner.login + "/" + .name'

# Tab-separated output
gh issue list --json number,title --jq '.[] | [.number, .title] | @tsv'

Best Practices

  1. Set default repo para evitar --repo repetido: gh repo set-default
  2. Usar --json + --jq para scripting — nunca parsear output de texto
  3. GH_TOKEN env var para CI/automation: export GH_TOKEN=$(gh auth token)
  4. --paginate para datasets grandes (default: 30 items)
  5. Shell completion: eval "$(gh completion -s zsh)" en .zshrc
  6. Aliases para comandos frecuentes: gh alias set prview 'pr view --web'

Environment Variables

Variable Uso
GH_TOKEN Token de autenticacion (CI/automation)
GH_HOST Hostname (default: github.com)
GH_REPO Override repo default
GH_EDITOR Editor para mensajes
GH_PAGER Pager para output largo
GH_PROMPT_DISABLED Deshabilitar prompts interactivos

Reference Files

Para referencia detallada de cada grupo de comandos:

  • references/auth-config.md — Autenticacion, configuracion, env setup
  • references/repos.md — Repositorios: create, clone, list, view, edit, fork, sync
  • references/issues.md — Issues: CRUD, labels, pins, locks, transfer, develop
  • references/pull-requests.md — Pull Requests: create, merge, review, checks, diff
  • references/actions.md — GitHub Actions: workflow, run, cache, secret, variable
  • references/projects-releases.md — Projects v2 y Releases
  • references/advanced.md — Gist, codespace, org, search, api, extensions, aliases, rulesets

Help

gh --help              # Ayuda general
gh pr --help           # Ayuda de un comando
gh issue create --help # Ayuda de un subcomando
gh help formatting     # Topics: formatting, environment, exit-codes

Links