# Referencia Rápida de GitHub CLI

*Repos, issues, PRs, actions, releases, API*

> Source: GitHub CLI Documentation (cli.github.com) · MIT

## Configuración

### Instalación

| Command | Description |
|---------|-------------|
| `brew install gh` | macOS con Homebrew |
| `sudo apt install gh` | Debian / Ubuntu |
| `winget install GitHub.cli` | Windows con winget |
| `conda install gh` | Con conda-forge |

### Autenticación

```
gh auth login                  # login interactivo
gh auth login --with-token < token.txt
gh auth status                 # verificar estado de auth
gh auth refresh -s repo,gist   # agregar scopes
```

### Configuración

```
gh config set editor vim
gh config set pager less
gh config set git_protocol ssh
gh config list
```

## Repos

### Comandos de repositorio

```
gh repo create my-app --public --clone
gh repo clone owner/repo
gh repo fork owner/repo --clone
gh repo view owner/repo --web
```

### Opciones de repo

| Command | Description |
|---------|-------------|
| `--public \| --private` | Establecer visibilidad del repositorio |
| `--template owner/repo` | Crear desde repositorio plantilla |
| `--clone` | Clonar después de crear |
| `--add-readme` | Inicializar con README |
| `gh repo list owner` | Listar repos de un propietario |
| `gh repo delete owner/repo` | Eliminar repositorio (con confirmación) |
| `gh repo rename new-name` | Renombrar repo actual |
| `gh repo archive owner/repo` | Archivar un repositorio |

## Issues

### Gestionar issues

```
gh issue create --title "Bug" --body "Details here"
gh issue list --state open --label bug
gh issue view 42
gh issue close 42 --reason completed
```

### Opciones de issue

| Command | Description |
|---------|-------------|
| `--assignee @me` | Asignar a ti mismo |
| `--label bug,urgent` | Agregar etiquetas |
| `--milestone v2.0` | Establecer milestone |
| `--project "Board"` | Agregar a proyecto |
| `gh issue edit 42` | Editar issue de forma interactiva |
| `gh issue reopen 42` | Reabrir issue cerrado |
| `gh issue comment 42 -b "msg"` | Agregar comentario al issue |
| `gh issue pin 42` | Fijar issue en el repo |

## Pull Requests

### Crear y gestionar PRs

```
gh pr create --title "feat: add auth" --body "..."
gh pr create --fill          # título/body desde commits
gh pr list --state open
gh pr view 123 --web
```

### Revisar y hacer merge

```
gh pr checkout 123           # obtener rama del PR
gh pr diff 123               # ver diff del PR
gh pr review 123 --approve
gh pr merge 123 --squash --delete-branch
```

### Opciones de PR

| Command | Description |
|---------|-------------|
| `--draft` | Crear como PR borrador |
| `--reviewer user1,user2` | Solicitar revisores |
| `--base main` | Establecer rama base |
| `--merge \| --squash \| --rebase` | Estrategia de merge |
| `--auto` | Habilitar auto-merge cuando pasen los checks |
| `--delete-branch` | Eliminar rama tras el merge |
| `gh pr ready 123` | Marcar PR borrador como listo |

## Actions

### Comandos de workflow

```
gh run list                         # ejecuciones recientes
gh run view 12345                   # detalles de ejecución
gh run view 12345 --log-failed      # logs de steps fallidos
gh run watch 12345                  # estado en tiempo real
```

### Activar y gestionar

```
gh workflow run deploy.yml --ref main
gh workflow list
gh workflow view deploy.yml
gh run rerun 12345 --failed   # re-ejecutar jobs fallidos
```

### Opciones de Actions

| Command | Description |
|---------|-------------|
| `-f key=value` | Pasar entrada al workflow_dispatch |
| `--json` | Salida como JSON |
| `-b branch` | Filtrar por rama |
| `gh run download 12345` | Descargar artefactos de la ejecución |
| `gh cache list` | Listar cachés de Actions |
| `gh cache delete KEY` | Eliminar una entrada de caché |

## Releases

### Gestionar releases

```
gh release create v1.0.0 --generate-notes
gh release create v1.0.0 ./dist/*.tar.gz
gh release list
gh release view v1.0.0
```

### Opciones de release

| Command | Description |
|---------|-------------|
| `--title "Release v1.0"` | Establecer título del release |
| `--notes "Changelog here"` | Establecer notas del release en línea |
| `--notes-file CHANGELOG.md` | Notas desde archivo |
| `--generate-notes` | Auto-generar desde commits |
| `--draft` | Crear como borrador |
| `--prerelease` | Marcar como pre-release |
| `--latest` | Marcar como último release |
| `gh release download v1.0.0` | Descargar assets del release |
| `gh release delete v1.0.0` | Eliminar un release |
| `gh release edit v1.0.0` | Editar metadatos del release |

## Gists

### Comandos de gist

```
gh gist create file.py -d "My snippet"
gh gist create file1.js file2.js   # gist de múltiples archivos
gh gist list
gh gist view <id>
```

### Opciones de gist

| Command | Description |
|---------|-------------|
| `-d "description"` | Establecer descripción del gist |
| `--public` | Crear gist público (por defecto: secreto) |
| `--web` | Abrir gist en el navegador |
| `gh gist edit <id>` | Editar archivos del gist |
| `gh gist clone <id>` | Clonar gist localmente |
| `gh gist delete <id>` | Eliminar un gist |

## API

### Hacer llamadas a la API

```
gh api repos/owner/repo
gh api repos/owner/repo/issues --method POST \
  -f title="Bug" -f body="Details"
gh api graphql -f query='{ viewer { login } }'
```

### Formatear salida

```
gh api repos/owner/repo --jq '.stargazers_count'
gh api repos/owner/repo --template '{{.full_name}}'
gh pr list --json number,title --jq '.[].title'
```

### Opciones de API

| Command | Description |
|---------|-------------|
| `--method GET\|POST\|PUT\|DELETE` | Método HTTP |
| `-f key=value` | Establecer campo de cadena |
| `-F key=@file` | Establecer campo desde archivo |
| `--jq 'expression'` | Filtrar JSON con sintaxis jq |
| `--template 'tmpl'` | Formatear con plantilla Go |
| `--paginate` | Obtener todas las páginas |
| `-H 'Accept: ...'` | Establecer cabecera personalizada |

## Alias

### Gestionar alias

```
gh alias set co 'pr checkout'
gh alias set bugs 'issue list --label bug'
gh alias set last 'run list -L 1'
gh alias list
```

### Alias avanzados

```
# Alias con comando shell
gh alias set --shell pv 'gh pr view --json url --jq .url | pbcopy'

# Eliminar alias
gh alias delete co
```

### Consejos sobre alias

| Command | Description |
|---------|-------------|
| `gh alias set name 'cmd'` | Crear alias simple |
| `--shell` | El alias se ejecuta con shell (admite tuberías) |
| `gh alias list` | Mostrar todos los alias definidos |
| `gh alias delete name` | Eliminar un alias |

## Patrones comunes

### Flujo diario de trabajo

```
gh issue list --assignee @me        # mis issues abiertos
gh pr status                        # PRs que necesitan atención
gh pr checks 123                    # estado de CI para PR
gh run list -b main -L 5            # ejecuciones de CI recientes
```

### Búsqueda

```
gh search repos --language rust --stars ">1000"
gh search issues --repo owner/repo "memory leak"
gh search prs --state open --review required
```

### Flags útiles

| Command | Description |
|---------|-------------|
| `--json field1,field2` | Salida de campos específicos como JSON |
| `--jq 'expr'` | Filtrar salida JSON |
| `-L N` | Limitar resultados a N elementos |
| `--web` | Abrir resultado en el navegador |
| `-R owner/repo` | Apuntar a un repositorio específico |
| `GH_TOKEN=xxx` | Autenticar con variable de entorno |