Claude Codeは、画面を開かずに1回だけ実行する使い方ができます。
スクリプトや定期処理に組み込むときは、claude -p を使います。
公式ドキュメントから、基本の書き方、出力形式、権限の指定、無人実行の注意点を整理しました。
- -p（–print）を付けると、対話せずに結果だけを出して終わる
- 出力形式は text（既定）、json、stream-json から選ぶ
- 許可する操作は –allowedTools で決める
- -p では、権限の確認が必要な操作は既定では止まる
claude -pの実機での再現は含まず、公式ページの記載（2026年9月30日に確認）に基づきます。
仕様や数値は変わることがあるので、最新は公式ページで確かめてください。
基本の書き方
公式が示す基本の例は、次の形です。
claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"-p の後ろに指示を書くと、対話画面を開かずに実行して結果を出力します。
公式では、claude -p はAgent SDKのCLI版という位置づけで、以前はヘッドレスモードと呼ばれていました。
終了コードは、成功なら0、失敗なら0以外です。
認証切れのように実行の中で起きた失敗は、結果として標準出力に出ます。
出力形式を選ぶ
| –output-format | 出力 |
|---|---|
| text | 既定。文章だけを出す |
| json | 結果、セッションID、メタデータを1つのJSONで出す |
| stream-json | 改行区切りのJSONを順に出す |
jsonの出力には、費用の見積もりを示す total_cost_usd が入ります。
これはクライアント側の推定値で、実際の請求とずれることがある、と公式は書いています。
–json-schema をjsonと組み合わせると、決まった形の結果が structured_output に入ります。
スキーマが不正だとエラーで終了します。
逐次で受け取りたいときは、次の組み合わせを使います。
claude -p "..." --output-format stream-json --verbose --include-partial-messages最終行が、結果を表すメッセージになります。
許可する操作の指定
–allowedTools には、権限ルールと同じ書き方を使います。
- Bash(git diff *) のように、コマンドを前方一致で許可できる
- 末尾の「スペース＋*」が前方一致になる
- スペースなしの * だと、git diff-index のようなコマンドにも一致する
-p の既定の権限モードは、確認を求める Manual です。
–permission-mode で、auto、dontAsk、acceptEdits を指定できます。
dontAsk は、確認が出る操作をすべて拒否するモードで、CI向けと公式は説明しています。
–permission-prompts none は無人実行用で、v2.1.259以降の記載です。
会話を続ける
- –continue：直近の会話を続ける
- –resume <session_id>：指定したセッションを続ける
- session_idは、json出力の .session_id から取れる
標準入力から渡せる量は、10MBまでです。
–bare で起動を軽くする
–bare を付けると、hooks、スキル、プラグイン、MCP、自動メモリ、CLAUDE.mdの自動読み込みを省きます。
起動が短くなり、どの環境でも同じ結果になりやすくなります。
公式は、スクリプトやSDKから呼ぶときに推奨し、将来は -p の既定になると書いています。
–bare はOAuthやキーチェーンを読まないので、ANTHROPIC_API_KEY か apiKeyHelper が必要です。
BedrockやVertexなどを使う場合は、それぞれの認証を使います。
-p で使えないもの
/login のような対話専用の組み込みコマンドは、-p では使えません。
スキルやカスタムコマンドは使えます。
公式に書かれていなかったこと
- CLIで –max-turns を単体で使うときの仕様（GitHub Actionsの例には出てくる）
- サブスクリプションでログインしたまま -p を使ったときの課金の扱い
課金の扱いは、認証の種類で変わります。
違いは別の記事で整理しているので、あわせてご覧ください。
