GitHub CLI (gh)
Interactúa con GitHub desde la línea de comandos: repositorios, releases, issues, PRs, discussions, búsqueda, revisión de código y Actions.
Verificado con gh 2.95.0.
Pautas para el agente
- Para archivos o directorios remotos conocidos, usa
gh repo read-file/gh repo read-dir(vista previa engh2.95). Para versiones antiguas degho necesidades solo de API, usa el fallback de la API de contenidos en API Patterns. - Cuando una tarea requiera buscar en varios archivos o explorar código desconocido donde las rutas no se conocen de antemano, clona a un directorio temporal (
gh repo clone owner/repo <temp-dir> -- --depth 1) y usa herramientas locales de lectura y búsqueda de archivos. - Prefiere la salida de texto predeterminada sobre
--jsonpara leer/visualizar; es más eficiente en tokens. Usa--jsoncon--jqsolo cuando extraigas campos específicos de forma programática. Para descubrir los campos admitidos, ejecuta el comando con--jsony sin lista de campos, luego solicita solo los campos que necesites. - Al ver logs o diffs, primero acota la salida (por ejemplo,
--name-only,--log-failed) antes de obtener el contenido completo. - La bandera
--repono es necesaria cuando se ejecuta dentro de un repositorio clonado; el repositorio del directorio actual se usa por defecto. Paragh api, usa la ruta explícita (repos/OWNER/REPO/...) o establece la variable de entornoGH_REPO. - Usa esta habilidad para los flujos de trabajo cubiertos. Cuando falte una bandera o campo necesario, un comando falle con una bandera desconocida o modificada, o el comando esté marcado como vista previa, consulta la ayuda de ese comando específico (por ejemplo,
gh pr diff --help).
Seguridad
- Operaciones de escritura (
create,edit,comment,review,close,merge,delete,rerun,run cancel,workflow run/enable/disable, mutaciones de discussion) modifican el estado de GitHub. Confirma con el usuario antes de ejecutarlas, especialmente en repositorios que no te pertenecen. gh apicon--method POST/PUT/PATCH/DELETEenvía solicitudes de escritura. Verifica el endpoint y la carga útil. El método predeterminado es GET (seguro); agregar parámetros-f/-Fcambia el método predeterminado a POST.- Operaciones destructivas (
delete,close,merge --admin) pueden ser irreversibles. Requieren confirmación explícita del usuario.
Prerrequisitos
Verifica que gh esté instalado y autenticado antes de ejecutar comandos:
gh --version
gh auth status
Si no está autenticado, guía al usuario a través de gh auth login.
Banderas comunes
Estas banderas están disponibles en muchos grupos de comandos, pero la compatibilidad varía según el comando:
--repo OWNER/REPO-- Apunta a un repositorio diferente (predeterminado: repositorio del directorio actual). También acepta URLs completas.--json FIELDS-- Salida como JSON con los campos especificados. Pasa sin valor para listar los campos disponibles.--jq EXPRESSION-- Filtra la salida JSON usando sintaxis de jq. Requiere--json.--template STRING-- Formatea la salida JSON usando una plantilla Go (alternativa a--jq).--web-- Abre el recurso en el navegador en lugar de mostrarlo en la terminal.--limit N-- Número máximo de resultados para comandos de lista (el valor predeterminado suele ser 30).
Repositorios
Ver
Muestra la descripción, README, estrellas, desglose de lenguaje y otros metadatos de un repositorio.
gh repo view owner/repo
gh repo view owner/repo --json name,description,defaultBranchRef,languages,stargazerCount
Clonar
Clona un repositorio localmente. Configura automáticamente el remoto y, para forks, configura el remoto upstream.
gh repo clone owner/repo [target-directory]
Leer contenidos de repositorio remoto
Para lecturas rápidas de archivos o directorios conocidos, usa los comandos de lectura de repositorio (vista previa en gh 2.95):
# Archivo conocido
gh repo read-file src/main.py --repo owner/repo --ref main
# Directorio conocido
gh repo read-dir src --repo owner/repo --ref main
# Fallback para versiones antiguas de gh
gh api "repos/OWNER/REPO/contents/src/main.py?ref=main" -H "Accept: application/vnd.github.raw+json"
Para formas de salida, límites de tamaño de archivo y advertencias sobre listados de directorios, consulta API Patterns. Para exploración de múltiples archivos, clona en su lugar (consulta las Pautas para el agente).
Listar repositorios
Lista repositorios propiedad de un usuario u organización, con filtros opcionales de lenguaje y visibilidad.
gh repo list owner --limit 30
Releases
Listar
Lista releases en un repositorio, ordenadas por fecha de creación (más recientes primero). Por defecto muestra todos los releases, incluyendo pre-releases y borradores.
gh release list --repo owner/repo --limit 10
Banderas:
--exclude-pre-releases-- Excluir pre-releases--exclude-drafts-- Excluir borradores
Campos JSON clave: tagName, name, publishedAt, isLatest, isDraft, isPrerelease, isImmutable
Ver (changelog, assets)
Muestra el cuerpo del changelog, etiqueta, assets y metadatos de un release. Omite la etiqueta para ver el último release.
gh release view --repo owner/repo # Último release
gh release view v1.2.0 --repo owner/repo # Etiqueta específica
gh release view v1.2.0 --json tagName,body,assets,publishedAt
Campos JSON clave: tagName, name, body, assets, author, publishedAt, isDraft, isPrerelease, isImmutable, url
Issues
Listar
Lista issues en un repositorio, filtrados por estado, etiqueta, asignado o consulta de búsqueda. Por defecto solo muestra issues abiertos.
gh issue list --repo owner/repo
gh issue list --repo owner/repo --state all --label bug --assignee @me
gh issue list --repo owner/repo --search "error no:assignee sort:created-asc"
Banderas:
--state VALUE--open(predeterminado),closed,all--label NAME-- Filtrar por etiqueta (repetir para múltiples)--assignee LOGIN-- Filtrar por asignado (@mepara uno mismo)--search QUERY-- Sintaxis de búsqueda de GitHub
Campos JSON clave: number, title, state, stateReason, author, labels, assignees, createdAt, updatedAt, url
Ver
Muestra el título, cuerpo, etiquetas, asignados y estado de un issue. Usa --comments para incluir el hilo de comentarios completo.
gh issue view 123
gh issue view 123 --comments
gh issue view 123 --json title,body,labels,comments,state
Crear
Crea un nuevo issue con título, cuerpo, etiquetas y asignados.
gh issue create --title "Bug: descripción" --body "Detalles..." --label bug --assignee user1
Editar
Actualiza el título, cuerpo, etiquetas, asignados o hito de un issue. Todas las banderas se pueden combinar en una sola llamada.
Banderas:
--title TEXT/--body TEXT-- Actualizar título o cuerpo--add-label NAME/--remove-label NAME-- Modificar etiquetas--add-assignee LOGIN/--remove-assignee LOGIN-- Modificar asignados--milestone NAME/--remove-milestone-- Establecer o eliminar hito
Comentar
Agrega un comentario a un issue existente.
gh issue comment 123 --body "Texto del comentario"
Cerrar / Reabrir
Cierra o reabre un issue. Opcionalmente especifica un motivo de cierre y deja un comentario.
gh issue close 123 --comment "Corregido en PR #456" --reason "not planned"
gh issue close 123 --duplicate-of 456
gh issue reopen 123
Motivos de cierre: completed (predeterminado), not planned, duplicate.
Estado
Muestra un resumen de issues relevantes para ti: asignados a ti, que te mencionan y que has abierto.
gh issue status
Para tipos de issues, sub-issues, relaciones padre-hijo, dependencias de bloqueo y sus campos JSON (requiere hosts de GitHub compatibles), consulta Issues reference.
Pull Requests
Usa estos comandos para ver e inspeccionar PRs. Para crear, fusionar, revisar y gestionar PRs, consulta Pull Requests reference.
Listar
Lista pull requests en un repositorio, filtrados por estado, autor, etiqueta o consulta de búsqueda. Por defecto solo muestra PRs abiertos.
gh pr list --repo owner/repo
gh pr list --repo owner/repo --state all --author @me --label "needs-review"
gh pr list --repo owner/repo --search "status:success review:required"
gh pr list --repo owner/repo --app dependabot
Banderas:
--state VALUE--open(predeterminado),closed,merged,all--draft-- Filtrar por estado de borrador--author LOGIN/--assignee LOGIN-- Filtrar por autor o asignado--label NAME-- Filtrar por etiqueta--search QUERY-- Sintaxis de búsqueda de GitHub--app NAME-- Filtrar por autor de GitHub App (por ejemplo,dependabot)
Campos JSON clave: number, title, state, author, headRefName, baseRefName, labels, reviewDecision, isDraft, statusCheckRollup, files, commits, reviews, url
Ver
Muestra el título, cuerpo, estado de revisión, comprobaciones y otros metadatos de un PR. Sin argumento, muestra el PR de la rama actual. Usa --comments para incluir el hilo de comentarios.
gh pr view 123
gh pr view 123 --comments
gh pr view 123 --json title,body,files,commits,reviews,reviewDecision
Estado
Muestra un resumen de PRs relevantes para ti: el PR de la rama actual, PRs que creaste y PRs donde se solicita tu revisión.
gh pr status
Discussions
Usa gh discussion para Discussions de repositorio (vista previa en gh 2.94). Comienza con comandos de lectura y verifica las banderas con --help porque el conjunto de comandos está en vista previa:
gh discussion list --repo owner/repo --limit 10
gh discussion view 123 --repo owner/repo --comments
Para crear, editar, comentar, hilos de respuesta, formas de salida JSON y patrones de fallback de GraphQL, consulta Discussions reference.
Búsqueda
Busca en GitHub issues, PRs, código, commits y repositorios. Usa gh issue list / gh pr list para un repositorio; usa gh search ... para consultas entre repositorios o de todo el propietario.
Para la sintaxis completa de consulta de búsqueda, consulta la documentación de búsqueda de GitHub. Para banderas específicas de cada subcomando, ejecuta gh search <subcommand> --help.
Límites de velocidad: Las APIs de búsqueda tienen límites de velocidad más estrictos que la API principal. La búsqueda de código es la más restrictiva (~10/min autenticado; requiere autenticación). Otros comandos de búsqueda permiten ~30/min autenticado o ~10/min no autenticado. Verifica la cuota actual con gh api rate_limit --jq '.resources | {search, code_search}'.
Cuándo clonar en su lugar: Consulta las Pautas para el agente para saber cuándo clonar en lugar de usar la API.
Bots y aplicaciones: Para autores de GitHub App como Dependabot, usa --app dependabot; --author dependabot filtra cuentas de usuario, no autores de aplicaciones.
Reconocimiento: Al buscar en un repositorio desconocido, primero verifica su lenguaje principal para seleccionar los valores correctos de --extension y --language:
gh repo view owner/repo --json primaryLanguage --jq '.primaryLanguage.name'
Issues
Busca issues entre repositorios usando palabras clave, etiquetas, estado o sintaxis de búsqueda de GitHub.
gh search issues "manejo de errores" --repo owner/repo
gh search issues --label bug --state open --assignee @me
gh search issues --app dependabot --repo owner/repo
gh search issues --involves username --comments ">10" --repo owner/repo
Banderas clave: --repo, --owner, --state, --label, --assignee, --author, --app, --involves, --comments, --match, --sort, --include-prs.
PRs
Busca pull requests entre repositorios. Soporta filtrado por autor, estado de revisión, estado de fusión y estado de borrador.
gh search prs "refactor" --repo owner/repo
gh search prs --review-requested @me --state open
gh search prs --app dependabot --repo owner/repo
gh search prs --author username --merged --repo owner/repo
Banderas clave: --repo, --owner, --state, --merged, --draft, --author, --assignee, --app, --label, --review, --review-requested, --base, --head, --checks, --sort.
Código
Busca dentro del contenido de archivos en repositorios de GitHub. Devuelve solo las líneas coincidentes (sin números de línea, sin contexto circundante). Útil para localizar archivos que contienen un patrón, pero luego lee los archivos o clona el repositorio para entender la lógica del código.
Limitaciones: Usa un motor de búsqueda heredado (los resultados pueden no coincidir con github.com). Solo busca en la rama predeterminada. Solo se indexan archivos de menos de 384 KB. Cada consulta debe incluir al menos un término de búsqueda (las búsquedas solo con calificadores como --extension ts solas fallarán). No soporta --sort ni --order; los resultados siempre se clasifican por relevancia.
gh search code "nombreDeFuncion" --repo owner/repo
gh search code "createServer" --repo owner/repo --extension ts
gh search code "lint" --repo owner/repo --filename package.json
Banderas clave: --repo, --owner, --extension, --filename, --language, --match, --size.
Campos JSON clave: path, repository, sha, textMatches, url.
El campo textMatches proporciona contexto de fragmento con posiciones de coincidencia a nivel de carácter: usa --json path,textMatches cuando necesites más contexto del que proporciona la salida de texto predeterminada.
Commits
Busca commits por texto del mensaje, autor, fecha del committer o hash.
gh search commits "corregir error" --repo owner/repo
gh search commits --author username --committer-date ">2024-01-01"
gh search commits --hash abc1234
Banderas clave: --repo, --owner, --author, --committer, --author-date, --committer-date, --author-name, --author-email, --hash, --merge, --sort.
Repositorios
Busca repositorios por palabra clave, lenguaje, tema, estrellas, licencia o propietario. Nota: --repo no está disponible en este subcomando; usa --owner para filtrar por propietario.
gh search repos "palabra clave" --language python --sort stars --order desc
gh search repos --topic cli --stars ">1000" --language go
Banderas clave: --owner, --language, --topic, --stars, --forks, --license, --created, --updated, --match, --sort, --include-forks, --visibility.
Exclusiones de calificadores (prefijo de guión)
Las consultas de búsqueda con exclusiones como -label:bug necesitan sintaxis especial para evitar la interpretación de banderas del shell. Todas las banderas (por ejemplo, --limit) deben aparecer antes de --; cualquier cosa después de -- se interpreta como texto de la consulta de búsqueda:
# Shells tipo Unix
gh search issues -- "mi consulta -label:bug"
# PowerShell
gh --% search issues -- "mi consulta -label:bug"