Ejecuta Claude Code desde un script con claude -p

Añade -p a un comando claude y responde una vez, imprime el resultado y termina. Así se puede usar dentro de scripts de terminal, pasos de compilación y tareas programadas. La pega: no hay nadie para pulsar sí, así que tienes que decidir de antemano qué puede hacer.

Lo básico

claude -p "What does the auth module do?"

Claude Code termina con código 0 cuando la ejecución sale bien y con un código distinto de cero cuando falla, así que un script puede decidir según ese código. También lee la entrada estándar, así que puedes pasarle texto y mandar la respuesta a un archivo:

cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

La entrada que le pasas está limitada a 10 MB. Para algo más grande, escríbelo en un archivo y menciona la ruta del archivo en tu petición.

Elige el formato de salida

• text (por defecto)Texto plano, para personas o para un archivo.
• jsonUn objeto JSON con la respuesta en result, más el ID de sesión y metadatos, entre ellos total_cost_usd, para que un script pueda seguir el gasto.
• stream-jsonUn evento JSON por línea según ocurre. Necesita --verbose, y --include-partial-messages para recibir los tokens según llegan.

claude -p "Summarize this project" --output-format json | jq -r '.result'

Para recibir una respuesta con la forma que tú defines, añade --json-schema con un esquema JSON. Los datos vuelven en el campo structured_output. Si una ejecución termina sin una salida estructurada válida, por ejemplo porque Claude rechazó la petición, ese campo no aparece, así que comprueba que existe antes de usarlo.

Qué puede hacer cuando nadie puede decir sí

En una ejecución de claude -p en el modo Manual por defecto, una llamada a una herramienta que normalmente pediría aprobación se rechaza, salvo que algo la apruebe. Tienes tres formas sencillas de decir sí de antemano:

• Permitir herramientas concretas: --allowedTools "Read,Edit". Si pones Bash permites comandos de terminal, y puedes acotarlo con las mismas reglas de patrón que en los ajustes: "Bash(git diff *),Bash(git status *)". El * final admite cualquier comando que empiece por esas palabras, y el espacio antes del asterisco importa, porque Bash(git diff*) también admitiría git diff-index.
• Elegir un modo: --permission-mode acceptEdits deja que Claude escriba archivos sin preguntar. dontAsk rechaza todo lo que no esté aprobado de antemano, y va bien para tareas muy cerradas. auto deja la decisión a un clasificador. Mira los modos de permisos explicados.
• Sin avisos del todo: --permission-prompts none rechaza lo que habría preguntado y avisa a Claude de que nadie puede aprobarlo, para que no insista.

Hay una lista de partida de reglas en una lista de partida de reglas de permisos. Las reglas deny siguen valiendo en una ejecución de script.

El modo bare y por qué importa

Por defecto, una ejecución con -p carga lo mismo que una sesión interactiva: hooks, skills, subagentes, plugins, servidores MCP, memoria automática y CLAUDE.md. Con --bare se salta todo eso. Entonces le pasas solo lo que quieras, por ejemplo con --settings, --mcp-config o --append-system-prompt.

claude --bare -p "Summarize README.md" --allowedTools "Read"

Dos cosas que conviene saber. Primero, el modo bare no usa el inicio de sesión de tu suscripción: necesita ANTHROPIC_API_KEY o las credenciales de otro proveedor. Segundo, la documentación recomienda el modo bare para scripts y CI, porque así el resultado deja de depender de los hooks o servidores que haya en esa máquina.

Un aviso sobre repositorios que no escribiste tú

Sin --bare, una ejecución con -p ejecuta los hooks del .claude/settings.json del proyecto y conecta los servidores de su .mcp.json, incluso en una carpeta en la que nunca confiaste. El modo print no muestra ningún aviso de confianza ni pide aprobar cada servidor. Así que, antes de apuntar un script a un repositorio que no escribiste tú, lee esos dos archivos o usa --bare.

Seguir una conversación

claude -p "Review this codebase for performance issues"
claude -p "Now focus on the database queries" --continue

--continue retoma la conversación más reciente. Para retomar una concreta, guarda su ID:

session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

Bueno saber

• Comandos: las skills que invocas por nombre funcionan si pones /nombre-de-la-skill en la petición. Los comandos que solo existen en la interfaz de terminal, como /login, no están disponibles.
• Parar una ejecución: SIGTERM termina con código 143 y deja sin acabar el turno en curso. Manda antes SIGINT si quieres que el turno termine limpio.
• Gasto: la documentación menciona una opción --max-budget-usd que limita el gasto de una ejecución. Mira la referencia de la línea de comandos para ver cómo funciona en tu versión.
• No todas las opciones se combinan con -p. Claude Code rechaza algunas con un error que nombra el conflicto.

Pruébalo con algo inofensivo

1. Ejecuta echo "hello" | claude -p "reply with one word" y comprueba que recibes una respuesta.
2. Ejecuta lo mismo con --output-format json y mira los campos.
3. Ejecuta echo $? justo después (o echo %errorlevel% en el cmd de Windows) y confirma que sale 0.

Límites

• Las opciones y los valores por defecto cambian entre versiones, y varios detalles de la página de documentación piden una versión mínima. Mira la tuya con claude --version.
• Esto cubre la línea de comandos. Los paquetes de Python y TypeScript tienen su propia documentación.

Esta página sigue la documentación de Anthropic sobre ejecutar Claude Code por programa tal como la leemos en octubre de 2026. No tenemos relación con Anthropic. La escribimos a partir de la documentación y no hemos probado todos los ejemplos.

Mira también: Programar con /loop · Trabajar hacia un objetivo con /goal · Flujos de cada día · Claude Code en GitHub Actions.

La skill gratis loop-stop da a las tareas largas un límite y una regla de parada. Si quieres una segunda mirada a tu CLAUDE.md y a tus ajustes, el Tune-Up Kit es una lista de comprobación para eso (la ficha está en inglés).