Saltar al contenido principal

​
Descripción general

El modo sin interfaz permite ejecutar Claude Code programáticamente desde scripts de línea de comandos y herramientas de automatización sin ninguna interfaz de usuario interactiva.

​
Uso básico

La interfaz de línea de comandos principal para Claude Code es el comando claude. Utiliza la bandera --print (o -p) para ejecutar en modo no interactivo e imprimir el resultado final: 
claude -p "Stage my changes and write a set of commits for them" \
  --allowedTools "Bash,Read" \
  --permission-mode acceptEdits

​
Opciones de configuración

El modo sin interfaz aprovecha todas las opciones de CLI disponibles en Claude Code. Aquí están las principales para automatización y scripting:
BanderaDescripciónEjemplo
--print, -pEjecutar en modo no interactivoclaude -p "query"
--output-formatEspecificar formato de salida (text, json, stream-json)claude -p --output-format json
--resume, -rReanudar una conversación por ID de sesiónclaude --resume abc123
--continue, -cContinuar la conversación más recienteclaude --continue
--verboseHabilitar registro detalladoclaude --verbose
--append-system-promptAñadir al indicador del sistema (solo con --print)claude --append-system-prompt "Custom instruction"
--allowedToolsLista de herramientas permitidas separadas por espacios, o

cadena de lista separada por comas de herramientas permitidas		claude --allowedTools mcp__slack mcp__filesystem

claude --allowedTools "Bash(npm install),mcp__filesystem"
--disallowedToolsLista de herramientas denegadas separadas por espacios, o

cadena de lista separada por comas de herramientas denegadas		claude --disallowedTools mcp__splunk mcp__github

claude --disallowedTools "Bash(git commit),mcp__github"
--mcp-configCargar servidores MCP desde un archivo JSONclaude --mcp-config servers.json
--permission-prompt-toolHerramienta MCP para manejar indicadores de permisos (solo con --print)claude --permission-prompt-tool mcp__auth__prompt
Para una lista completa de opciones de CLI y características, consulta la documentación de referencia de CLI.

​
Conversaciones de múltiples turnos

Para conversaciones de múltiples turnos, puedes reanudar conversaciones o continuar desde la sesión más reciente: 
# Continuar la conversación más reciente
claude --continue "Now refactor this for better performance"

# Reanudar una conversación específica por ID de sesión
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Update the tests"

# Reanudar en modo no interactivo
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Fix all linting issues" --no-interactive

​
Formatos de salida

​
Salida de texto (predeterminada)

claude -p "Explain file src/components/Header.tsx"
# Output: This is a React component showing...

​
Salida JSON

Devuelve datos estructurados incluyendo metadatos: 
claude -p "How does the data layer work?" --output-format json
Formato de respuesta: 
{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "The response text here...",
  "session_id": "abc123"
}

​
Salida JSON de transmisión

Transmite cada mensaje a medida que se recibe: 
claude -p "Build an application" --output-format stream-json
Cada conversación comienza con un mensaje del sistema init inicial, seguido de una lista de mensajes de usuario y asistente, seguido de un mensaje del sistema result final con estadísticas. Cada mensaje se emite como un objeto JSON separado.

​
Formatos de entrada

​
Entrada de texto (predeterminada)

# Argumento directo
claude -p "Explain this code"

# Desde stdin
echo "Explain this code" | claude -p

​
Entrada JSON de transmisión

Un flujo de mensajes proporcionados a través de stdin donde cada mensaje representa un turno de usuario. Esto permite múltiples turnos de una conversación sin relanzar el binario claude y permite proporcionar orientación al modelo mientras procesa una solicitud. Cada mensaje es un objeto JSON ‘Mensaje de usuario’, siguiendo el mismo formato que el esquema de mensaje de salida. Los mensajes se formatean usando el formato jsonl donde cada línea de entrada es un objeto JSON completo. La entrada JSON de transmisión requiere -p y --output-format stream-json. 
echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"Explain this code"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose

​
Ejemplos de integración de agentes

​
Bot de respuesta a incidentes SRE

#!/bin/bash

# Agente de respuesta a incidentes automatizado
investigate_incident() {
    local incident_description="$1"
    local severity="${2:-medium}"

    claude -p "Incident: $incident_description (Severity: $severity)" \
      --append-system-prompt "You are an SRE expert. Diagnose the issue, assess impact, and provide immediate action items." \
      --output-format json \
      --allowedTools "Bash,Read,WebSearch,mcp__datadog" \
      --mcp-config monitoring-tools.json
}

# Uso
investigate_incident "Payment API returning 500 errors" "high"

​
Revisión de seguridad automatizada

# Agente de auditoría de seguridad para solicitudes de extracción
audit_pr() {
    local pr_number="$1"

    gh pr diff "$pr_number" | claude -p \
      --append-system-prompt "You are a security engineer. Review this PR for vulnerabilities, insecure patterns, and compliance issues." \
      --output-format json \
      --allowedTools "Read,Grep,WebSearch"
}

# Uso y guardar en archivo
audit_pr 123 > security-report.json

# Revisión de documentos legales con persistencia de sesión
session_id=$(claude -p "Start legal review session" --output-format json | jq -r '.session_id')

# Revisar contrato en múltiples pasos
claude -p --resume "$session_id" "Review contract.pdf for liability clauses"
claude -p --resume "$session_id" "Check compliance with GDPR requirements"
claude -p --resume "$session_id" "Generate executive summary of risks"

​
Mejores prácticas

  • Usar formato de salida JSON para análisis programático de respuestas: 
    # Analizar respuesta JSON con jq
result=$(claude -p "Generate code" --output-format json)
code=$(echo "$result" | jq -r '.result')
cost=$(echo "$result" | jq -r '.cost_usd')
  • Manejar errores correctamente - verificar códigos de salida y stderr: 
    if ! claude -p "$prompt" 2>error.log; then
    echo "Error occurred:" >&2
    cat error.log >&2
    exit 1
fi
  • Usar gestión de sesiones para mantener contexto en conversaciones de múltiples turnos
  • Considerar tiempos de espera para operaciones de larga duración: 
    timeout 300 claude -p "$complex_prompt" || echo "Timed out after 5 minutes"
  • Respetar límites de velocidad al realizar múltiples solicitudes añadiendo retrasos entre llamadas

​
Recursos relacionados