1.1 Instalación y primer comando

📋 Requisitos e instalación

🧠 Imagínalo así: instalar Claude Code es como instalar Git por primera vez. Un comando, una autenticación y, a partir de ahí, tienes un nuevo superpoder en la terminal que nunca más vas a dejar.

O Claude Code es una herramienta de línea de comandos (CLI) de Anthropic que pone a Claude directamente en tu terminal. A diferencia de un chat web, aquí Claude tiene acceso a tu codebase, puede leer y editar archivos, ejecutar comandos y actuar como un agente de desarrollo completo.

Para instalarlo, necesitas Node.js 18+ (el runtime de JavaScript). Si ya tienes Node, la instalación requiere un solo comando. Hay tres opciones, según tu sistema operativo:

instalación vía npm (cualquier SO)

npm install -g @anthropic-ai/claude-code

npm (universal)

Funciona en Mac, Linux y Windows. Necesitas tener instalado Node.js 18+. Es el camino más común.

Homebrew (macOS)

brew install claude-code si usas Homebrew en Mac. Gestiona las actualizaciones automáticamente.

winget (Windows)

winget install Anthropic.ClaudeCode en Windows. Se integra con el gestor de paquetes nativo.

💡 Consejo: autenticación

En la primera ejecución, Claude Code te pedirá autenticarte. Puedes iniciar sesión mediante el navegador (recomendado) o definir la variable ANTHROPIC_API_KEY en tu entorno. El inicio de sesión mediante el navegador vincula tu cuenta de Anthropic y habilita el uso con los planes Pro/Max/Team.

En 1 frase: Con Node.js 18+ y un npm install -g, tienes Claude Code funcionando.

▶️ Primer claude en la terminal

🧠 Imagínalo así: abrir Claude Code por primera vez es como encender un auto nuevo. El motor ruge, el tablero se ilumina y te das cuenta de que tienes un copiloto inteligente en el asiento del pasajero.

Abre el terminal, ve a la carpeta de cualquier proyecto y escribe claude. Listo. Aparecerá la interfaz interactiva, que mostrará el modelo en ejecución y esperará tu prompt. Estás conversando directamente con Claude, pero ahora tiene acceso a los archivos del directorio actual.

primer comando

cd ~/meu-projeto
claude

Al empezar, prueba pedir algo sencillo: "explica qué hace este proyecto" o "enumera los archivos principales". Claude leerá los archivos del directorio y responderá con contexto real. Eso ya lo diferencia de cualquier chatbot web, porque está dentro de tu proyecto.

one-shot mode (sin sesión)

claude "explica qué hace el archivo package.json"

En 1 frase: claude en la terminal abre una sesión interactiva con acceso total a tu proyecto.

🔀 Modo interactivo vs. ejecución única

🧠 Imagínalo así: El modo interactivo es como sentarte a una mesa con Claude para trabajar juntos durante horas. El one-shot es como enviar un mensaje rápido por la ventana y recibir la respuesta.

Claude Code tiene dos modos fundamentales de uso. En el modo interactivo (solo escribe claude), abres una conversación continua. Cada mensaje mantiene el contexto de los anteriores, Claude puede pedir confirmación antes de editar archivos y tú controlas el flujo paso a paso. Es el modo predeterminado para el desarrollo.

En modo one-shot (usando el flag -p), envías un único prompt, recibes la respuesta y el proceso termina. Es ideal para automatizaciones, scripts y preguntas rápidas. El flag -p (de "print") dice: ejecuta esto y devuélveme el resultado en stdout.

✓ Modo interactivo

• La conversación continúa con contexto
• Pide confirmación para las ediciones
• Ideal para desarrollo
• Comando: claude

→ Modo one-shot

• Una pregunta, una respuesta
• La salida va a stdout
• Ideal para scripts y pipes
• Comando: claude -p "..."

En 1 frase: claude para conversar, claude -p para preguntar y salir.

📖 Cómo navegar por --help y flags esenciales

🧠 Imagínalo así: las flags de Claude Code son como los botones del tablero de un avión. No necesitas conocerlos todos el primer día, pero los esenciales te mantienen en el aire.

El punto de partida siempre es claude --help. Enumera todas las flags disponibles con una breve explicación. Las que vas a usar en el día a día son pocas:

flags esenciales

claude --help          # ver todas as opções
claude --version       # versão instalada
claude -p "..."        # modo one-shot (print)
claude --resume        # retomar sessão anterior
claude --model opus    # escolher o modelo
claude --verbose       # modo verboso (debug)

--help

Siempre es el primer comando cuando olvidas algo. Toda la referencia al alcance de tus dedos.

-p (print / one-shot)

El flag más usado. Convierte Claude Code en una herramienta de pipe de Unix.

--resume

Retoma la sesión anterior. Esencial cuando cierras la terminal sin querer.

--model

Elige qué modelo usar. Opus para tareas complejas, Sonnet para tareas rápidas.

En 1 frase: --help es tu manual de bolsillo; -p, --resume e --model son los flags del día a día.

🔄 Actualización y control de versiones

🧠 Imagínalo así: Claude Code evoluciona rápido. Cada versión nueva trae features, mejoras y fixes. Mantenerlo actualizado es como mantener afilada la caja de herramientas.

Claude Code recibe actualizaciones frecuentes. Verificar su versión y actualizarlo son operaciones sencillas:

verificar y actualizar

claude --version                              # ver versão atual
npm update -g @anthropic-ai/claude-code       # atualizar via npm

Claude Code también avisa cuando hay una actualización disponible al iniciar una sesión. Se recomienda mantener siempre la versión más reciente, ya que suelen aparecer funciones nuevas (como servidores MCP, mejores permisos y nuevos slash commands). Consulta el changelog oficial para saber qué cambió entre versiones.

💡 Sobre los breaking changes

Los cambios importantes son poco frecuentes, pero ocurren. Si tienes scripts que dependen de Claude Code, pruébalos después de actualizar. El comando claude --version al inicio de los scripts ayuda a garantizar la compatibilidad.

En 1 frase: npm update -g para actualizar; --version para comprobar.

🔧 Diagnóstico de problemas comunes

🧠 Imagínalo así: como todo software, Claude Code puede presentar problemas durante la instalación. La buena noticia es que los errores más comunes se resuelven con una sola línea.

Si algo salió mal durante la instalación o la primera ejecución, sigue esta lista de verificación. Cubre el 90% de los problemas que encuentran quienes empiezan:

✗ Errores comunes

• EACCES permission denied en npm install -g
• Node version mismatch (necesitas tener 18 años o más)
• Authentication failed en la primera ejecución
• command not found: claude después de install

✓ Soluciones

• Usa sudo npm install -g o configura npm prefix
• Actualiza Node: nvm install 20
• Ejecútalo claude y sigue el inicio de sesión en el navegador
• Verifica si npm/bin está en el PATH

checklist-diagnostico.txt

Claude Code não funciona? Checklist rápido:
[ ] Node.js 18+ instalado?  → node --version
[ ] npm global acessível?   → npm list -g --depth=0
[ ] claude no PATH?         → which claude
[ ] Autenticação ok?        → claude (e siga o login)
[ ] Versão atualizada?      → claude --version
Se 3+ falharam, reinstale: npm uninstall -g @anthropic-ai/claude-code && npm install -g @anthropic-ai/claude-code

En 1 frase: Node, npm, PATH y auth: resuelve estos cuatro y Claude Code funcionará.

🧾 Resumen del módulo

✓

Instalación con 1 comando — npm install -g @anthropic-ai/claude-code (necesita Node 18+).

✓

Dos modos de uso — interactivo (claude) para desarrollo, one-shot (claude -p) para scripts.

✓

Flags esenciales — --help, -p, --resume, --model y --version cubren las tareas diarias.

✓

Troubleshooting — Node + npm + PATH + auth = los 4 puntos de control para el diagnóstico.

Siguiente módulo:

1.2 — Navega el CLI como un pro: atajos, slash commands, sesiones y pipes.

← Volver a la ruta Siguiente módulo →