uso de Headless CLI
Usa la CLI de Cursor en scripts y flujos de trabajo automatizados para analizar, generar y refactorizar código.
Cómo funciona
Usa el modo de impresión (-p, --print) para automatizar scripts no interactivos.
Modificación de archivos en scripts
Combina --print con --force (o --yolo) para modificar archivos desde scripts:
# Activa la modificación de archivos en modo de impresiónagent -p --force "Refactor this code to use modern ES6+ syntax"# Sin --force, los cambios solo se proponen; no se aplicanagent -p "Add JSDoc comments to this file" # No modificará los archivos# Procesamiento en lote con modificaciones reales de archivosfind src/ -name "*.js" | while read file; do agent -p --force "Add comprehensive JSDoc comments to $file"doneLa opción --force permite que el agente modifique archivos directamente sin
confirmación
Configuración
Consulta Instalación y Autenticación para conocer todos los detalles de configuración.
# Instalar la CLI de Cursor (macOS, Linux, WSL)curl https://cursor.com/install -fsS | bash# Instalar la CLI de Cursor (Windows PowerShell)irm 'https://cursor.com/install?win32=true' | iex# Configurar la clave de API para scriptsexport CURSOR_API_KEY=your_api_key_hereagent -p "Analyze this code"Scripts de ejemplo
Usa distintos formatos de salida según las necesidades de cada script. Consulta Formato de salida para más detalles.
Buscar en la base de código
De forma predeterminada, --print usa el formato text para ofrecer respuestas limpias que solo incluyen la respuesta final:
#!/bin/bash# Consulta sencilla sobre la base de código: usa el formato de texto de forma predeterminadaagent -p "What does this codebase do?"Revisión de código automatizada
Usa --output-format json para obtener un análisis estructurado:
#!/bin/bash# simple-code-review.sh - Script básico de revisión de códigoecho "Starting code review..."# Revisar los cambios recientesagent -p --force --output-format text \ "Review the recent code changes and provide feedback on: - Code quality and readability - Potential bugs or issues - Security considerations - Best practices compliance Provide specific suggestions for improvement and write to review.txt"if [ $? -eq 0 ]; then echo "✅ Code review completed successfully"else echo "❌ Code review failed" exit 1fiSeguimiento del progreso en tiempo real
Usa --output-format stream-json para seguir el progreso a nivel de mensaje, o añade --stream-partial-output para transmitir deltas de forma incremental:
#!/bin/bash# stream-progress.sh - Seguimiento del progreso en tiempo realecho "🚀 Starting stream processing..."# Seguimiento del progreso en tiempo realaccumulated_text=""tool_count=0start_time=$(date +%s)agent -p --force --output-format stream-json --stream-partial-output \ "Analyze this project structure and create a summary report in analysis.txt" | \ while IFS= read -r line; do type=$(echo "$line" | jq -r '.type // empty') subtype=$(echo "$line" | jq -r '.subtype // empty') case "$type" in "system") if [ "$subtype" = "init" ]; then model=$(echo "$line" | jq -r '.model // "unknown"') echo "🤖 Using model: $model" fi ;; "assistant") # Procesar solo los deltas del flujo (con timestamp_ms y sin model_call_id). # Omitir las emisiones almacenadas en búfer antes de las llamadas a herramientas y al final del turno. has_ts=$(echo "$line" | jq 'has("timestamp_ms")') has_mc=$(echo "$line" | jq 'has("model_call_id")') if [ "$has_ts" = "true" ] && [ "$has_mc" = "false" ]; then content=$(echo "$line" | jq -r '.message.content[0].text // empty') accumulated_text="$accumulated_text$content" printf "\r📝 Generating: %d chars" ${#accumulated_text} fi ;; "tool_call") if [ "$subtype" = "started" ]; then tool_count=$((tool_count + 1)) # Extraer información de la herramienta if echo "$line" | jq -e '.tool_call.writeToolCall' > /dev/null 2>&1; then path=$(echo "$line" | jq -r '.tool_call.writeToolCall.args.path // "unknown"') echo -e "\n🔧 Tool #$tool_count: Creating $path" elif echo "$line" | jq -e '.tool_call.readToolCall' > /dev/null 2>&1; then path=$(echo "$line" | jq -r '.tool_call.readToolCall.args.path // "unknown"') echo -e "\n📖 Tool #$tool_count: Reading $path" fi elif [ "$subtype" = "completed" ]; then # Extraer y mostrar los resultados de la herramienta if echo "$line" | jq -e '.tool_call.writeToolCall.result.success' > /dev/null 2>&1; then lines=$(echo "$line" | jq -r '.tool_call.writeToolCall.result.success.linesCreated // 0') size=$(echo "$line" | jq -r '.tool_call.writeToolCall.result.success.fileSize // 0') echo " ✅ Created $lines lines ($size bytes)" elif echo "$line" | jq -e '.tool_call.readToolCall.result.success' > /dev/null 2>&1; then lines=$(echo "$line" | jq -r '.tool_call.readToolCall.result.success.totalLines // 0') echo " ✅ Read $lines lines" fi fi ;; "result") duration=$(echo "$line" | jq -r '.duration_ms // 0') end_time=$(date +%s) total_time=$((end_time - start_time)) echo -e "\n\n🎯 Completed in ${duration}ms (${total_time}s total)" echo "📊 Final stats: $tool_count tools, ${#accumulated_text} chars generated" ;; esac doneTrabajar con imágenes
Para enviar imágenes, archivos multimedia u otros datos binarios al agente, incluye rutas de archivos en tus instrucciones. El agente puede leer cualquier archivo mediante llamadas a herramientas, incluidas imágenes, vídeos y otros formatos.
Incluir rutas de archivos en las instrucciones
Solo tienes que mencionar las rutas de los archivos en el texto de la instrucción. El agente leerá los archivos automáticamente cuando sea necesario:
# Analizar una imagenagent -p "Analyze this image and describe what you see: ./screenshot.png"# Procesar varios archivos multimediaagent -p "Compare these two images and identify differences: ./before.png ./after.png"# Combinar rutas de archivos con instrucciones de textoagent -p "Review the code in src/app.ts and the design mockup in designs/homepage.png. Suggest improvements to match the design."Cómo funciona
Cuando incluyes rutas de archivo en tu instrucción:
- El agente recibe tu instrucción con las referencias a las rutas de archivo
- El agente usa llamadas a herramientas para leer los archivos automáticamente
- Las imágenes se procesan de forma transparente
- Puedes hacer referencia a archivos mediante rutas relativas o absolutas
Ejemplo: Script de análisis de imágenes
#!/bin/bash# analyze-image.sh - Analiza imágenes con la CLI sin interfaz gráficaIMAGE_PATH="./screenshots/ui-mockup.png"agent -p --output-format json \ "Analyze this image and provide a detailed description: $IMAGE_PATH" | \ jq -r '.result'Ejemplo: procesamiento por lotes de archivos multimedia
#!/bin/bash# process-media.sh - Procesa varios archivos multimediafor image in images/*.png; do echo "Processing $image..." agent -p --output-format text \ "Describe what's in this image: $image" > "${image%.png}.description.txt"doneLas rutas de archivo pueden ser relativas al directorio de trabajo actual o absolutas. El agente leerá los archivos mediante llamadas a herramientas, así que asegúrate de que existan y sean accesibles desde el lugar donde ejecutes el comando.