Claude Codeのclaude -pの使い方｜ヘッドレス実行の出力形式と権限の指定

Claude Codeは、画面を開かずに1回だけ実行する使い方ができます。

スクリプトや定期処理に組み込むときは、claude -p を使います。

公式ドキュメントから、基本の書き方、出力形式、権限の指定、無人実行の注意点を整理しました。

• -p（--print）を付けると、対話せずに結果だけを出して終わる
• 出力形式は text（既定）、json、stream-json から選ぶ
• 確認なしで許可する操作を --allowedTools で指定する。未指定の操作がすべて禁止になるわけではない
• Manualモードで確認が必要な操作は、承認する仕組みがなければ拒否される

claude -pの実機での再現は含まず、公式ページの記載（2026年10月23日に再照合）に基づきます。

2026年10月17日に、Windows 11 の Claude Code 2.1.289 で claude --help を表示し、-p まわりのオプションの説明を確かめて画像を追加しました。

claude -p そのものは実行していないので、json などの出力の中身は確かめていません。

仕様や数値は変わることがあるので、最新は公式ページで確かめてください。

基本の書き方

公式が示す基本の例は、次の形です。

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

-p の後ろに指示を書くと、対話画面を開かずに実行して結果を出力します。

Claude Code 2.1.289 の claude --help から、-p と入出力の形式の行を抜き出すと、次のように表示されます。

-p（--print）の説明は「Print response and exit」（応答を出力して終了する）です。

続けて、-p で実行するとフォルダーを信頼するかの確認（workspace trust dialog）が出ないので、信頼できるフォルダーだけで使うように、と書かれています。

検証に失敗した設定ファイルは、このときエラーを出さずに無視される、とも書かれています。

--output-format と --input-format は、どちらも -p を付けたときだけ効きます。

出力形式の選択肢は text（既定）・json・stream-json の3つで、次の節の表と同じです。

入力形式は text（既定）と stream-json の2つです。

公式では、claude -p はAgent SDKのCLI版という位置づけで、以前はヘッドレスモードと呼ばれていました。

終了コードは、成功なら0、失敗なら0以外です。

認証切れのように実行の中で起きた失敗は、結果として標準出力に出ます。

自動処理では終了コードだけでなく、結果本文と期待した成果物も確認します。

権限拒否があっても処理を続ける場合があるため、stream-jsonではpermission_deniedメッセージと最終結果のpermission_denialsを確認し、実行できなかった操作を取りこぼさないようにします。

出力形式を選ぶ

jsonの出力には、費用の見積もりを示す total_cost_usd が入ります。

これは請求額そのものではなくクライアント側の推定です。会話を再開した場合、以前の実行分を含む会話全体の合計なので、今回だけの費用として扱わないでください。

--json-schema をjsonと組み合わせると、有効な構造化結果が得られた場合、structured_outputに入ります。

スキーマが不正だとエラーで終了します。実行結果にstructured_outputが存在するか確認してから使ってください。format指定は注釈扱いで、形式の検証を保証しません。

逐次で受け取りたいときは、次の組み合わせを使います。

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

最終行が、結果を表すメッセージになります。

許可する操作の指定

--allowedTools には、権限ルールと同じ書き方を使います。

• Bash(git diff *) のように、コマンドを前方一致で許可できる
• 末尾の「スペース＋*」が前方一致になる
• スペースなしの * だと、git diff-index のようなコマンドにも一致する

v2.1.302以降、別の設定がなければ-pはManualモードで始まります。承認が必要な操作は、フックなどが許可しなければ拒否されます。

--permission-mode で、auto、dontAsk、acceptEdits を指定できます。

dontAskは未解決の権限確認を拒否するモードです。読取りなど元から承認不要の操作や許可ルールに合う操作は実行され、一部は権限拡張にも影響されます。

--permission-prompts noneは無人実行向けです。承認ホストの返答を待たず、ルール・モード・PermissionRequestフックでも解決しない確認要求を拒否して処理を続けます。

同じ 2.1.289 の claude --help で、権限まわりの3つのオプションを表示しました。

--allowedTools は --allowed-tools とも書け、ツール名をカンマかスペースで区切って並べます（ヘルプの例は "Bash(git *) Edit"）。

--permission-mode の選択肢は、acceptEdits・auto・bypassPermissions・manual・dontAsk・plan の6つです。

ヘルプには、-p のときにどのモードが既定になるかは書かれていません。

--permission-prompts は host（既定）と none の2つで、none にすると確認が出る操作は自動で拒否され、それ以外は権限モードで決まる、と書かれています。

関連記事：Claude Codeの権限モードと許可ルール

--permission-promptsはv2.1.259以降の機能で、それ以前の版ではunknown-optionエラーになります。

会話を続ける

• --continue：直近の会話を続ける
• --resume <session_id>：指定したセッションを続ける
• session_idは、json出力の .session_id から取れる

標準入力から渡せる量は、10MBまでです。

10MBを超える内容はファイルに保存し、そのパスをプロンプトで指定して読み取らせます。

2.1.289 の claude --help では、会話を続ける2つのオプションは次のように表示されます。

--continue（-c）は、今いるフォルダーで直近の会話を続けます。

--resume（-r）は、セッションIDを付けるとその会話を続け、付けないと会話を選ぶ画面を開く、と書かれています。

-p と組み合わせて ID を付けなかったときの動きは確かめていません。

画像の最後の行は、ヘルプの中に max-turns という文字が何回出るかを数えたもので、結果は0でした。

--bare で起動を軽くする

--bare を付けると、hooks、スキル、プラグイン、MCP、自動メモリ、CLAUDE.mdの自動読み込みを省きます。

ホスト固有の自動読込みを減らせますが、モデルの出力が毎回同じになる保証はありません。バックグラウンド処理も無効になるため、通常モードとの違いを確認してください。

公式は、スクリプトやSDKから呼ぶときに推奨し、将来は -p の既定になると書いています。

--bareではサブスクリプションのOAuthやキーチェーンを使いません。Anthropic APIなら環境のANTHROPIC_API_KEYか、--settingsで渡すapiKeyHelperを用意します。

BedrockやVertexなどを使う場合は、それぞれの認証を使います。

2.1.289 の claude --help の --bare の説明には、スキルは /スキル名 で呼べば使える、とも書かれています（画像には入れていません）。

--bareでも、明示的な--mcp-configで渡したMCPサーバーは接続対象になります。

また、--add-dirで指定したディレクトリの.claude/skills/は例外的に読み込まれるため、bareを外部ツールやスキルの全面禁止として扱わないでください。

-p で使えないもの

/login のような対話専用の組み込みコマンドは、-p では使えません。

スキルやカスタムコマンドは使えます。

実行上限と認証を確認する

• 現行CLIリファレンスの--max-turnsはprintモードのエージェントターン数上限。既定は無制限で、上限到達時はエラー終了する
• 認証方法で利用枠・課金先が変わる。通常の-pでは保存済みサブスクリプション認証を使えるが、APIキーなど優先される認証があればそちらを使う

過去に確認した2.1.289のヘルプには--max-turnsの行がありませんでしたが、現行の公式リファレンスには仕様と例があります。画像内の検索件数だけで機能の有無は判断できません。

課金の扱いは、認証の種類で変わります。

違いは別の記事で整理しているので、あわせてご覧ください。

関連記事：Claude Codeのログイン方法の違い

よくある質問：Claude Codeのclaude -p

claude -p とは、何ですか？

-p（--print）を付けると、対話画面を開かずに1回だけ実行し、結果だけを出して終わります。

スクリプトや定期処理に組み込むときに使います。

公式では、Agent SDKのCLI版という位置づけで、以前はヘッドレスモードと呼ばれていました。

出力形式は、どれを選べばよいですか？

text（既定、文章だけ）、json（結果、セッションID、メタデータを1つのJSONで出す）、stream-json（改行区切りのJSONを順に出す）から選びます。

--json-schema をjsonと組み合わせると、有効な構造化結果が得られた場合、structured_outputに入ります（スキーマが不正だとエラーで終了します）。

費用は、どう確認できますか？

jsonの出力には、費用の見積もりを示す total_cost_usd が入ります。

請求額とは異なる推定値です。会話を再開すると過去の実行分も合計に含まれます。

許可する操作は、どう指定しますか？

--allowedTools に、権限ルールと同じ書き方で指定します。

Bash(git diff *) のように、コマンドを前方一致で許可でき、末尾の「スペース＋*」が前方一致になります。

スペースなしの * だと、git diff-index のようなコマンドにも一致します。

無人で動かすとき、権限の確認で止まりませんか？

承認先の有無で異なります。

Manualモードで承認先がない場合、確認が必要な操作は拒否されます。SDKの承認コールバックなどを設定すると、その応答を待つ場合があります。

--permission-mode で、auto、dontAsk、acceptEdits を指定できます。

dontAskは未解決の権限確認を拒否するモードです。読取りなど元から承認不要の操作や許可ルールに合う操作は実行され、一部は権限拡張にも影響されます。

--permission-prompts noneは無人実行向けです。承認ホストの返答を待たず、ルール・モード・PermissionRequestフックでも解決しない確認要求を拒否して処理を続けます。

前の会話の続きから実行できますか？

--continue で直近の会話を、--resume <session_id> で指定したセッションを続けられます。

session_id は、json出力の .session_id から取れます。

標準入力から渡せる量は、10MBまでです。

--bare は、何のために付けますか？

hooks、スキル、プラグイン、MCP、自動メモリ、CLAUDE.mdの自動読み込みを省いて、環境ごとの自動読込みの差を減らします。出力の一致を保証する機能ではありません。

公式は、スクリプトやSDKから呼ぶときに推奨し、将来は -p の既定になると書いています。

--bareではサブスクリプションのOAuthやキーチェーンを使いません。Anthropic APIなら環境のANTHROPIC_API_KEYか、--settingsで渡すapiKeyHelperを用意します。

BedrockやVertexなどを使う場合は、それぞれの認証を使います。

-pの制限と実行上限は？

/login のような対話専用の組み込みコマンドは -p では使えません（スキルやカスタムコマンドは使えます）。

現行の公式資料には--max-turnsの仕様が掲載されています。printモードでターン数を制限し、到達時はエラー終了します。認証の優先順位も公式資料で確認できます。

課金の扱いは認証の種類で変わるため、別の記事（Claude Codeのログイン方法の違い）もご覧ください。

2026年10月23日に公式の非対話実行ガイドなどと照合しました。実際の-p実行、出力解析、権限拒否、認証別課金、画面表示は今回検証していません。通常モードではバックグラウンド作業を待って終了が延びる場合もあります。