Claude Code CLI: La Referencia Técnica Definitiva
Actualizado el 12 de diciembre de 2025
Actualización de diciembre 2025: Claude Code ahora impulsa flujos de trabajo de ingeniería empresarial con edición agéntica de múltiples archivos, integración del protocolo MCP con más de 300 servicios externos, subagentes especializados para tareas complejas y un sistema de hooks para automatización CI/CD. El sistema de permisos permite controles de seguridad granulares. El cambio entre modelos Haiku (rápido/económico) y Opus (potente) optimiza las compensaciones entre costo y rendimiento.
He pasado meses llevando Claude Code al límite en bases de código de producción, pipelines CI/CD y despliegues empresariales. Esta guía destila esa experiencia en la referencia completa que desearía haber tenido cuando empecé. Cubre todo, desde la primera instalación hasta patrones avanzados que la mayoría de usuarios nunca descubren.
Claude Code no es una interfaz de chat que casualmente sabe de programación. Es un sistema agéntico que lee tu base de código, ejecuta comandos, modifica archivos, gestiona flujos de trabajo de git, se conecta a servicios externos y delega tareas complejas a subagentes especializados—todo a través de una interfaz de línea de comandos que se integra en cómo realmente trabajan los desarrolladores.
La diferencia entre usar Claude Code casualmente y usarlo efectivamente está en entender su arquitectura: la jerarquía de configuración que controla el comportamiento, el sistema de permisos que controla las operaciones, el sistema de hooks que permite automatización determinista, el protocolo MCP que extiende las capacidades y el sistema de subagentes que maneja tareas complejas de múltiples pasos. Domina estos sistemas y Claude Code se convierte en un multiplicador de fuerza. Ignóralos y estarás dejando la mayor parte del valor sobre la mesa.
Esta guía asume que te sientes cómodo con herramientas de línea de comandos y quieres el panorama completo. Cada característica está documentada con sintaxis real, ejemplos de configuración reales y los casos límite que confunden incluso a usuarios experimentados. Ya sea que estés configurando tu primer proyecto o desplegando en una organización de ingeniería empresarial, la información está aquí.
Cómo Funciona Claude Code: El Modelo Mental
Antes de profundizar en las características, entiende cómo la arquitectura de Claude Code moldea todo lo que haces con él. El sistema opera en tres capas:
┌─────────────────────────────────────────────────────────┐
│ CAPAS DE CLAUDE CODE │
├─────────────────────────────────────────────────────────┤
│ CAPA DE EXTENSIÓN │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ MCP │ │ Hooks │ │ Skills │ │ Plugins │ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
│ Herramientas externas, automatización determinista, │
│ experiencia de dominio, extensiones empaquetadas │
├─────────────────────────────────────────────────────────┤
│ CAPA DE DELEGACIÓN │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Subagentes (hasta 10 en paralelo) │ │
│ │ Explore | Plan | General-purpose | Custom │ │
│ └─────────────────────────────────────────────────┘ │
│ Contextos aislados para trabajo enfocado, retorna │
│ resúmenes │
├─────────────────────────────────────────────────────────┤
│ CAPA CENTRAL │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Contexto de Conversación Principal │ │
│ │ Herramientas: Read, Edit, Bash, Glob, Grep, │ │
│ │ etc. │ │
│ └─────────────────────────────────────────────────┘ │
│ Tu interacción principal; contexto limitado; cuesta │
│ dinero │
└─────────────────────────────────────────────────────────┘
Capa Central: Tu conversación principal. Cada mensaje, lectura de archivo y salida de herramienta consume contexto de una ventana compartida de 200K tokens (1M con premium). Cuando el contexto se llena, Claude pierde el seguimiento de decisiones anteriores y la calidad se degrada. Esta capa cuesta dinero por token.
Capa de Delegación: Los subagentes se inician con contextos limpios, hacen trabajo enfocado y retornan resúmenes. Los resultados de exploración no inflan tu conversación principal—solo las conclusiones regresan. Usa subagentes Haiku para exploración (económico, rápido) y Sonnet para implementación.
Capa de Extensión: MCP conecta servicios externos (bases de datos, GitHub, Sentry). Los hooks garantizan la ejecución de comandos shell independientemente del comportamiento del modelo. Los skills codifican experiencia de dominio que Claude aplica automáticamente. Los plugins empaquetan todo esto para distribución.
La idea clave: La mayoría de usuarios trabajan enteramente en la Capa Central, observando cómo el contexto se infla y los costos suben. Los usuarios avanzados empujan la exploración y el trabajo especializado a la Capa de Delegación, mantienen la Capa de Extensión configurada para su flujo de trabajo y usan la Capa Central solo para orquestación y decisiones finales.
Tabla de Contenidos
- Instalación y Autenticación
- Modos de Interacción Principales
- Sistema de Configuración en Profundidad
- Selección y Cambio de Modelos
- Sistema de Permisos y Seguridad
- Sistema de Hooks
- MCP (Model Context Protocol)
- Subagentes y Delegación de Tareas
- Modo de Pensamiento Extendido
- Estilos de Salida
- Comandos Slash
- Skills
- Sistema de Plugins
- Gestión de Memoria y Contexto
- Entrada de Imágenes y Multimodal
- Integración con Git y Flujos de Trabajo
- Integración con IDEs
- Patrones de Uso Avanzado
- Claude Code Remote
- Background Agents
- Gestión de Costos y Facturación
- Optimización de Rendimiento
- Solución de Problemas y Depuración
- Despliegue Empresarial
- Referencia de Atajos de Teclado
- Mejores Prácticas
Instalación y Autenticación
Requisitos del Sistema
Claude Code funciona en macOS 10.15+, Ubuntu 20.04+/Debian 10+ y Windows 10+ a través de WSL o Git Bash. El sistema requiere 4 GB de RAM como mínimo y una conexión activa a internet. La compatibilidad con shells funciona mejor con Bash, Zsh o Fish.
Para Windows, tanto WSL 1 como WSL 2 funcionan. Git Bash también funciona si prefieres Windows nativo. Alpine Linux y otros sistemas basados en musl requieren paquetes adicionales:
apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0
Métodos de Instalación
Instalación nativa (recomendada)
El binario nativo proporciona la experiencia más limpia sin dependencia de Node.js:
# macOS y Linux
curl -fsSL https://claude.ai/install.sh | bash
# Alternativa con Homebrew
brew install --cask claude-code
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
Para instalación de versión específica:
# Instalar versión específica
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58
# Instalar última versión explícitamente
curl -fsSL https://claude.ai/install.sh | bash -s latest
# Windows PowerShell - versión específica
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58
Instalación con NPM
Para entornos donde se prefiere npm:
npm install -g @anthropic-ai/claude-code
Nunca uses sudo con la instalación npm—crea problemas de permisos que complican todo lo posterior.
Migración desde instalación existente
Si tienes una instalación anterior basada en npm, migra al binario nativo:
claude install
Opciones de Autenticación
Claude Code soporta tres rutas de autenticación, cada una con diferentes compensaciones:
Claude Console (facturación API)
Conéctate directamente a la API de Anthropic a través de console.anthropic.com. Crea una cuenta, configura la facturación y autentícate a través del CLI. Esto proporciona facturación basada en uso con acceso completo a la API. Se crea automáticamente un workspace dedicado "Claude Code"—no puedes crear claves API para este workspace, pero puedes monitorear el uso.
Suscripción Claude Pro o Max
Usa las credenciales de tu cuenta claude.ai. La suscripción cubre tanto la interfaz web como el uso del CLI bajo un único plan mensual. Esto simplifica la facturación para usuarios individuales que quieren costos predecibles.
Plataformas empresariales
AWS Bedrock, Google Vertex AI y Microsoft Foundry proporcionan acceso de grado empresarial con relaciones de facturación cloud existentes:
# AWS Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_PROFILE=your-profile
# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project
# Microsoft Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource-name
# Opcional: autenticación por clave API (de lo contrario usa Entra ID)
export ANTHROPIC_FOUNDRY_API_KEY=your-key
Para despliegues empresariales detrás de proxies o a través de gateways LLM:
# Proxy corporativo
export HTTPS_PROXY='https://proxy.example.com:8080'
# Gateway LLM (omitir autenticación nativa)
export CLAUDE_CODE_USE_BEDROCK=1
export ANTHROPIC_BEDROCK_BASE_URL='https://your-gateway.com/bedrock'
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
Verificación
claude doctor
Esto reporta el tipo de instalación, versión, configuración del sistema y cualquier problema detectado.
Actualizaciones
Claude Code se auto-actualiza por defecto, verificando al inicio y periódicamente durante las sesiones. Las actualizaciones se descargan en segundo plano y se aplican en el próximo lanzamiento.
Deshabilitar auto-actualizaciones:
export DISABLE_AUTOUPDATER=1
O en settings.json:
{
"env": {
"DISABLE_AUTOUPDATER": "1"
}
}
Actualización manual:
claude update
Desinstalación
Instalación nativa (macOS/Linux/WSL):
rm -f ~/.local/bin/claude
rm -rf ~/.claude-code
Instalación nativa (Windows PowerShell):
Remove-Item -Path "$env:LOCALAPPDATA\Programs\claude-code" -Recurse -Force
Remove-Item -Path "$env:LOCALAPPDATA\Microsoft\WindowsApps\claude.exe" -Force
Limpiar configuración (elimina todos los ajustes):
rm -rf ~/.claude
rm ~/.claude.json
rm -rf .claude
rm -f .mcp.json
Modos de Interacción Principales
REPL Interactivo
Lanza Claude Code sin argumentos para entrar en el bucle interactivo de lectura-evaluación-impresión:
cd your-project
claude
El REPL mantiene el contexto de conversación entre turnos. Escribe consultas directamente, recibe respuestas y continúa hasta que salgas con /exit o Ctrl+D.
Inicia con un prompt inicial para enfocar la sesión:
claude "explain the authentication flow in this project"
Consejo de experto: El REPL persiste el estado a través de eventos de compactación. Cuando el contexto crece demasiado, Claude automáticamente resume la conversación anterior mientras preserva decisiones clave y fragmentos de código. Puedes activar esto manualmente con /compact o agregar instrucciones personalizadas de qué preservar.
Modo No Interactivo
El modo print (-p) ejecuta una sola consulta y termina:
# Consulta directa
claude -p "list all TODO comments in this project"
# Procesar entrada por pipe
cat error.log | claude -p "identify the root cause of these failures"
# Encadenar con otras herramientas
claude -p "generate a README" > README.md
Para salida estructurada adecuada para parsing en scripts:
claude -p "count lines by file type" --output-format json
La salida JSON incluye todo lo que necesitas para automatización:
{
"type": "result",
"subtype": "success",
"total_cost_usd": 0.0034,
"is_error": false,
"duration_ms": 2847,
"duration_api_ms": 1923,
"num_turns": 4,
"result": "Texto de respuesta aquí...",
"session_id": "abc-123-d
[Contenido truncado para traducción]
