ガイド

claude -p ガイド：Claude Code をスクリプトと CI から非対話で実行する

公開日：2026年10月30日 · 最終確認：2026年10月30日

このページでは、claude -p を使ってスクリプトから Claude Code を呼び出す使い方を説明します。基本的な使い方、入力のパイプ、3 つの出力形式、ツール権限、会話の再開、bare モードを、コピーして使えるコマンドで紹介します。フラグ、フィールド、動作は Anthropic の Run Claude Code programmatically のドキュメントに基づき、2026 年 10 月 30 日に確認しました。内容は一部を抜粋したもので、サブエージェントのメッセージやバックグラウンド作業など、ドキュメントにはさらに多くの情報があります。

-p の動作

任意の claude コマンドに -p（または --print）フラグを付けると、非対話で実行されます。次の例は、1 つのプロンプトを実行して応答を出力します。

claude -p "What does the auth module do?"

すべての CLI オプションが -p と組み合わせられるわけではありません。Claude Code は --bg を拒否し、タスクの説明付きの --cloud も拒否して、競合している内容を示すエラーを出します。

Claude Code は成功すると終了コード 0、実行が失敗すると 0 以外のコードで終了します。無効なフラグを渡した場合は、実行が始まる前にエラーを stderr に出力します。認証がないなど、実行の途中で失敗した場合は、その失敗を結果として stdout に出力します。

-p は他のフラグと組み合わせられます。次の例では 3 つのツールを事前承認し、Claude がプロンプトなしで作業できるようにしています。

claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

入力のパイプ

非対話モードは stdin を読み取るので、他のコマンドラインツールと同じように、データをパイプで渡し、応答をリダイレクトして取り出せます。次の例は、ビルドログをパイプで渡し、説明をファイルに書き出します。

cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

パイプで渡す stdin の上限は 10MB です。上限を超えると、Claude Code は明確なエラーと 0 以外のステータスで終了します。それより大きな入力は、内容をファイルに書き出し、プロンプトでそのファイルパスを参照してください。起動したプロセスが自分の側を切断したなどで Claude Code が stdin を読めない場合は、stderr に警告を出し、コマンドラインのプロンプトで続行します。

呼び出しをスクリプトに包んで、Claude をプロジェクト専用のリンターとして使うこともできます。この package.json のスクリプトは、main との diff を Claude にパイプで渡し、タイポを報告させます。diff をパイプで渡すので、Claude はそれを読むために Bash の権限を必要とせず、エスケープした二重引用符のおかげでスクリプトは Windows でも動きます。

{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
  }
}

npm run lint:claude で実行します。

出力形式

--output-format で、応答の返し方を指定します。

次の例は、プロジェクトの要約を JSON で返し、テキストの結果は result フィールドに入ります。

claude -p "Summarize this project" --output-format json

--output-format json を指定すると、レスポンスのペイロードには total_cost_usd とモデル別のコストの内訳も含まれるので、スクリプトで支出を追跡できます。--continue や --resume で以前の会話を続けた場合は、それ以前の実行の支出を含む、会話全体の合計が報告されます。どちらの数値もクライアント側の推定値で、実際の請求額とは異なることがあります。

jq などのツールで、特定のフィールドを取り出せます。

# Extract the text result
claude -p "Summarize this project" --output-format json | jq -r '.result'

# Extract structured output
claude -p "Extract function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

JSON Schema による構造化出力

特定のスキーマに沿った出力を得るには、--output-format json に --json-schema と JSON Schema の定義を組み合わせます。レスポンスにはリクエストに関するメタデータ（セッション ID、使用量など）が含まれ、構造化出力は structured_output フィールドに入ります。次の例は関数名を抽出し、文字列の配列として返します。

claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

値が有効な JSON Schema でない場合、claude は Error: --json-schema is not a valid JSON Schema に続けてバリデーターの診断を出力して終了します。Claude Code は "format": "email" のように format キーワードを使うスキーマを受け付けますが、format はアノテーションとして扱い、検証はしません。Claude がリクエストを断った場合などで、有効な構造化出力が得られないまま実行が終わると、レスポンスに structured_output フィールドが含まれないため、スクリプトで使う前にこのフィールドがあるか確認してください。

ストリーミング

生成されたトークンをそのまま受け取るには、--output-format stream-json に --verbose と --include-partial-messages を組み合わせます。各行はイベントを表す JSON オブジェクトです。

claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages

ストリームの最後の行は result メッセージで、最終的な応答テキスト、コスト、セッションのメタデータが入っています。次の jq フィルターはテキストの差分だけを残します。-r は引用符なしの生の文字列で出力し、-j は改行なしで連結するので、トークンが途切れずに流れます。

claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

system/init イベントは、モデル、ツール、MCP サーバー、読み込まれたプラグインなどのセッションメタデータを報告します。API リクエストが再試行可能なエラーで失敗すると、Claude Code は再試行の前に system/api_retry イベントを出力します。そのフィールドには attempt、max_retries、retry_delay_ms、error_status があります。stream-json では、拒否は permission_denied のシステムメッセージとして現れ、最終の結果メッセージの permission_denials に一覧されます。

非対話モードでのツール権限

プロンプトに答えてくれる人がキーボードの前にいないので、Claude に何を許すかを事前に決めておきます。--allowedTools を使うと、特定のツールをプロンプトなしで使わせられます。Read と Edit を列挙すると、ネットワークパスからの読み取りを除き、Claude は許可を求めずにファイルを読み書きできます。Bash を列挙するとシェルコマンドも同様になりますが、auto モードで始まった実行は例外で、Claude Code は単独の Bash エントリを広すぎる allow ルールとして外し、auto モードが各コマンドを個別に評価します。次の例は、この 3 つのツールを列挙して、テストスイートを実行し失敗を修正します。

claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"

列挙していないツールの呼び出しは、承認が不要なら実行されます。Manual モードの claude -p では、承認が必要な呼び出しは、PermissionRequest フックや --permission-prompt-tool など、何かが承認しない限り拒否されます。Claude Code v2.1.302 以降では、権限モードが何も設定されていない場合、claude -p は Manual モードで始まります。

ツールを特定のコマンドに限定するには、--allowedTools で権限ルールの構文を使います。末尾の * は前方一致を有効にするので、Bash(git diff *) は git diff で始まるすべてのコマンドを許可します。* の前のスペースは重要で、これがない Bash(git diff*) は git diff-index にも一致してしまいます。

claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

個別のツールを列挙する代わりに、セッション全体の基準を設定するには、--permission-mode で権限モードを渡します。

claude -p "Apply the lint fixes" --permission-mode acceptEdits

無人のジョブ向けには、スケジュール実行のジョブなど、権限プロンプトに答えられる人がいない場合に --permission-prompts none を渡します。プロンプトが出るはずの操作は、PermissionRequest フックが許可しない限り拒否され、Claude には誰もリクエストを承認できないことと再試行しないことが伝えられ、実行は続きます。このフラグには Claude Code v2.1.259 以降が必要で、それ以前のバージョンでは unknown-option エラーで拒否されます。

claude -p "Update the dependency pins and run the tests" --permission-mode auto --permission-prompts none

モード自体については、Claude Code の権限モードで説明しています。

会話を続ける

直近の会話を続けるには --continue、特定の会話を続けるにはセッション ID を付けた --resume を使います。次の例は、レビューを実行してから、続きのプロンプトを送ります。

# First request
claude -p "Review this codebase for performance issues"

# Continue the most recent conversation
claude -p "Now focus on the database queries" --continue
claude -p "Generate a summary of all issues found" --continue

複数の会話を並行して実行している場合は、セッション ID を取得して特定の会話を再開します。

session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

この 2 つのコマンドは別々のディレクトリから実行できます。Claude Code は、このマシン上のどのプロジェクトからでも、ID でセッションを見つけます。セッション ID の代わりに、セッションの .jsonl トランスクリプトファイルの絶対パスを --resume に渡すこともでき、その場合は、そのファイルに保存された会話を続けます。

スクリプトと CI 向けの bare モード

--bare を付けると、フック、スキル、カスタムコマンド、サブエージェント、インストール済みのプラグイン、MCP サーバー、自動メモリ、CLAUDE.md の自動検出をスキップして、起動時間を短縮します。付けない場合、claude -p は対話セッションと同じように、作業ディレクトリや ~/.claude に設定されたものを含めて、それらを検出して読み込みます。bare モードは、どのマシンでも同じ結果が必要な CI やスクリプトで役立ちます。同僚の ~/.claude にあるフックや、プロジェクトの .mcp.json にある MCP サーバーは、bare モードがそれらを一切読まないため実行されません。

bare モードはサブスクリプションのログインを使わないため、実行前に ANTHROPIC_API_KEY を設定してください。次の例は Read ツールを事前承認して、権限プロンプトなしで呼び出しが完了するようにしています。

claude --bare -p "Summarize README.md" --allowedTools "Read"

bare モードでは、Claude Code は OAuth 認証情報もシステムのキーチェーンも読みません。Anthropic API では、Claude Console で作成したキーを環境変数 ANTHROPIC_API_KEY に設定するか、--settings の JSON で apiKeyHelper を指定します。Amazon Bedrock、Google Cloud の Agent Platform、Microsoft Foundry は、従来どおり各プロバイダーの認証情報を読み込みます。

bare モードでは、Claude は Bash、ファイル読み取り、ファイル編集のツールを使えます。必要なコンテキストは、フラグで渡します。

--bare がない場合、-p セッションは、一度も信頼したことのないフォルダであっても、プロジェクトの .claude/settings.json にあるフックを実行し、.mcp.json にあるサーバーに接続します。-p セッションでは、ワークスペースの信頼ダイアログもサーバーごとの承認プロンプトも表示されません。自分が書いていないリポジトリで claude -p を実行する前に、この点に注意してください。ドキュメントでは、--bare がスクリプトや SDK からの呼び出しに推奨されるモードであり、将来のリリースで -p のデフォルトになる予定だとしています。

その他のレシピ

Claude Code のデフォルトの動作を保ったまま指示を追加するには、--append-system-prompt を使います。次の例は、PR の diff を Claude にパイプで渡し、セキュリティレビューを依頼します。review.sh などのシェルスクリプトとして保存して bash review.sh 123 と実行すると、シェルが "$1" を 123 に置き換えます。

gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json

--system-prompt はデフォルトのプロンプトを完全に置き換えます。置き換えた場合、その実行は git status のスナップショットなしで始まります。

コマンドのサポートは -p モードでは異なります。ユーザーが呼び出すスキルとカスタムコマンドは動作します。プロンプトの文字列に /skill-name を含めると、Claude Code が実行前に展開します。/login のように、ターミナルのインターフェイスでしか動かない組み込みコマンドは使えません。設定を変えるには、/config thinking=false のように /config に key=value を渡します。対話用のコマンドは Claude Code のコマンド一覧を、GitHub のワークフローで claude -p を実行する方法は Claude Code と GitHub Actions を参照してください。

トラブルシューティング

FAQ

参考資料

• Claude Code: Run Claude Code programmatically（-p、出力形式、権限、--bare、セッションの再開）
• Claude Code: CLI reference（すべての CLI フラグとオプション）
• Claude Code: Permission modes（--permission-mode の各値の動作）