cURLを簡単に使いこなす：複雑なコマンドを秒速で作成
📷 Pexels / PexelscURLを簡単に使いこなす：複雑なコマンドを秒速で作成
cURLのフラグを毎回Googleするのはもう終わり。重要なパターンを学ぶか、ビジュアルコマンドビルダーを使って即座にリクエストを組み立てよう。
開発者として数ヶ月以上経験があれば、必ずcURLを使ったことがあるはずです。そして「curl post request json」を何度もGoogleしたことがあるでしょう。それは恥ずかしいことではありません。cURLには多くのフラグがあり、構文は密度が高いため、経験豊富な開発者でもすべてを記憶しているわけではないのです。
多くの開発者が気づいていないのは、日常的なAPIテストの90%をカバーするには、約12個のフラグを深く理解するだけでよいということです。残りは必要に応じて調べるか、ビルダーを使って構文を暗記せずにコマンドを組み立てればよいのです。
このガイドでは、実際に重要なcURLの部分に焦点を当て、今日すぐに実行できる実例を紹介します。
なぜcURLなのか？
公平な疑問です。Postman、Insomnia、VS CodeのREST Client拡張機能、ブラウザのDevToolsがあるのに、なぜcURLに手を伸ばすのでしょうか？
いくつかの理由があります：
常に利用可能です。 cURLはmacOSとほとんどのLinuxシステムにプリインストールされています。新しいサーバーでも、Dockerコンテナでも、同僚のマシンでも、cURLは使えます。Postmanはそうではありません。
スクリプト化できます。 cURLコマンドをbashスクリプト、CIパイプライン、cronジョブ、Makefileに組み込むことができます。インフラの一部になります。GUIツールではそれができません。
共有できます。 SlackメッセージやGitHub issueにcURLコマンドを貼り付ければ、誰でも即座に実行できます。「Postmanでこれを再現する方法は...」という説明が不要です。
共通言語です。 ほとんどのAPIドキュメントにはcURLの例が載っています。同僚が「これが失敗しているリクエストです」と言う場合、cURLコマンドを送ってくることが多いです。cURLを読む能力は価値があります。
ただし、cURLが常に適切なツールとは限りません。複雑な多段階ワークフロー、視覚的なレスポンス検査、フォームデータが多い場合は、Postmanの方が管理しやすいことが多いです。適切なツールを使いましょう。
実際に使うフラグ
-X — HTTPメソッド
デフォルトでは、cURLはGETリクエストを送信します。-Xでメソッドを変更します：
curl -X POST https://api.example.com/users
curl -X PUT https://api.example.com/users/123
curl -X DELETE https://api.example.com/users/123
curl -X PATCH https://api.example.com/users/123
よく使われる省略形：-dでボディを送る場合は-X POSTを省略できます。cURLがPOSTを推測するためです。ただし、他の人とコマンドを共有する際は明示的にする方が明確です。
-H — ヘッダーを追加する
ほぼすべてのAPIリクエストには最低1つのヘッダーが必要です。POST/PUTリクエストのContent-Type、認証済みエンドポイントのAuthorizationなどです：
# コンテンツタイプを設定
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json"
# 認証トークンを追加
curl https://api.example.com/profile \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..."
# 複数のヘッダー
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-token" \
-H "X-Request-ID: abc123"
同じコマンドで-Hを複数回使用できます。ヘッダーごとに1つのフラグです。
-d — リクエストボディ
リクエストボディにデータを送信します。POST、PUT、PATCHで使用します：
# JSONボディ
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-d '{"name": "Alice", "email": "alice@example.com"}'
# フォームデータ（URLエンコード）
curl -X POST https://api.example.com/login \
-d "username=alice&password=secret"
Content-Typeヘッダーが欠落している場合の注意：-dでJSONを送信しても-H "Content-Type: application/json"を忘れると、サーバーがリクエストを拒否するか、ボディを誤解析するかもしれません。これはcURLで最も一般的なミスの1つです。送信するものがわかっている場合は常にContent-Typeを設定してください。
-L — リダイレクトを追跡する
デフォルトでは、サーバーが301または302リダイレクトを返すと、cURLは停止してリダイレクト応答を表示します。通常はそれを追跡したいはずです：
curl -L https://example.com/old-url
これは、HTTPをHTTPSにリダイレクトするAPI、またはリソースが移動した場合に頻繁に発生します。-Lがないと、301 Moved Permanentlyが表示されるだけで、リクエストがデータを返さない理由がわからなくなります。
-i — レスポンスヘッダーを含む
デフォルトでは、cURLはレスポンスボディのみを表示します。-iはレスポンスヘッダーも含めます：
curl -i https://api.example.com/users/1
出力はこのようになります：
HTTP/2 200
content-type: application/json
x-rate-limit-remaining: 99
...
{"id": 1, "name": "Alice"}
ステータスコード、Content-Type、キャッシングヘッダー、レート制限情報を検査する必要がある場合に便利です。-iは、完全な接続デバッグ出力なしにヘッダーだけが必要な場合の、冗長モードの軽量な代替手段です。
-v — 冗長モード
これはデバッグ用フラグです。-vはすべてを表示します：cURLが送信した完全なリクエストヘッダー、TLSハンドシェイク、完全なレスポンスヘッダー：
curl -v https://api.example.com/users
出力例（省略版）：
* Trying 93.184.216.34:443...
* Connected to api.example.com (93.184.216.34) port 443
* SSL connection using TLSv1.3
> GET /users HTTP/2
> Host: api.example.com
> User-Agent: curl/8.1.2
> Accept: */*
>
< HTTP/2 200
< content-type: application/json
<
{"users": [...]}
>で始まる行はcURLが送信したものです。<で始まる行はサーバーが返したものです。*で始まる行はcURL自身のステータスメッセージです。認証問題、予期しないヘッダー、TLS問題のデバッグに非常に役立ちます。
-u — Basic認証
HTTP Basic Authを使用するAPIの場合、Authorizationヘッダーを手動で構築することもできますが、-uが自動的に処理します：
curl -u username:password https://api.example.com/protected
cURLは認証情報をBase64でエンコードし、適切なAuthorization: Basic ...ヘッダーを送信します。注意点：ターミナルにこれを貼り付けると、パスワードがシェル履歴に残ります。後で履歴を消去するか、環境変数を使用してください：
curl -u "alice:$API_PASSWORD" https://api.example.com/protected
-k — SSL検証をスキップ
このフラグには注意が必要です。-k（または--insecure）はcURLにSSL証明書エラーを無視するよう指示します：
curl -k https://localhost:8443/api/health
これは自己署名証明書を使用しているローカル開発には適切です。本番環境のリクエストには適切ではありません。実際の外部サービスに対して-kを使用している場合、正当な理由で存在するセキュリティをバイパスしています。開発環境のみで使用してください。
-oと-O — レスポンスをファイルに保存する
レスポンスをターミナルに出力する代わりに保存します：
# 特定のファイル名で保存
curl -o output.json https://api.example.com/data
# リモートのファイル名を使用して保存
curl -O https://example.com/files/report.pdf
-oはファイル名を選択でき、-OはURLの最後のパスセグメントを使用します。
-s — サイレントモード
プログレスバーとエラーメッセージを抑制します。レスポンスボディだけが必要なスクリプトで便利です：
curl -s https://api.example.com/status | jq .
jqへのパイプはJSONレスポンスを整形表示するための一般的なパターンです。-sを使うことで、jqがJSONのみを受け取るようにクリーンな出力が保たれます。
よくある間違い
POSTリクエストでContent-Typeを忘れる
これは開発者がよく踏むワナです。JSONを送信しているのにサーバーが400 Bad Requestや415 Unsupported Media Typeを返し、ヘッダーを1つ追加するだけで解決することに気づくまで20分もデバッグしてしまいます：
# ヘッダーが欠落 -- サーバーが拒否する可能性がある
curl -X POST https://api.example.com/users \
-d '{"name": "Alice"}'
# 正しい例
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-d '{"name": "Alice"}'
Windowsでのクォートの問題
WindowsのコマンドプロンプトでのcURLは、bashとは異なる方法でクォートを処理します。CMDではシングルクォートが使えません。ダブルクォートを使用し、内側のクォートをエスケープする必要があります：
# Windows CMD -- ダブルクォートを使い、内側のクォートをエスケープ
curl -X POST https://api.example.com/users ^
-H "Content-Type: application/json" ^
-d "{\"name\": \"Alice\"}"
PowerShellではシングルクォートが使えますが、エスケープルールはまだ異なります。これはWindowsの開発者がUnixシステム向けに書かれたドキュメントのcURLコマンドを使う際の最大の混乱源の1つです。WindowsでドキュメントのcURLコマンドが動作しない場合、クォートが原因であることがほとんどです。
@を使わずにファイルをボディとして送信する
ファイルの内容をリクエストボディとして送信したい場合は、@filenameを使用します：
# data.jsonの内容をボディとして送信
curl -X POST https://api.example.com/import \
-H "Content-Type: application/json" \
-d @data.json
@がないと、cURLは文字列をファイル名ではなくリテラルのボディ値として扱います。ファイルの内容ではなく、リテラルテキストdata.jsonを送信することになります。
GETリクエストで-dを使う
-dはボディを送信します。GETリクエストにはボディがありません（サーバーは通常それを無視します）。GETリクエストでクエリパラメータを送信したい場合は、URLに含めてください：
# GETリクエストでパラメータを使う正しい方法
curl "https://api.example.com/users?page=1&limit=20"
URLを囲むクォートに注意してください。クォートがないと、URLの&がシェルによってバックグラウンドオペレーターとして解釈される可能性があります。
まとめ：実際の例
ユーザーを作成する：
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{"name": "Bob", "email": "bob@example.com", "role": "editor"}'
ファイルをアップロードする：
curl -X POST https://api.example.com/upload \
-H "Authorization: Bearer $TOKEN" \
-F "file=@/path/to/document.pdf" \
-F "description=Q4 Report"
（注：マルチパートフォームデータには-dではなく-Fを使用）
カスタムペイロードでWebhookを確認する：
curl -X POST https://your-app.com/webhooks/github \
-H "Content-Type: application/json" \
-H "X-GitHub-Event: push" \
-H "X-Hub-Signature-256: sha256=abc123" \
-d @sample-push-event.json
進捗表示付きでダウンロードする：
curl -L -o large-file.zip https://example.com/downloads/archive.zip
暗記する代わりにビルダーを使う
基本的なGETリクエスト以外の場合、正しいフラグの組み合わせを記憶から組み立てるのはやがて面倒になります。ToolPal cURLコマンドビルダーを使えば、メソッド、URL、ヘッダー、ボディをフォームに入力するだけでcURLコマンドが生成されます。それをターミナルに直接コピーするか、必要に応じて調整できます。
これが特に便利な場面：
- 以前に書いたことのない認証ヘッダーを持つコマンドの構築
- マルチパートフォームアップロードの正しい構文を取得する
- bashに慣れているときのWindows互換コマンドの生成
- フラグ構文を知らないかもしれないチームメンバーとのコマンド共有
生成されたコマンドは標準的なcURLです。ベンダーロックインも独自仕様もありません。ビルダーを生産性のショートカットとして使い、生成されたコマンドを必要な場所で使用します。
cURL vs 他のツール
cURL vs Postman： PostmanはAPIの反復的な探索、リクエストのコレクション管理、チームコラボレーションで優れています。cURLはスクリプト化、素早い一回限りのリクエスト、共有可能性で優れています。競合するものではなく、ほとんどの開発者が両方を使っています。
cURL vs HTTPie： HTTPieはより親しみやすいインターフェイスときれいな出力を持つ新しいコマンドラインHTTPクライアントです。インストールできる状況なら、試してみる価値があります。cURLはインストール不要でどこでも使えるという優位性があります。
cURL vs ブラウザのDevTools： ブラウザが実際に送信しているもの（Cookie、セッショントークン、複雑なヘッダー）を調査するには、DevToolsが最適です。ネットワークタブでリクエストを右クリックしてcURLコマンドとしてコピーすることもできます。ブラウザリクエストをコマンドラインから再現する便利な方法です。
cURLは習得に時間をかけた分だけ報われます。すべてのフラグを暗記することはなくても、コアなフラグ（-X、-H、-d、-L、-v）の動作を理解することで、どこでも使え、スクリプト化しやすく、明確にコミュニケーションできるツールを手に入れられます。それはいくつの構文パターンを暗記するよりも価値があります。
迷ったら、ビルダーを使いましょう。何が問題かを理解する必要があるときは、-vを使いましょう。