Usando a Headless CLI
Use a CLI do Cursor em scripts e fluxos de trabalho de automação para analisar, gerar e refatorar código.
Como funciona
Use o modo de impressão (-p, --print) para automação e scripts não interativos.
Modificação de arquivos em scripts
Combine --print com --force (ou --yolo) para modificar arquivos em scripts:
# Habilite modificações de arquivos no modo de impressãoagent -p --force "Refactor this code to use modern ES6+ syntax"# Sem --force, as alterações são apenas propostas, não aplicadasagent -p "Add JSDoc comments to this file" # Won't modify files# Processamento em lote com alterações efetivas nos arquivosfind src/ -name "*.js" | while read file; do agent -p --force "Add comprehensive JSDoc comments to $file"doneA flag --force permite que o agente faça alterações diretamente nos arquivos sem
confirmação
Configuração
Consulte Instalação e Autenticação para obter todos os detalhes de configuração.
# Instalar a CLI do Cursor (macOS, Linux, WSL)curl https://cursor.com/install -fsS | bash# Instalar a CLI do Cursor (Windows PowerShell)irm 'https://cursor.com/install?win32=true' | iex# Definir a chave de API para scriptsexport CURSOR_API_KEY=your_api_key_hereagent -p "Analyze this code"Scripts de exemplo
Use formatos de saída diferentes conforme a necessidade de cada script. Consulte Formato de saída para mais detalhes.
Pesquisando na base de código
Por padrão, --print usa o formato text para gerar respostas limpas, contendo apenas a resposta final:
#!/bin/bash# Pergunta simples sobre a base de código — usa o formato de texto por padrãoagent -p "What does this codebase do?"Revisão automatizada de código
Use --output-format json para obter uma análise estruturada:
#!/bin/bash# simple-code-review.sh - Script básico de revisão de códigoecho "Starting code review..."# Revisar alterações recentesagent -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 1fiAcompanhamento do progresso em tempo real
Use --output-format stream-json para acompanhar o progresso por mensagem ou adicione --stream-partial-output para transmitir deltas incrementalmente:
#!/bin/bash# stream-progress.sh - Acompanhar o progresso em tempo realecho "🚀 Starting stream processing..."# Acompanhar o progresso em tempo 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") # Processar apenas deltas de streaming (timestamp_ms presente e sem model_call_id). # Ignorar os flushes armazenados em buffer antes das chamadas de ferramenta e ao fim da interação. 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)) # Extrair informações sobre a ferramenta 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 # Extrair e exibir os resultados da ferramenta 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 doneTrabalhando com imagens
Para enviar imagens, arquivos de mídia ou outros dados binários ao agente, inclua caminhos de arquivos nos prompts. O agente pode ler qualquer arquivo por meio de chamadas de ferramenta, incluindo imagens, vídeos e outros formatos.
Inclusão de caminhos de arquivo em prompts
Basta informar os caminhos dos arquivos no texto do prompt. O agente lerá os arquivos automaticamente quando necessário:
# Analise uma imagemagent -p "Analyze this image and describe what you see: ./screenshot.png"# Processe vários arquivos de mídiaagent -p "Compare these two images and identify differences: ./before.png ./after.png"# Combine caminhos de arquivos com instruções de textoagent -p "Review the code in src/app.ts and the design mockup in designs/homepage.png. Suggest improvements to match the design."Como funciona
Quando você inclui caminhos de arquivos no prompt:
- O agente recebe seu prompt com referências aos caminhos dos arquivos
- O agente usa chamadas de ferramenta para ler os arquivos automaticamente
- As imagens são processadas de forma transparente
- Você pode referenciar arquivos usando caminhos relativos ou absolutos
Exemplo: script de análise de imagens
#!/bin/bash# analyze-image.sh - Analisa imagens usando a Headless CLIIMAGE_PATH="./screenshots/ui-mockup.png"agent -p --output-format json \ "Analyze this image and provide a detailed description: $IMAGE_PATH" | \ jq -r '.result'Exemplo: processamento de mídia em lote
#!/bin/bash# process-media.sh - Processar vários arquivos de mídiafor image in images/*.png; do echo "Processing $image..." agent -p --output-format text \ "Describe what's in this image: $image" > "${image%.png}.description.txt"doneOs caminhos de arquivo podem ser relativos ao diretório de trabalho atual ou absolutos. O agente lerá os arquivos por meio de chamadas de ferramenta. Portanto, verifique se eles existem e estão acessíveis a partir do local em que você executa o comando.