Usar Claude Code en scripts y CI con claude -p

Hola, bienvenido. En esta lección empezamos la sección de automatizar fuera de la sesión, después de construir en la lección anterior la bandeja de feedback con Spec-Driven Development, siempre en una sesión interactiva. Vamos a ver el modo no interactivo de Claude Code, claude -p, que ejecuta un prompt, imprime el resultado y termina, como cualquier otro comando de la terminal. Veremos qué carga una ejecución así, qué puede hacer sin preguntarte y cómo decidirlo con los permisos y el modo, cómo pedirle la respuesta en JSON para usarla desde un script, cómo evitar sorpresas de coste y cómo autenticarte en un servidor de CI con tu suscripción.

¿Para qué sirve, si ya tenemos la sesión? Hasta ahora, cada vez que querías algo de Claude abrías claude y escribías. Sin embargo, hay tareas que se repiten igual cada vez, como revisar el diff antes de un commit o explicar por qué se ha parado el circuito de calidad, y que encajan mejor en un script, en un alias de tu terminal o en un paso de tu CI. Para eso está -p: el mismo agente, con las mismas herramientas y el mismo contexto del proyecto, pero sin nadie delante. Y eso cambia mucho las cosas, porque en una sesión interactiva hay alguien que responde a los avisos de permiso y que confirma los gastos, y en un script no.

Para seguir la lección necesitas el proyecto con el último commit, los contenedores de Sail levantados y jq, que instalamos en la lección Configurar hooks en Claude Code: eventos y settings.json. De cada opción te indico la versión mínima cuando la documentación la da.

Añadir -p, o su forma larga --print, a cualquier comando claude lo ejecuta en modo no interactivo: Claude trabaja con el prompt que le pasas, imprime la respuesta y el proceso termina. Desde la raíz del proyecto:

Como cualquier comando de la terminal, termina con código 0 si todo ha ido bien y con otro código si ha fallado, así que un script puede decidir qué hacer según el resultado. La documentación distingue 2 tipos de fallo. Si le pasas una opción que no existe, Claude Code escribe el error en la salida de error antes de empezar, y si el fallo ocurre durante la ejecución, como que no haya ninguna cuenta con la sesión iniciada, lo imprime como resultado en la salida normal.

Además, -p lee la entrada estándar, así que puedes pasarle datos con una tubería como a cualquier otra herramienta de línea de comandos. Este ejemplo le pasa la salida del circuito de calidad y le pide que la interprete:

Fíjate en una ventaja de hacerlo así: Claude recibe la salida ya hecha y no necesita permiso para ejecutar nada. La entrada por tubería tiene un tope de 10 MB, y si lo pasas, Claude Code termina con un error claro. Para contenidos más grandes, la documentación recomienda escribirlos en un archivo y darle la ruta en el prompt.