Manual de referencia de la CLI: Comandos y flags

📚 Navegación de la serie: El artículo anterior 33 Hooks (ganchos) te enseñó cómo disparar acciones automáticas ante eventos específicos, sirviendo de protección en el entorno de desarrollo. En este artículo regresaremos a lo más básico: qué opciones admite el comando claude que escribes en la terminal. Comandos, flags (banderas), tuberías y códigos de salida; todo reunido en una guía rápida para su consulta.

"¿Se le pueden pasar parámetros a claude? Yo siempre he escrito claude a secas."

"Sí, un montón. Puedes hacer que un script ejecute claude -p 'resume este PR' y obtener el resultado directamente en la terminal sin entrar a la interfaz interactiva."

"Espera... ¿qué es -p? He mirado en claude --help y no lo he visto claro."

Esta conversación es habitual. Muchos desarrolladores usan Claude Code a diario y solo conocen la opción de escribir claude a secas para acceder al modo interactivo, desconociendo las decenas de flags que admite la terminal. Es comprensible; la propia documentación oficial advierte: claude --help no lista todas las opciones. Si confías solo en --help, te perderás gran parte de su funcionalidad.

Básicamente, en los artículos anteriores nos hemos movido dentro del "modo interactivo": inicias, conversas y Claude realiza la tarea. Pero claude es, en esencia, una herramienta de consola, y las herramientas de consola admiten más posibilidades que el simple hecho de "abrir una interfaz de chat": pueden conectarse mediante tuberías, integrarse en scripts o informar de su resultado mediante códigos de salida. Este artículo es ese manual de uso: detalla los comandos, flags, tuberías y códigos de salida para que los consultes siempre que lo necesites.

Al terminar de leer este artículo, obtendrás:

• La lista de comandos principales de claude: iniciar, enviar un prompt inicial, redirecciones, reanudar/recuperar conversaciones, actualizar y login.
• Los flags más habituales (-p / --model / -c / --resume / --permission-mode / --add-dir...) explicados uno a uno y resumidos en una tabla.
• El uso de tuberías y el modo headless (sin interfaz): cómo integrar a Claude en scripts, usarlo como linter y procesar su salida con jq.
• Cómo interpretar los códigos de salida de la terminal para evaluar si una tarea se completó con éxito desde un script.
• Un ejercicio práctico de uso en modo headless: llamadas directas, alimentación por tuberías, formato de salida estructurado y lectura de códigos de salida.

---

01 Conceptos clave: Comando frente a flag

Antes de entrar en las tablas, aclaremos dos conceptos que suelen confundirse. La instrucción completa que escribes en la terminal se divide en dos partes: el comando y los flags (banderas).

Analogía: Enviar un paquete. Escribir claude es la orden de realizar el envío. Los términos como update o mcp son subacciones (comandos) que indican que en este envío no vas a mandar un paquete ordinario, sino que quieres "actualizar la aplicación" o "configurar MCP". Por su parte, opciones como -p o --model son las opciones de envío (flags) que indican cómo quieres gestionarlo: ¿es un envío exprés?, ¿va asegurado?, ¿qué transportista (modelo de IA) debe llevarlo? Defines una acción y puedes marcar múltiples opciones de envío.

Veamos la diferencia en la práctica:

claude update
claude -p "explica esta función" --model sonnet

• Primera línea: claude es la aplicación y update es el comando (una subacción específica que se ejecuta y finaliza).
• Segunda línea: claude se inicia de forma directa sin comando secundario; -p y --model son flags; la frase "explica esta función" es el prompt de entrada asociado a -p.

¿Por qué es importante distinguirlos? Porque en la documentación se organizan en dos tablas independientes y debes saber dónde buscar. Si quieres saber cómo actualizar, iniciar sesión o configurar servidores MCP, consulta la tabla de comandos; si quieres saber cómo cambiar el modelo de IA, evitar la interfaz interactiva o saltarte los avisos de permisos, consulta la tabla de flags.

Un detalle del sistema: si te equivocas al escribir un comando, la terminal te lo indicará. La documentación oficial lo detalla:

Si introduces un subcomando incorrecto, Claude Code sugerirá el comando correcto más cercano y saldrá sin iniciar la conversación. Por ejemplo, al escribir claude udpate mostrará Did you mean claude update?.

Escribir rápido claude udpate es un fallo habitual; la aplicación detectará el error y te preguntará si querías escribir update, evitando iniciar una conversación inútil con un comando erróneo. Es un detalle muy práctico.

💡 Resumen en una frase: La instrucción de consola se divide en dos: el comando define la acción principal (como update o mcp, que finalizan al terminar), y los flags adaptan el comportamiento de esa acción (como -p o --model). Tenlo en cuenta al consultar el manual.

---

02 Comandos principales: Formas de iniciar la conversación

Empecemos con los comandos. En tu día a día interactuarás principalmente con unas pocas opciones, que clasificamos en tres grupos según su objetivo, detallando su sintaxis oficial.

Grupo 1: Iniciar la sesión (el uso común)

El bloque que usarás el 90% del tiempo:

# 1. Iniciar la sesión de forma interactiva
claude

# 2. Iniciar pasando una pregunta inicial (responde y mantiene el chat abierto)
claude "explica este proyecto"

# 3. Obtener el resultado sin entrar a la interfaz interactiva (modo headless / print)
claude -p "explica esta función"

Los dos primeros casos son los habituales. El tercero, claude -p, activa el modo "headless" (sin interfaz) del que hablaremos en este artículo. Muestra la respuesta directamente en la consola y finaliza la ejecución, siendo idóneo para su uso en scripts o tuberías de comandos. Lo analizaremos en la sección 04.

Grupo 2: Reanudar conversaciones (evitar la amnesia de sesión)

Como explicamos en el artículo 19, al abrir una nueva sesión de chat, Claude actúa como un desarrollador que ha olvidado lo hablado anteriormente. Estos comandos sirven para recuperar el contexto de conversaciones previas:

# Reanudar la conversación más reciente en la carpeta actual
claude -c
# (--continue es el nombre completo, -c es el atajo)

# Reanudar una conversación específica por su ID o nombre
claude -r "auth-refactor" "completa este PR"
# (--resume es el nombre completo, -r es el atajo)

La diferencia radica en: "la más reciente" frente a "una en particular".

• -c (--continue): recupera la última conversación en la carpeta actual sin necesidad de recordar identificadores. Es la opción más práctica.
• -r (--resume): recupera una conversación específica indicando su identificador (UUID) o el nombre que le diste al iniciarla. Si no especificas el nombre, mostrará una lista interactiva de las últimas conversaciones para que elijas.

Analogía: Continuar una charla con un compañero. La opción -c equivale a decir "sigamos con lo que estábamos haciendo"; se asume que es el trabajo más reciente sin necesidad de especificarlo. La opción -r equivale a decir "vamos a retomar lo que hablamos el miércoles sobre la refactorización de login"; debes especificar de qué conversación se trata para que recupere esa memoria concreta.

Un hábito recomendado: si estás centrado en una única tarea, usa -c para ahorrar tiempo; si trabajas en múltiples tareas en paralelo (corregir un bug en una carpeta, escribir pruebas en otra), usa -r para recuperarlas por su nombre, el cual debes asignar al iniciar la conversación usando --name (o el atajo -n), de lo contrario tendrás que buscarlas por sus complejos identificadores UUID (como 550e8400-...). El flujo completo sería:

# Iniciar una sesión dándole un nombre identificativo
claude -n "login-refactor"

# Unos días después, retomar la sesión directamente por su nombre
claude -r "login-refactor"

La documentación oficial explica que el nombre definido con --name se mostrará en la lista de /resume y en el título de la terminal, permitiendo recuperar el chat escribiendo claude --resume <nombre>. En entornos multi-tarea, asignar nombres claros te evitará perder tiempo buscando entre cadenas de UUID.

Además, hay una combinación de gran utilidad: puedes usar -c y -p juntos. Escribir claude -c -p "busca errores de tipos" significa "recupera el contexto de la última conversación, pero ejecútala en modo headless, imprimiendo la respuesta y saliendo". Es muy útil en scripts para avanzar en una tarea en varios pasos automatizados (como veremos en la sección 04).

Grupo 3: Mantenimiento y cuenta de usuario

Comandos para la administración del sistema:

# Actualizar a la versión más reciente de la herramienta
claude update

# Instalar o reinstalar una versión específica (admite 'stable', 'latest' o versiones fijas como '2.1.118')
claude install stable

# Iniciar sesión con tu cuenta de Anthropic
claude auth login

# Comprobar el estado del inicio de sesión (devuelve código 0 si está conectado, o 1 si no lo está)
claude auth status

El comando claude install permite especificar una versión concreta, lo cual es muy útil para resolver problemas: si una actualización da fallos, puedes degradar la versión escribiendo claude install 2.1.x para mantener una versión estable mientras se resuelve la incidencia, en lugar de no poder trabajar.

Por su parte, el comando claude auth status devuelve un código de salida 0 si estás autenticado, o 1 si no lo estás. Analizaremos el uso de estos códigos en scripts en la sección 05.

Nota: Estos comandos requieren acceso a internet. Si tienes problemas para iniciar sesión o actualizar, comprueba tu conexión o proxy.

💡 Resumen en una frase: Los comandos principales se dividen en tres grupos: gestión de sesiones (claude, claude "prompt", claude -p), recuperación de contexto (-c para la última conversación, -r para una específica) y mantenimiento del sistema (update, install, auth); usar -c y -r evita que Claude inicie conversaciones sin recordar el contexto anterior.

---

03 Flags más comunes: Configuración de la sesión en la terminal

Con los comandos explicados, pasemos a los flags. Existen decenas de opciones, pero en el día a día interactuarás principalmente con este grupo (hemos incluido una tabla de referencia completa al final en la sección 06 para su consulta; esta sección se enfoca en explicar su funcionamiento).

-p / --print: Ejecución en modo headless (sin interfaz)

El flag más importante. Al añadir -p, Claude no abre la interfaz de chat; lee el prompt de entrada, realiza la tarea, muestra la respuesta en la consola y finaliza la sesión sin interacción.

claude -p "¿qué hace el módulo auth en este proyecto?"

Es el interruptor que activa el modo "headless" (sin interfaz), la base para la automatización y la integración en scripts que veremos en la sección 04.

--model: Selección del modelo de IA para la sesión

Permite definir el modelo de IA para la conversación actual, sobrescribiendo la preferencia guardada en tu configuración:

claude --model sonnet
claude --model opus
claude --model claude-sonnet-4-6   # También admite el identificador técnico completo

Puedes usar los nombres simplificados (sonnet u opus que apuntan a sus versiones más recientes) o los nombres técnicos. Explicamos cómo elegir el modelo en el artículo 05; este flag te permite cambiarlo puntualmente en la terminal.

--permission-mode: Nivel de control de permisos de la sesión

Establece el comportamiento de la autorización de herramientas al iniciar la sesión. Define "qué tan estricto es el control de permisos de Claude al trabajar":

claude --permission-mode plan

Los valores admitidos por el flag son:

default, acceptEdits, plan, auto, dontAsk o bypassPermissions. Sobrescribe la opción defaultMode del archivo de configuración.

Los niveles más utilizados son: plan (modo planificador, no realiza cambios), acceptEdits (aprueba la edición de archivos de forma automática) o bypassPermissions (permite todo sin preguntar; usar con precaución). Explicaremos el comportamiento de estos modos en el artículo 35; quédate con que este flag define el nivel de permisos al iniciar la terminal.

--dangerously-skip-permissions: Omitir todas las consultas de permisos

Un flag de seguridad importante. Su función es saltarse todas las solicitudes de confirmación al ejecutar herramientas. La documentación oficial indica que equivale a usar --permission-mode bypassPermissions:

claude --dangerously-skip-permissions

Al activarlo, Claude modificará archivos y ejecutará comandos en la terminal de forma directa sin pedir confirmaciones. El término dangerously (peligrosamente) en el nombre es una advertencia de Anthropic. En los artículos 20 y 21 insistimos en la importancia de mantener el control; usar este flag equivale a soltar las riendas de seguridad por completo.

Sigue esta regla de seguridad: utilízalo únicamente en entornos aislados y controlados donde un error no cause daños (como contenedores de usar y tirar, entornos de pruebas o pipelines de CI aislados). Evita usarlo en tu carpeta de desarrollo habitual y en servidores que contengan datos de producción. Si necesitas automatización en modo headless sin confirmaciones constantes, es más seguro dar accesos específicos a herramientas con --allowedTools o usar --permission-mode acceptEdits (que solo autoriza cambios en archivos), reduciendo la superficie de riesgo en comparación con el bypass total.

--add-dir: Conceder acceso a carpetas adicionales

Por defecto, Claude solo puede leer y modificar archivos de la carpeta en la que se inicia. --add-dir te permite añadir carpetas adicionales a su área de trabajo:

claude --add-dir ../apps ../lib

Caso de uso típico: estás en un monorepo y tu proyecto depende de una biblioteca situada en una carpeta adyacente. Quieres que Claude pueda leer y modificar ambas. Ten en cuenta esta advertencia oficial:

Concede permisos de acceso a los archivos de esas carpetas; las opciones de configuración de los directorios .claude/ de esas rutas no se cargarán de forma automática.

Es decir: --add-dir otorga permisos de lectura y escritura sobre los archivos, pero no carga los archivos CLAUDE.md ni los Skills definidos en esas carpetas.

--output-format: Formato de salida de la respuesta

Solo tiene efecto al usarse junto a -p (modo print), y define la estructura del resultado en la terminal:

claude -p "resume este proyecto" --output-format json

Las opciones disponibles son: text (por defecto, texto plano), json (devuelve un objeto JSON con metadatos como el ID de sesión o el coste de la llamada) y stream-json (devuelve eventos JSON en streaming, uno por línea). Si quieres extraer el coste de la llamada o el ID de la conversación en un script, usa la salida json (veremos un ejemplo con jq en la sección 04).

--allowedTools / --disallowedTools: Definición de accesos rápidos

Permiten autorizar (o denegar) el uso de herramientas específicas de antemano. Es muy útil en scripts headless para evitar que la ejecución se detenga esperando una confirmación en la consola (lo que causaría que el script falle en entornos automatizados):

claude -p "pasa los tests y corrige fallos" --allowedTools "Bash,Read,Edit"

Las herramientas definidas en --allowedTools se ejecutarán directamente sin pedir confirmación; --disallowedTools hará lo contrario. Utiliza la sintaxis de las reglas de autorización (ver artículo 20), como "Bash(git diff *)" para permitir únicamente llamadas a git diff.

No lo confundas con el flag --tools (que elimina por completo el acceso a las herramientas indicadas del contexto de Claude); --allowedTools mantiene el acceso pero se salta las consultas de confirmación.

Parámetros de control para automatización (modo headless)

Estos flags son útiles en scripts headless para evitar bucles infinitos o desbordamientos de coste:

# Limita el número máximo de turnos de conversación en el script (el script fallará al superarlo)
claude -p --max-turns 3 "realiza la tarea"

# Detiene la ejecución si el coste acumulado supera la cantidad de dólares indicada
claude -p --max-budget-usd 5.00 "realiza la tarea"

Un consejo sobre --max-turns: al escribir automatizaciones, si olvidas este flag y Claude entra en un bucle de corrección de errores intentando solucionar un fallo sin éxito, el contador de turnos subirá consumiendo tu saldo de API. Configurar --max-turns en tus scripts establece un límite de seguridad rígido; el script fallará si supera los turnos, pero evitarás sorpresas en el coste.

💡 Resumen en una frase: Los flags indispensables son: -p para ejecutar sin interfaz, --model para definir el modelo, --permission-mode para la seguridad inicial, --add-dir para dar acceso a otras carpetas, --output-format json para salida estructurada y --allowedTools para preautorizar herramientas. En scripts, añade --max-turns o --max-budget-usd como medidas de control de costes.

---

04 Automatización y tuberías: Integración de Claude en la consola

Aquí es donde el flag claude -p muestra todo su potencial. En lugar de usar a Claude a través de una interfaz de chat, lo integramos en la consola como un comando más del sistema, pudiendo recibir datos de otras herramientas mediante tuberías (|) y redirigir su salida.

Analogía: Una máquina en una línea de montaje. La interfaz de chat es como realizar el trabajo a mano en una mesa; el modo headless integra a Claude en la línea de producción: la máquina anterior (por ejemplo, cat o git diff) le suministra la materia prima, Claude la procesa y el resultado pasa directamente al siguiente puesto de la línea (un archivo o una utilidad como jq). Todo el flujo se ejecuta de forma autónoma.

Tuberías: Alimentar a Claude con datos de la terminal

Al ejecutarse en modo headless, Claude Code lee la entrada estándar (stdin), lo que te permite alimentarlo con datos usando tuberías (|):

cat build-error.txt | claude -p 'explica la causa de este error de compilación de forma concisa' > output.txt

Esta instrucción encadena tres pasos: cat lee el archivo de log → la tubería pasa el texto a claude -p → Claude analiza el error y redirige la respuesta a output.txt. Todo el proceso se realiza sin abrir interfaces de usuario, lo que facilita su integración en scripts de automatización.

Límite técnico a tener en cuenta (a partir de la versión v2.1.128): el volumen de datos transferido por stdin mediante tuberías tiene un límite máximo de 10MB. Si superas este límite, Claude Code devolverá un error y terminará la ejecución con un código de salida distinto de cero. Para analizar volúmenes mayores, escribe los datos en un archivo y pasa la ruta de ese archivo en tu prompt.

Uso como linter personalizado del repositorio

Si empaquetas el comando headless en un script de desarrollo, puedes usar a Claude como un validador personalizado del código. Un ejemplo típico en un archivo package.json consiste en pasarle el diff de git frente a la rama principal para buscar errores de ortografía o sintaxis:

{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
  }
}

Al ejecutar npm run lint:claude se iniciará la validación. Ventaja del uso de tuberías: le estás pasando los datos de forma directa, por lo que Claude no necesita permisos de ejecución de herramientas (Bash) para leer el diff de git.

Procesar salidas estructuradas con jq

Si necesitas capturar únicamente el texto de respuesta o el identificador del chat dentro de un script, combina --output-format json con jq (el procesador JSON de consola):

# Extraer únicamente el texto de la respuesta
claude -p "resume este proyecto" --output-format json | jq -r '.result'

La salida en formato json genera un objeto con metadatos: la respuesta está en .result, el ID de conversación en .session_id y el gasto en .total_cost_usd. Para encadenar múltiples pasos de conversación en un script, captura el .session_id y pásalo con --resume:

session_id=$(claude -p "inicia la revisión" --output-format json | jq -r '.session_id')
claude -p "continúa con esa revisión" --resume "$session_id"

Dar una "identidad temporal" a la llamada

En ejecuciones desasistidas, a veces quieres que Claude actúe con un rol específico para esa tarea (como "actúa como experto en seguridad y busca vulnerabilidades"). Usa --append-system-prompt para añadir la directriz al final de la instrucción del sistema; en este ejemplo le pasamos el diff de un PR para una auditoría de seguridad:

gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json

Distingue estos dos flags para no cometer errores: --append-system-prompt añade la directriz al final del mensaje base, manteniendo las capacidades nativas de desarrollo y reglas de seguridad de Claude Code; --system-prompt reemplaza por completo la instrucción del sistema, eliminando la configuración de herramientas y reglas básicas de la herramienta (tendrás que definirlo todo tú en el prompt). El 90% de las veces querrás usar append (añadir) en lugar de system-prompt (reemplazar).

--bare: Mayor velocidad en ejecuciones automatizadas

Para scripts de consola existe el flag --bare (modo básico). La documentación oficial lo explica:

Modo mínimo: omite la detección de hooks, skills, plugins, servidores MCP, almacenamiento de memoria automático y la búsqueda de CLAUDE.md para agilizar el inicio en llamadas programadas.

Básicamente: la llamada habitual claude -p carga todo el contexto del repositorio (tus CLAUDE.md, Skills y MCP); --bare omite este paso, dejando únicamente las herramientas de sistema básicas (Bash, lectura y edición de archivos). Esto acelera el inicio de la llamada y ofrece resultados consistentes entre máquinas (al no verse afectado por los Skills locales del usuario). Es ideal en entornos de CI y scripts. La documentación oficial indica además que en versiones futuras --bare se aplicará por defecto en las llamadas con -p.

Compara las diferencias entre el modo interactivo y headless:

Dimensión	Modo interactivo (claude)	Modo headless (claude -p)
Interfaz de chat	✅ Sí, conversas en consola	❌ No, imprime y sale
Intervención del usuario	✅ Requieres estar presente	❌ Ejecución desasistida en scripts
Uso de tuberías	❌ No soportado	✅ Sí, lee stdin y admite redirecciones
Gestión de permisos	Pregunta en consola ante cada acción	Configurada de antemano con flags
Ámbito de uso	Programar en el día a día	Integración en CI, linters, scripts de automatización

💡 Resumen en una frase: claude -p permite integrar a Claude en tuberías de consola: puedes encadenar comandos con cat ... | claude -p ... > out.txt, capturar metadatos con --output-format json | jq y acelerar el inicio en scripts con --bare; preconfigura los permisos mediante flags para que el script no se detenga.

---

05 Códigos de salida: Evaluación del resultado en scripts

Este concepto es indispensable para los desarrolladores que escriben automatizaciones.

Analogía: El resultado Apto o No Apto de una prueba. En la terminal, cada comando devuelve un código numérico de finalización al terminar: 0 indica que el proceso finalizó con éxito, cualquier otro número indica que se produjo un error. No se muestra al usuario, sino que se pasa al script que invocó la orden para que decida si continuar con el flujo.

Puedes consultar el código de salida del último comando ejecutado escribiendo:

claude auth status
echo $?

La variable $? almacena el código de salida de la última orden en la terminal.

La documentación oficial detalla los siguientes códigos de salida:

Comando / Escenario	Código de salida	Significado
claude auth status (conectado)	0	Autenticado con éxito
claude auth status (no conectado)	1	No se ha iniciado sesión
claude -p --max-turns N (límite superado)	Distinto de 0	Se alcanzaron los turnos límite (sale con error)
Datos en stdin superiores a 10MB	Distinto de 0	Entrada excesiva (detiene la ejecución con error)
claude daemon status (supervisor inactivo)	1	El supervisor de sesiones en segundo plano no se está ejecutando

¿Cómo se aplica esto en un script? Por ejemplo, si en tu pipeline de CI quieres verificar que el entorno está autenticado antes de continuar (y detener la ejecución si no lo está), utiliza el código de salida de claude auth status:

# Si el código de salida es distinto de 0 (no conectado), muestra el aviso y finaliza
claude auth status || { echo "Error: sesión no iniciada en Claude Code"; exit 1; }

El operador || indica "si la orden de la izquierda devuelve un código distinto de cero, ejecuta las instrucciones de la derecha". Puedes usar este control en tus scripts: comprueba el estado al inicio con claude auth status para detener el flujo si el token ha expirado, en lugar de fallar a mitad de la tarea.

Quédate con esta regla básica de la terminal: 0 indica éxito (continuar); cualquier otro número indica fallo (detener). Todos los comandos de Claude Code siguen esta convención.

💡 Resumen en una frase: Los códigos de salida informan del resultado al script: 0 indica correcto y un valor distinto de 0 indica error; claude auth status devuelve 0 o 1 según el estado de inicio de sesión, y los fallos por desbordamiento de turnos o límites de tubería devuelven códigos de error recuperables con $? o ||.

---

06 Tabla completa de flags: Guía de consulta rápida

A continuación recopilamos los flags que admite Claude Code, organizados por categorías. Guárdala como referencia de consulta.

Nota: como indica la documentación oficial, claude --help no detalla todas las opciones disponibles; esta tabla sirve de complemento.

Gestión de sesión

Flag	Atajo	Función
--print	-p	Ejecuta en modo headless, imprimiendo la respuesta y finalizando la sesión
--continue	-c	Reanuda la conversación más reciente de la carpeta actual
--resume	-r	Reanuda una conversación específica por su nombre o ID, o muestra la lista
--name	-n	Asigna un nombre descriptivo a la conversación para recuperarla después
--fork-session	—	Crea una nueva sesión a partir de una conversación previa sin sobrescribirla (se usa con -r o -c)
--session-id	—	Especifica la conversación indicando su identificador técnico UUID

Modelo e interactividad

Flag	Función
--model	Define el modelo de IA para la sesión (como sonnet u opus), sobrescribiendo la configuración global
--fallback-model	Especifica el modelo de respaldo si el principal da error (se aplica en modo headless y segundo plano)
--permission-mode	Define la autorización de herramientas (default/acceptEdits/plan/auto/dontAsk/bypassPermissions)
--allowedTools	Lista de herramientas que se autorizan de forma automática sin preguntar
--disallowedTools	Lista de herramientas bloqueadas
--dangerously-skip-permissions	Desactiva las solicitudes de confirmación de herramientas (equivale a bypassPermissions, usar con precaución)

Directorios y configuración

Flag	Función
--add-dir	Concede permisos de acceso a carpetas adicionales fuera del directorio de inicio
--settings	Pasa un archivo JSON de configuración o una cadena de opciones para sobrescribir los valores
--setting-sources	Define qué niveles de configuración cargar (como user, project o local)
--mcp-config	Pasa la configuración de MCP desde un archivo o una cadena JSON
--bare	Modo básico: acelera el inicio de scripts omitiendo Hooks, Skills, plugins, MCP y la lectura de CLAUDE.md

Parámetros en modo headless (con -p)

Flag	Función
--output-format	Define el formato de la respuesta: text (por defecto), json o stream-json
--input-format	Define el formato de la entrada: text o stream-json
--max-turns	Limita el número de turnos de la llamada para evitar bucles infinitos en scripts
--max-budget-usd	Detiene la ejecución si el coste de la llamada supera el límite de dólares indicado
--verbose	Muestra en detalle todos los mensajes del proceso en la terminal
--append-system-prompt	Añade instrucciones al final del system prompt nativo
--system-prompt	Reemplaza por completo el system prompt nativo por el texto indicado

Otros flags

Flag	Atajo	Función
--version	-v	Muestra la versión instalada
--ide	—	Conecta con un IDE activo de forma automática al iniciar
--debug	—	Activa el modo de depuración (permite filtrar categorías como "api,mcp")

Utiliza esta tabla para buscar opciones específicas al automatizar tareas. Para configuraciones avanzadas (relacionadas con sesiones en segundo plano o control remoto), consulta la sección CLI en la documentación oficial de la herramienta.

💡 Resumen en una frase: La tabla agrupa las opciones por categorías para facilitar su consulta; algunos flags avanzados no se muestran en --help, por lo que esta guía sirve de referencia para complementar la ayuda en consola.

---

07 Ejercicio: Usar claude -p en tuberías de consola

Consolidemos lo aprendido ejecutando una llamada headless en la consola. Realizaremos todo el ejercicio en la terminal, sin abrir la interfaz interactiva de chat, comprobando la integración de la herramienta con tuberías.

Nota: este ejercicio consume saldo de API y requiere conexión a internet.

Paso 1: Ejecutar una llamada headless directa

Escribe en tu consola (no dentro de una conversación de Claude Code):

claude -p "explica brevemente la diferencia entre git rebase y git merge en una frase"

Resultado esperado: la terminal mostrará la respuesta directamente y terminará la ejecución, devolviéndote la línea de comandos. Has comprobado el modo print sin interfaz.

Paso 2: Pasar datos a través de una tubería

Crearemos un archivo con código erróneo y se lo pasaremos a Claude para su análisis:

printf 'def add(a, b):\n    return a - b\n' > buggy.py
cat buggy.py | claude -p "indica el error en este código en una línea"

Resultado esperado: Claude procesará los datos recibidos por stdin y devolverá una respuesta similar a: "El nombre de la función es add, pero resta los argumentos en el return". Claude ha analizado el código sin necesidad de usar herramientas de lectura, ya que el contenido se le suministró directamente por la tubería.

Paso 3: Obtener salida estructurada JSON y procesarla con jq

Solicitamos la salida estructurada:

claude -p "qué es Python en una frase" --output-format json

Resultado esperado: el resultado será un bloque JSON con metadatos que incluye los campos result, session_id y total_cost_usd. Si tienes instalada la utilidad jq, escribe lo siguiente para filtrar el resultado:

claude -p "qué es Python" --output-format json | jq -r '.result'

Resultado esperado: mostrará únicamente el texto plano de la respuesta, limpiando la estructura JSON. Esta es la vía recomendada para capturar respuestas limpias en scripts de automatización.

Paso 4: Comprobar el código de salida de la terminal

claude auth status
echo $?

Resultado esperado: si has iniciado sesión con éxito, echo $? devolverá 0; en caso contrario devolverá 1. El script utilizará este código numérico para evaluar el estado y decidir si continuar con el flujo.

Al completar estos pasos habrás recorrido la integración en modo headless: llamadas directas, alimentación por tuberías, capturar salidas con jq y verificar estados con códigos de salida. Cualquier automatización que programes se apoyará en la combinación de estas técnicas.

💡 Resumen en una frase: Practica la automatización: realiza una llamada con -p → pasa un archivo por tubería con cat | claude -p → filtra la salida estructurada con json | jq → comprueba el código de finalización con $?; esta prueba sienta las bases para integrar a Claude Code en tus herramientas y tareas de consola.

---

08 Resumen

En este artículo hemos recopilado la referencia de comandos, flags, tuberías y códigos de salida de la CLI de Claude Code.

Repasemos los conceptos clave:

Objetivo	Herramienta / Método	Detalle clave
Diferenciar el formato	Comando frente a flag	Los comandos definen subacciones específicas (update); los flags configuran la llamada (--model).
Reanudar conversaciones	Opciones -c y -r	-c recupera la última sesión; -r recupera una sesión concreta por su nombre.
Ejecutar sin interfaz	Flag -p (print)	Modo headless idóneo para scripts de consola y pipelines de CI.
Configurar en consola	Flags habituales	--model para el modelo, --permission-mode para la seguridad y --add-dir para carpetas adicionales.
Encadenar comandos	Tuberías de consola	Envía datos a través de stdin e integra el procesamiento JSON de jq.
Controlar ejecuciones	Códigos de salida	El código 0 indica éxito, valores distintos de 0 informan de fallos utilizables con $? en scripts.

Ahora deberías ser capaz de: analizar la estructura de un comando de Claude Code, reanudar chats anteriores mediante -c y -r, automatizar flujos en modo headless usando -p, encadenar comandos mediante tuberías filtrando la salida JSON con jq, evaluar la ejecución en scripts a través de los códigos de salida, y consultar la tabla de flags para adaptar la herramienta a tus necesidades. La CLI te permite integrar a Claude Code como una herramienta programable más dentro de tus pipelines y scripts de desarrollo.

Conocer los comandos de consola te abrirá la puerta a la automatización de tus flujos diarios, permitiéndote delegar comprobaciones repetitivas en scripts integrados con Claude.

---

En el próximo artículo, 35 "Modos de control y ejecución", profundizaremos en los niveles de seguridad. Hemos presentado la opción --permission-mode en este artículo, detallando que permite establecer diferentes políticas de autorización. En la siguiente sección explicaremos detalladamente qué implican modos como plan, acceptEdits o bypassPermissions, qué tareas se permiten en cada nivel de forma automática, cuántas consultas realiza Claude en la terminal y cómo alternar entre modos en caliente usando atajos de teclado. Piensa en esto: ¿qué diferencia hay en velocidad y seguridad al programar si dejas que Claude modifique archivos directamente frente a tener que confirmar cada cambio? Lo analizaremos en el próximo artículo.

---

Lecturas recomendadas

• Introducción a Claude Code: Primeros pasos
• Configuración de API: Suscripción o claves de API en la sesión
• Checkpoints (puntos de control): Puntos de restauración seguros en git