ヘッドレス CLI の使用
スクリプトや自動化ワークフローで Cursor CLI を使用し、コードの分析、生成、リファクタリングを行えます。
仕組み
非対話型のスクリプトや自動化には、print モード (-p, --print) を使用します。
スクリプトでのファイル変更
スクリプトでファイルを変更するには、--print と --force (または --yolo) を組み合わせます。
# print モードでファイル変更を有効にするagent -p --force "Refactor this code to use modern ES6+ syntax"# --force がない場合、変更は提案されるだけで適用されないagent -p "Add JSDoc comments to this file" # ファイルは変更されない# 実際にファイルを変更する一括処理find src/ -name "*.js" | while read file; do agent -p --force "Add comprehensive JSDoc comments to $file"done--force フラグを使用すると、確認なしでエージェントがファイルを直接変更できるようになります
セットアップ
セットアップの詳細については、インストールと認証を参照してください。
# Cursor CLI をインストール(macOS、Linux、WSL)curl https://cursor.com/install -fsS | bash# Cursor CLI をインストール(Windows PowerShell)irm 'https://cursor.com/install?win32=true' | iex# スクリプト用に API key を設定export CURSOR_API_KEY=your_api_key_hereagent -p "Analyze this code"スクリプト例
スクリプトの用途に応じて、異なる出力形式を使用できます。詳しくは出力形式を参照してください。
コードベースを検索する
デフォルトでは、--print は最終回答のみを含む簡潔なレスポンスに text 形式を使用します。
#!/bin/bash# コードベースに関する簡単な質問 - デフォルトでは text 形式を使用agent -p "What does this codebase do?"自動コードレビュー
構造化された分析結果を得るには、--output-format json を使用します。
#!/bin/bash# simple-code-review.sh - 基本的なコードレビュー用スクリプトecho "Starting code review..."# 最近の変更を確認するagent -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 1fiリアルタイムで進行状況を追跡
メッセージ単位で進行状況を追跡するには --output-format stream-json を使用します。差分を段階的にストリーミングするには、--stream-partial-output を追加します。
#!/bin/bash# stream-progress.sh - 進行状況をリアルタイムに追跡echo "🚀 Starting stream processing..."# 進行状況をリアルタイムに追跡accumulated_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") # ストリーミングの delta のみを処理する(timestamp_ms あり、model_call_id なし)。 # ツール呼び出しの前とターン終了時に発生するバッファ済みの flush はスキップする。 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)) # ツール情報を抽出 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 # ツールの実行結果を抽出して表示 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 done画像を扱う
画像、メディアファイル、その他のバイナリデータをエージェントに送信するには、プロンプトにファイルパスを含めます。エージェントはツール呼び出しを通じて、画像、動画、その他の形式を含むあらゆるファイルを読み取れます。
プロンプトにファイルパスを含める
プロンプト内でファイルパスを指定するだけで、必要に応じてエージェントが自動的にファイルを読み取ります。
# 画像を解析するagent -p "Analyze this image and describe what you see: ./screenshot.png"# 複数のメディアファイルを処理するagent -p "Compare these two images and identify differences: ./before.png ./after.png"# ファイルパスとテキストの指示を組み合わせるagent -p "Review the code in src/app.ts and the design mockup in designs/homepage.png. Suggest improvements to match the design."仕組み
プロンプトにファイルパスを含めると:
- エージェントは、ファイルパスの参照を含むプロンプトを受け取ります
- エージェントはツール呼び出しでファイルを自動的に読み取ります
- 画像は自動的に処理されます
- 相対パスまたは絶対パスでファイルを参照できます
例: 画像解析スクリプト
#!/bin/bash# analyze-image.sh - ヘッドレス CLI で画像を分析するIMAGE_PATH="./screenshots/ui-mockup.png"agent -p --output-format json \ "Analyze this image and provide a detailed description: $IMAGE_PATH" | \ jq -r '.result'例: メディアのバッチ処理
#!/bin/bash# process-media.sh - 複数のメディアファイルを処理するfor image in images/*.png; do echo "Processing $image..." agent -p --output-format text \ "Describe what's in this image: $image" > "${image%.png}.description.txt"doneファイルパスには、現在の作業ディレクトリからの相対パスまたは絶対パスを指定できます。 エージェントはツール呼び出しを通じてファイルを読み取るため、ファイルが存在し、 コマンドを実行する場所からアクセスできることを確認してください。