Flags del CLI

Modo interactivo y modo print

Claude Code ofrece dos modos de ejecución principales que determinan cómo interactúas con el agente. El modo que elijas depende de si necesitas una conversación continua o una respuesta puntual.

El modo interactivo se activa al ejecutar claude sin flags especiales (o con un prompt inicial entre comillas). Se abre una sesión conversacional en la que puedes enviar múltiples mensajes, recibir respuestas y aprobar acciones del agente de forma iterativa:

claude

claude "explica la estructura de este proyecto"

El modo print (también conocido como modo SDK) se activa con el flag -p o --print. Claude recibe la consulta, la procesa y devuelve la respuesta por la salida estándar, sin abrir una sesión interactiva. Al terminar, el proceso finaliza automáticamente:

claude -p "lista todos los endpoints REST de este proyecto"

El modo print con -p convierte a Claude Code en una herramienta de línea de comandos convencional: recibe entrada, produce salida y termina. Es el modo adecuado para scripts, pipelines y automatizaciones.

La diferencia fundamental es que el modo interactivo mantiene una conversación con estado (puedes hacer preguntas de seguimiento, aprobar cambios paso a paso), mientras que el modo print es stateless: una entrada, una salida, fin del proceso.

flowchart LR
    A["claude 'tarea'"] --> B["Sesión interactiva"]
    B --> C["Conversación continua"]
    C --> D["El usuario cierra la sesión"]

    E["claude -p 'consulta'"] --> F["Respuesta directa"]
    F --> G["Proceso termina"]

Continuación y reanudación de sesiones

Dos flags permiten retomar conversaciones anteriores sin perder el contexto acumulado:

• -c (o --continue): carga la conversación más reciente del directorio actual y la continúa.
• -r (o --resume): reanuda una sesión concreta indicando su nombre o ID. Si se ejecuta sin argumento, abre un selector interactivo de sesiones disponibles.

Ambos se pueden combinar con -p para enviar un mensaje en modo print sin abrir sesión interactiva. La gestión detallada de sesiones se desarrollará más adelante.

Directorios de trabajo adicionales

Por defecto, Claude Code trabaja sobre el directorio desde el que se ejecuta. El flag --add-dir permite añadir directorios adicionales para que el agente tenga acceso a múltiples partes del sistema de archivos en una misma sesión:

claude --add-dir ../shared-lib --add-dir ../config

Este flag es especialmente útil en monorepos o proyectos con dependencias locales. Por ejemplo, si el backend y el frontend viven en carpetas hermanas, se puede dar acceso a ambas:

cd proyecto/backend
claude --add-dir ../frontend

Claude podrá leer y editar archivos tanto en backend/ como en frontend/, lo que permite hacer cambios coordinados entre ambos sin necesidad de abrir dos sesiones separadas.

El flag --add-dir amplía el ámbito de trabajo del agente a múltiples directorios. Claude valida que cada ruta proporcionada exista como directorio antes de iniciar la sesión.

Control de herramientas

Claude Code permite definir con precisión qué herramientas puede usar el agente mediante dos flags complementarios.

Herramientas permitidas sin aprobación

El flag --allowedTools define las herramientas que Claude puede ejecutar sin solicitar permiso al usuario. Acepta patrones con comodines para mayor flexibilidad:

claude --allowedTools "Bash(git log *)" "Bash(git diff *)" "Read"

En este ejemplo, Claude puede ejecutar cualquier comando git log o git diff y leer archivos sin pedir aprobación, pero seguirá pidiendo permiso para editar archivos o ejecutar otros comandos bash.

Herramientas prohibidas

El flag --disallowedTools elimina herramientas del contexto del modelo, impidiendo que Claude las utilice:

claude --disallowedTools "Bash(rm *)" "Edit"

Con esta configuración, Claude no podrá ejecutar ningún comando rm ni editar archivos. Las herramientas deshabilitadas desaparecen por completo del repertorio del agente.

Restricción del conjunto de herramientas

El flag --tools permite restringir el conjunto total de herramientas disponibles, en lugar de añadir o quitar herramientas individuales:

claude --tools "Bash,Read,Grep"

En este caso, Claude solo tendrá acceso a Bash, Read y Grep. Todas las demás herramientas (Edit, Write, WebSearch, etc.) quedarán deshabilitadas. Usar --tools "" desactiva todas las herramientas, y --tools "default" restaura el conjunto completo.

Selección de modelo

El flag --model establece el modelo de lenguaje para la sesión. Acepta tanto alias cortos como nombres completos:

claude --model opus

claude --model sonnet

claude --model claude-sonnet-4-6

Los alias sonnet y opus apuntan siempre a la versión más reciente del modelo correspondiente. Usar el nombre completo (como claude-sonnet-4-6) permite fijar una versión específica.

Para sesiones en modo print, el flag --fallback-model permite definir un modelo alternativo que se usa automáticamente si el modelo principal está sobrecargado:

claude -p --fallback-model sonnet "analiza este archivo"

Modo de permisos

El flag --permission-mode establece el nivel de aprobación con el que arranca la sesión:

claude --permission-mode plan

Los modos disponibles son:

• Normal (default): Claude pide aprobación para cada acción que modifique archivos o ejecute comandos.
• Plan (plan): Claude puede leer archivos y explorar el proyecto libremente, pero no puede modificar archivos ni ejecutar comandos.
• Auto-Accept (acceptEdits): Claude ejecuta ediciones de archivos sin solicitar aprobación, pero sigue pidiendo permiso para comandos Bash.

El valor que acepta el flag es el nombre de configuración entre paréntesis. Por ejemplo, --permission-mode acceptEdits activa el modo Auto-Accept. Estos mismos valores son los que se usan en la propiedad defaultMode de settings.json.

El modo de permisos se puede cambiar durante una sesión con Shift+Tab, pero el flag permite establecer el modo por defecto desde el arranque.

Personalización del prompt del sistema

Claude Code permite modificar las instrucciones base del agente mediante flags dedicados. Existen dos estrategias: reemplazar el prompt completo o añadir instrucciones adicionales.

Añadir instrucciones

El flag --append-system-prompt añade texto al final del prompt del sistema por defecto, manteniendo todas las capacidades estándar de Claude Code:

claude --append-system-prompt "Usa siempre TypeScript y añade comentarios JSDoc"

Este es el enfoque más seguro para la mayoría de casos, ya que preserva el comportamiento base del agente y solo añade restricciones o preferencias adicionales.

Reemplazar el prompt

El flag --system-prompt reemplaza por completo el prompt del sistema. Claude pierde las instrucciones por defecto y se comporta exclusivamente según el texto proporcionado:

claude --system-prompt "Eres un experto en seguridad. Analiza código buscando vulnerabilidades"

Este modo se reserva para situaciones donde se necesita control total sobre el comportamiento del agente, como crear un agente especializado que no necesite las capacidades generales de Claude Code.

El flag --append-system-prompt es la opción recomendada para la mayoría de casos, ya que preserva las capacidades integradas de Claude Code mientras añade instrucciones personalizadas.

En modo print, también se pueden cargar los prompts desde archivos con --system-prompt-file y --append-system-prompt-file, lo que facilita el versionado y la reutilización de configuraciones entre equipos.

Limitación de recursos

Dos flags permiten establecer límites en las sesiones de modo print para evitar ejecuciones descontroladas o costes inesperados.

El flag --max-turns limita el número de turnos agénticos (ciclos de razonamiento + acción) antes de que Claude se detenga:

claude -p --max-turns 5 "refactoriza este módulo"

El flag --max-budget-usd establece un presupuesto máximo en dólares para las llamadas a la API:

claude -p --max-budget-usd 2.00 "genera tests para todo el proyecto"

Ambos flags son particularmente útiles en entornos de CI/CD o scripts automatizados, donde una ejecución sin límites podría consumir recursos de forma indefinida.

Formato de salida

El flag --output-format controla cómo se formatea la respuesta en modo print. Dispone de tres opciones:

• text (por defecto): salida en texto plano, legible para humanos.
• json: respuesta en formato JSON, ideal para parsear con herramientas como jq.
• stream-json: emisión de eventos JSON en streaming conforme Claude genera la respuesta.

claude -p --output-format json "lista las dependencias del proyecto"

El formato JSON resulta especialmente útil para integrar Claude Code en scripts de automatización que necesitan procesar la respuesta de forma programática.

Otros flags destacados

Algunos flags adicionales cubren necesidades específicas:

| Flag | Descripción | |---|---| | --worktree nombre | Inicia Claude en un worktree de Git aislado, útil para sesiones en paralelo | | --verbose | Activa el registro detallado de cada turno | | --debug "categoría" | Activa el modo debug con filtrado por categoría (por ejemplo, "api,mcp") | | --chrome | Habilita la integración con el navegador Chrome | | --mcp-config archivo | Carga servidores MCP desde un archivo de configuración JSON | | --version | Muestra la versión instalada de Claude Code |

Los flags se pueden combinar libremente para componer configuraciones a medida. Por ejemplo, una ejecución en modo print con modelo específico, herramientas restringidas y límite de presupuesto:

claude -p --model opus --tools "Read,Grep,Glob" --max-budget-usd 1.00 "busca posibles memory leaks"