Ir al contenido
Mastering Claude

Inicio / Gestos cotidianos

Gestos cotidianos9 minApplication

Modo headless, estilos de salida y tareas en segundo plano

El modo headless ejecuta Claude Code sin interfaz interactiva con -p, --output-format determina si la salida sigue siendo texto o se convierte en un objeto JSON utilizable por un script, con el costo total incluido, y run_in_background deja que un comando largo continúe sin bloquear la conversación.

El modo headless ejecuta Claude Code sin interfaz interactiva, en un solo comando que devuelve su resultado y se detiene. El indicador -p (o --print) activa este modo, con un prompt dado como argumento.

claude -p "Resume los archivos modificados en este repositorio" --output-format json

Tres formatos de salida para tres usos

El parámetro --output-format acepta tres valores. text, el valor predeterminado, devuelve una respuesta en lenguaje natural destinada a un humano. json devuelve un único objeto estructurado, con el resultado, el identificador de sesión y el costo total en dólares junto con un desglose por modelo, una forma que un script puede leer sin analizar texto libre. stream-json devuelve la misma información en JSON Lines, un objeto por línea, útil cuando un programa quiere reaccionar antes de que termine por completo la ejecución. Un indicador --bare se salta el descubrimiento automático de hooks, skills, comandos personalizados, subagentes, plugins, servidores MCP, memoria automática y archivos CLAUDE.md al arrancar, lo que acelera el inicio. La documentación oficial lo recomienda para las llamadas con script y señala que podría convertirse en el valor predeterminado de -p en una versión futura. Esta ganancia de velocidad tiene una contrapartida que nada indica en pantalla: el modo bare nunca lee los identificadores OAuth ni el llavero del sistema, por lo que no se apoya en la conexión por suscripción, y un script que lo use debe fijar la variable ANTHROPIC_API_KEY en su entorno para autenticarse ante la API de Anthropic.

Dejar que un comando largo se ejecute sin bloquear

Un comando largo lanzado por la herramienta Bash de Claude Code puede pedir run_in_background: true en lugar de esperar a que termine. La herramienta devuelve entonces de inmediato un identificador de tarea, el comando continúa en segundo plano, y su salida se vuelve a leer después con la herramienta Read. El atajo Ctrl+B mientras un comando se ejecuta hace el mismo cambio a mano, y el comando /tasks enumera y detiene las tareas en curso.

Este cambio también ocurre solo: un comando que llega a su plazo de expiración sin haber terminado pasa automáticamente a tarea en segundo plano en lugar de cortarse en seco, salvo para tres familias de comandos que siguen siendo bloqueantes hasta el final, los que empiezan por sleep, los que contienen git, y los comandos demasiado compuestos para ser analizados por el mecanismo de seguridad. Combinar los dos gestos, modo headless para la entrada y la salida, tarea en segundo plano para la duración, hace que un script sea capaz de pilotar Claude Code sin esperar nunca bloqueado frente a una terminal. El identificador de sesión que --output-format json devuelve explícitamente es el mismo que retoma cada gesto rápido de la terminal con --resume.

Figure 1

De un comando headless a una salida utilizable por un script

01
Entrada en modo headless
El indicador -p envía un prompt a Claude Code sin abrir una interfaz interactiva.
02
Ejecución no interactiva
Claude Code procesa la solicitud solo, sin esperar una respuesta humana entre los pasos.
03
Salida elegida
El parámetro --output-format determina si el resultado sale en texto, en un único objeto JSON, o en JSON Lines en flujo.
04
El script lee el resultado
Un programa externo recupera la salida estructurada, con el costo total y el identificador de sesión, sin analizar texto libre.
05
Comando largo en tarea de fondo
Si un paso dura demasiado, run_in_background lo hace continuar mientras el script queda libre para lo que sigue.
La secuencia muestra cómo una solicitud enviada en modo headless atraviesa una ejecución no interactiva hasta llegar a una salida estructurada que un script puede leer, con un posible cambio a tarea en segundo plano si un paso dura demasiado.
Calíbralo tú mismo

Un desarrollador lanza claude -p con --output-format json en un pipeline de despliegue, y el script del pipeline recupera el campo total_cost_usd del resultado para añadirlo al panel de costos.

Escriba en una frase lo que esta situación establece, y en una frase lo que no establece.

Lo que hay que recordar
  • El indicador -p activa el modo headless, sin interfaz interactiva, para un uso con script de Claude Code.
  • --output-format json devuelve un objeto único que contiene el resultado, el identificador de sesión y el costo total en dólares con su desglose por modelo.
  • --bare se salta el descubrimiento automático de hooks, skills y archivos de contexto al arrancar, una ganancia de velocidad recomendada para las llamadas con script, pero nunca lee los identificadores OAuth ni el llavero, por lo que ANTHROPIC_API_KEY se vuelve necesaria.
  • run_in_background devuelve inmediatamente un identificador de tarea y deja que un comando largo continúe mientras la conversación sigue su curso.
  • Un comando que llega a su plazo de expiración cambia automáticamente a tarea en segundo plano, salvo que empiece por sleep, contenga git, o sea demasiado compuesto para ser analizado.
Hazlo ahora

Lance desde su terminal claude -p "una palabra al azar" --output-format json en una carpeta que no contenga ningún dato sensible, y localice en la salida los campos session_id y total_cost_usd.

Verificar en la fuente

Cada afirmación datable de esta lección remite aquí al texto público que la respalda. Una fuente que no se abre no prueba nada.