Saltar al contenido principal
El Agent SDK le proporciona las mismas herramientas, bucle de agente y gestión de contexto que potencian Claude Code. Está disponible como CLI para scripts e CI/CD, o como paquetes de Python y TypeScript para control programático completo.
La CLI se llamaba anteriormente “modo sin interfaz”. La bandera -p y todas las opciones de CLI funcionan de la misma manera.
Para ejecutar Claude Code mediante programación desde la CLI, pase -p con su indicación y cualquier opción de CLI: 
claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"
Esta página cubre el uso del Agent SDK a través de la CLI (claude -p). Para los paquetes SDK de Python y TypeScript con salidas estructuradas, devoluciones de llamada de aprobación de herramientas y objetos de mensaje nativos, consulte la documentación completa del Agent SDK.

​
Uso básico

Agregue la bandera -p (o --print) a cualquier comando claude para ejecutarlo de forma no interactiva. Todas las opciones de CLI funcionan con -p, incluyendo: Este ejemplo le pregunta a Claude sobre su base de código e imprime la respuesta: 
claude -p "What does the auth module do?"

​
Ejemplos

Estos ejemplos destacan patrones comunes de CLI.

​
Obtener salida estructurada

Utilice --output-format para controlar cómo se devuelven las respuestas:
  • text (predeterminado): salida de texto sin formato
  • json: JSON estructurado con resultado, ID de sesión y metadatos
  • stream-json: JSON delimitado por saltos de línea para transmisión en tiempo real
Este ejemplo devuelve un resumen del proyecto como JSON con metadatos de sesión, con el resultado de texto en el campo result: 
claude -p "Summarize this project" --output-format json
Para obtener una salida que se ajuste a un esquema específico, utilice --output-format json con --json-schema y una definición de JSON Schema. La respuesta incluye metadatos sobre la solicitud (ID de sesión, uso, etc.) con la salida estructurada en el campo structured_output. Este ejemplo extrae nombres de funciones y los devuelve como una matriz de cadenas: 
claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'
Utilice una herramienta como jq para analizar la respuesta y extraer campos específicos:
# Extract the text result
claude -p "Summarize this project" --output-format json | jq -r '.result'

# Extract structured output
claude -p "Extract function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

​
Transmitir respuestas

Utilice --output-format stream-json con --verbose e --include-partial-messages para recibir tokens a medida que se generan. Cada línea es un objeto JSON que representa un evento: 
claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages
El siguiente ejemplo utiliza jq para filtrar deltas de texto y mostrar solo el texto transmitido. La bandera -r genera cadenas sin formato (sin comillas) y -j se une sin saltos de línea para que los tokens se transmitan continuamente: 
claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'
Para transmisión programática con devoluciones de llamada y objetos de mensaje, consulte Transmitir respuestas en tiempo real en la documentación del Agent SDK.

​
Aprobar herramientas automáticamente

Utilice --allowedTools para permitir que Claude use ciertas herramientas sin solicitar confirmación. Este ejemplo ejecuta un conjunto de pruebas y corrige fallos, permitiendo que Claude ejecute comandos Bash y lea/edite archivos sin pedir permiso: 
claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"

​
Crear una confirmación

Este ejemplo revisa los cambios preparados y crea una confirmación con un mensaje apropiado: 
claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"
La bandera --allowedTools utiliza sintaxis de regla de permiso. El * final habilita la coincidencia de prefijo, por lo que Bash(git diff *) permite cualquier comando que comience con git diff. El espacio antes de * es importante: sin él, Bash(git diff*) también coincidiría con git diff-index.
Las skills invocadas por el usuario como /commit y los comandos integrados solo están disponibles en modo interactivo. En modo -p, describa la tarea que desea realizar en su lugar.

​
Personalizar el indicador del sistema

Utilice --append-system-prompt para agregar instrucciones mientras mantiene el comportamiento predeterminado de Claude Code. Este ejemplo canaliza un diff de PR a Claude e le indica que revise las vulnerabilidades de seguridad: 
gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json
Consulte banderas de indicador del sistema para más opciones, incluyendo --system-prompt para reemplazar completamente el indicador predeterminado.

​
Continuar conversaciones

Utilice --continue para continuar la conversación más reciente, o --resume con un ID de sesión para continuar una conversación específica. Este ejemplo ejecuta una revisión y luego envía indicaciones de seguimiento: 
# First request
claude -p "Review this codebase for performance issues"

# Continue the most recent conversation
claude -p "Now focus on the database queries" --continue
claude -p "Generate a summary of all issues found" --continue
Si está ejecutando múltiples conversaciones, capture el ID de sesión para reanudar una específica: 
session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

​
Próximos pasos