GitHub Copilot CLI: guía práctica del agente de IA en la terminal

GitHub Copilot CLI es el agente de Copilot que vive en tu terminal: entras al repo, corres copilot y le describes la tarea. Lee y modifica archivos, ejecuta comandos, adjunta imágenes o PDFs, habla con servidores MCP y puede delegar a subagentes (Explore, Task, Code review, Research). No es el autocompletado del editor ni el cloud agent que abre PRs solo: es la superficie agéntica local. Si buscas cuándo elegir completions, chat, CLI o cloud agent, empieza por Copilot para trabajo; esta guía cubre solo el CLI.

Esta guía sigue el flujo de la serie de agentes CLI del hub Construir agentes: instalación, autenticación, permisos, headless, sandbox e instrucciones. Compáralo con Kimi Code CLI, Qwen Code, OpenCode o Aider. Para reglas del repo, usa AGENTS.md.

Instalación: cuatro caminos

Hace falta una suscripción activa de Copilot. Si tu org o enterprise desactivó Copilot CLI en políticas, el binario no te sirve: el bloqueo es de cuenta, no de PATH. En Windows, PowerShell v6 o superior.

La vía más portable es npm sobre Node.js 22 o posterior:

npm install -g @github/copilot

Si tu ~/.npmrc tiene ignore-scripts=true, los docs piden npm_config_ignore_scripts=false npm install -g @github/copilot. Prerelease: @github/copilot@prerelease.

Las otras vías oficiales:

Canal	Comando
Homebrew (macOS/Linux)	brew install --cask copilot-cli
WinGet (Windows)	winget install GitHub.Copilot
Script (macOS/Linux)	curl -fsSL https://gh.io/copilot-install | bash

El script instala en $HOME/.local si no eres root, o /usr/local con sudo. Puedes fijar PREFIX y VERSION (ejemplo oficial: VERSION="v0.0.369"). También hay binarios en github/copilot-cli/releases. Verifica con copilot help.

Primer arranque: directorio de confianza y /login

Entra a una carpeta con código y corre copilot. El CLI pregunta si confías en los archivos de esa carpeta y debajo: durante la sesión puede leer, modificar y ejecutar ahí. Tres opciones: confiar solo esta sesión, recordar la carpeta, o salir. No marques “remember” en un checkout que no controlas.

Si no hay sesión de GitHub, pide /login. Tres métodos oficiales:

1. OAuth device flow (/login o copilot login): código de un uso y browser. Token en el keychain (copilot-cli: Keychain Access, Credential Manager o libsecret).
2. Variables de entorno para CI, contenedores y headless: COPILOT_GITHUB_TOKEN, luego GH_TOKEN, luego GITHUB_TOKEN. Un PAT clásico ghp_ no vale; el fine-grained github_pat_ tiene que ser de tu cuenta personal (no de una org) con permiso Copilot Requests.
3. Fallback de gh: si gh ya está autenticado y no hay otras credenciales, usa ese token.

Una variable de entorno pisa el OAuth guardado. Si exportas GH_TOKEN para otro tool, Copilot CLI lo usará aunque hayas hecho /login.

BYOK (tu propia API key de proveedor) no exige auth de GitHub, pero pierdes /delegate (cloud agent), el MCP de GitHub y Code Search. COPILOT_OFFLINE=true evita GitHub y telemetría; solo es air-gap real si el proveedor BYOK también es local.

Cómo trabaja: permisos por tool, no por prompt

En interactivo, las tools que modifican o ejecutan (touch, chmod, node, sed, shell) piden aprobación:

• Yes: esta vez.
• Yes, and approve TOOL for the rest of the session: esa tool con cualquier opción, el resto de la sesión. En rm equivale a borrar sin preguntar.
• No (Esc): corta la operación; puedes redirigir (“sigue, pero sin tocar tests”).

Esc también aborta mientras “Thinking”. Shift+Tab entra y sale de plan mode: plan estructurado antes de escribir código. @ruta mete un archivo al prompt; arrastra o pega JPEG/PNG/GIF/WebP/PDF/HEIC. /add-dir autoriza otro árbol; /cwd o /cd cambian el working directory sin reiniciar. Un ! al inicio corre shell sin llamar al modelo (!git status).

Headless: -p, allowlist y YOLO

Para una instrucción y salir:

copilot -p "Resume los commits de esta semana" --allow-tool='shell(git)'

Sin un --allow-tool / --allow-all-tools, el modo programático no puede modificar ni ejecutar. --allow-all-tools (y --allow-all / --yolo en interactivo) le da el mismo acceso que tú, sin preguntar. Combínalo con denylist:

copilot --allow-all-tools --deny-tool='shell(rm)' --deny-tool='shell(git push)'

--deny-tool gana a --allow-all-tools. En CI, prefiere allowlist estrecha (shell(git), shell(pnpm)) sobre YOLO.

Sesiones: copilot --continue retoma la última local; --resume o /resume elige una. Puedes arrancar un cloud agent en GitHub y bajarlo al CLI. /every 1h … y /after programan prompts; /usage, /context y /compact miden créditos, tokens y comprimen. El CLI compacta solo al ~95% del contexto.

Instrucciones, agentes, MCP y sandbox

Copilot CLI lee, en este repo:

• .github/copilot-instructions.md (todo el repo)
• .github/instructions/**/*.instructions.md (por path)
• AGENTS.md

Custom agents: ~/.copilot/agents (usuario), .github/agents (repo), /agents en el repo .github-private (org/enterprise). Built-ins: Explore, Task, General purpose, Code review, Research; Rubber duck se consulta solo. /agent lista; copilot --agent=refactor-agent --prompt "…" invoca uno. Skills y hooks existen; no los sustituyas por un system prompt eterno.

MCP de GitHub viene configurado. Extra:

copilot mcp add --transport http sentry https://mcp.sentry.dev/mcp

En sesión, /mcp add. La config vive en ~/.copilot/mcp-config.json (o COPILOT_HOME).

Sandbox local (/sandbox enable) no mete al CLI en una jaula: restringe los comandos que el agente lanza (fs, red, capabilities). Cloud sandbox: copilot --cloud corre la sesión remota aislada. En Business/Enterprise, las content exclusions de org aplican: archivos excluidos no entran al contexto.

Checklist antes de soltarlo en tu repo

• copilot help responde; Node 22+ si instalaste por npm.
• Suscripción Copilot activa; la org no tiene la CLI deshabilitada.
• /login o token COPILOT_GITHUB_TOKEN / fine-grained con Copilot Requests; nada de PAT clásico ghp_.
• Directorio de confianza acotado al repo; no “remember” en clones ajenos.
• Headless con --allow-tool explícito; YOLO solo en throwaway.
• --deny-tool para rm y git push si usas --allow-all-tools.
• Instrucciones en AGENTS.md / .github/copilot-instructions.md, no en cada prompt.
• Tareas paralelas en worktrees, no dos sesiones peleando el mismo working tree.
• Si delegas de verdad, el curso Instalar un agente cubre el resto del stack.

FAQ

¿Copilot CLI es gratis? No: necesita plan Copilot. Chat, CLI y agent mode consumen créditos; el autocompletado del editor es otra superficie.

¿Puedo usarlo sin cuenta de GitHub? Solo con BYOK. Pierdes /delegate, MCP de GitHub y Code Search. COPILOT_OFFLINE=true corta GitHub y telemetría.

¿--yolo y --allow-all-tools son lo mismo? En la práctica sí: aprueban todas las tools. El riesgo es idéntico: el agente corre lo que tú podrías correr.

¿Dónde se guardan MCP y settings? Por defecto ~/.copilot/ (mcp-config.json, agents). COPILOT_HOME mueve el home. /settings edita en caliente.

¿Sirve para CI? Sí, con -p + --allow-tool estrecho y un token de entorno. No uses PAT clásico; no dejes GITHUB_TOKEN de un job de PR con write si el prompt viene de un fork.