​
概要

ヘッドレスモードでは、インタラクティブUIなしでコマンドラインスクリプトや自動化ツールからClaude Codeをプログラム的に実行できます。

​
基本的な使用方法

Claude Codeの主要なコマンドラインインターフェースはclaudeコマンドです。--print（または-p）フラグを使用して非インタラクティブモードで実行し、最終結果を出力します：

claude -p "変更をステージして、それらのコミットセットを書いて" \
  --allowedTools "Bash,Read" \
  --permission-mode acceptEdits \
  --cwd /path/to/project

​
設定オプション

SDKはClaude Codeで利用可能なすべてのCLIオプションを活用します。SDK使用における主要なオプションは以下の通りです：

フラグ説明例
--print, -p非インタラクティブモードで実行claude -p "クエリ"
--output-format出力形式を指定（text、json、stream-json）claude -p --output-format json
--resume, -rセッションIDで会話を再開claude --resume abc123
--continue, -c最新の会話を継続claude --continue
--verbose詳細ログを有効化claude --verbose
--append-system-promptシステムプロンプトに追加（--printでのみ）claude --append-system-prompt "カスタム指示"
--allowedTools許可されたツールのスペース区切りリスト、または

許可されたツールのカンマ区切りリストの文字列		claude --allowedTools mcp__slack mcp__filesystem

claude --allowedTools "Bash(npm install),mcp__filesystem"
--disallowedTools拒否されたツールのスペース区切りリスト、または

拒否されたツールのカンマ区切りリストの文字列		claude --disallowedTools mcp__splunk mcp__github

claude --disallowedTools "Bash(git commit),mcp__github"
--mcp-configJSONファイルからMCPサーバーを読み込みclaude --mcp-config servers.json
--permission-prompt-tool権限プロンプトを処理するMCPツール（--printでのみ）claude --permission-prompt-tool mcp__auth__prompt

CLIオプションと機能の完全なリストについては、CLIリファレンスドキュメントを参照してください。

​
マルチターン会話

マルチターン会話では、会話を再開したり、最新のセッションから継続したりできます：

# 最新の会話を継続
claude --continue "今度はパフォーマンス向上のためにリファクタリングして"

# セッションIDで特定の会話を再開
claude --resume 550e8400-e29b-41d4-a716-446655440000 "テストを更新して"

# 非インタラクティブモードで再開
claude --resume 550e8400-e29b-41d4-a716-446655440000 "すべてのリンティング問題を修正して" --no-interactive

​
出力形式

​
テキスト出力（デフォルト）

claude -p "ファイルsrc/components/Header.tsxを説明して"
# 出力: これは...を表示するReactコンポーネントです

​
JSON出力

メタデータを含む構造化データを返します：

claude -p "データレイヤーはどのように動作しますか？" --output-format json

レスポンス形式：

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "ここにレスポンステキスト...",
  "session_id": "abc123"
}

​
ストリーミングJSON出力

受信した各メッセージをストリーミングします：

claude -p "アプリケーションを構築して" --output-format stream-json

各会話は初期のinitシステムメッセージで始まり、ユーザーとアシスタントのメッセージのリストが続き、統計情報を含む最終的なresultシステムメッセージで終わります。各メッセージは個別のJSONオブジェクトとして出力されます。

​
入力形式

​
テキスト入力（デフォルト）

# 直接引数
claude -p "このコードを説明して"

# stdinから
echo "このコードを説明して" | claude -p

​
ストリーミングJSON入力

stdin経由で提供されるメッセージのストリームで、各メッセージはユーザーターンを表します。これにより、claudeバイナリを再起動することなく会話の複数ターンが可能になり、リクエストを処理している間にモデルにガイダンスを提供できます。

各メッセージは出力メッセージスキーマと同じ形式に従うJSON「ユーザーメッセージ」オブジェクトです。メッセージはjsonl形式を使用してフォーマットされ、入力の各行が完全なJSONオブジェクトになります。ストリーミングJSON入力には-pと--output-format stream-jsonが必要です。

echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"このコードを説明して"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose

​
エージェント統合例

​
SREインシデント対応ボット

#!/bin/bash

# 自動化されたインシデント対応エージェント
investigate_incident() {
    local incident_description="$1"
    local severity="${2:-medium}"

    claude -p "インシデント: $incident_description (重要度: $severity)" \
      --append-system-prompt "あなたはSREエキスパートです。問題を診断し、影響を評価し、即座のアクション項目を提供してください。" \
      --output-format json \
      --allowedTools "Bash,Read,WebSearch,mcp__datadog" \
      --mcp-config monitoring-tools.json
}

# 使用方法
investigate_incident "Payment APIが500エラーを返している" "high"

​
自動セキュリティレビュー

# プルリクエスト用のセキュリティ監査エージェント
audit_pr() {
    local pr_number="$1"

    gh pr diff "$pr_number" | claude -p \
      --append-system-prompt "あなたはセキュリティエンジニアです。このPRを脆弱性、安全でないパターン、コンプライアンス問題についてレビューしてください。" \
      --output-format json \
      --allowedTools "Read,Grep,WebSearch"
}

# 使用方法とファイルに保存
audit_pr 123 > security-report.json

​
マルチターン法務アシスタント

# セッション永続化を伴う法的文書レビュー
session_id=$(claude -p "法務レビューセッションを開始" --output-format json | jq -r '.session_id')

# 複数ステップで契約をレビュー
claude -p --resume "$session_id" "contract.pdfの責任条項をレビューして"
claude -p --resume "$session_id" "GDPR要件への準拠を確認して"
claude -p --resume "$session_id" "リスクの要約を生成して"

​
ベストプラクティス

  • レスポンスのプログラム的解析にはJSON出力形式を使用：

    # jqでJSONレスポンスを解析
result=$(claude -p "コードを生成" --output-format json)
code=$(echo "$result" | jq -r '.result')
cost=$(echo "$result" | jq -r '.cost_usd')

  • エラーを適切に処理 - 終了コードとstderrをチェック：

    if ! claude -p "$prompt" 2>error.log; then
    echo "エラーが発生しました:" >&2
    cat error.log >&2
    exit 1
fi

  • マルチターン会話でコンテキストを維持するためにセッション管理を使用

  • 長時間実行される操作にはタイムアウトを考慮：

    timeout 300 claude -p "$complex_prompt" || echo "5分後にタイムアウトしました"

  • 複数のリクエストを行う際は呼び出し間に遅延を追加してレート制限を尊重

​
関連リソース