コピペしたcurlが読めれば、APIの調査は速くなる

ドキュメントやブラウザの開発者ツールからコピーしたcurlコマンドは、たいていこんな見た目です。

curl -X POST 'https://api.example.com/v1/items?limit=10' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Alice","tags":["a","b"]}'

読めてしまえば単純ですが、オプションの組み合わせで挙動が変わる箇所がいくつかあり、そこを知らないと「同じコマンドのはずなのに動かない」に出会います。この記事は主要オプションの早見表と、実際にハマる点をまとめたリファレンスです。

オプション一覧(用途別)

よく使うものを用途別に並べました。すべてを確認したいときは curl --help all(一覧)、curl --help category(カテゴリ一覧)、man curl(詳細)が使えます。

リクエストの組み立て

オプション 意味
-X, --request HTTPメソッドを指定(GET / POST / PUT / DELETE など)
-H, --header リクエストヘッダーを追加。複数回書ける
-A, --user-agent User-Agent を指定する
-e, --referer Referer ヘッダーを指定する
-b, --cookie Cookieを送る
-c, --cookie-jar 受け取ったCookieをファイルに保存
-u, --user Basic認証(user:password)
-G, --get -d のデータをボディではなくURLのクエリ文字列として送る

データの送信

オプション 意味
-d, --data リクエストボディを送る。付けると自動でPOSTになる
--data-raw -d と同じだが、先頭の @ をファイル指定として解釈しない
--data-binary 改行を削らずそのまま送る(バイナリ・ファイル向け)
--data-urlencode 値をパーセントエンコードして送る
-F, --form multipart/form-data で送る(ファイルアップロード)
-T, --upload-file ファイルをアップロードする(HTTPではPUT)
--json JSONを送る(Content-Type と Accept も付く。curl 7.82以降)

レスポンスの扱い

オプション 意味
-o, --output レスポンスをファイルに保存
-O, --remote-name URL末尾のファイル名で保存
-i, --include レスポンスヘッダーも出力に含める
-I, --head HEADリクエストを送り、ヘッダーだけ取得
-D, --dump-header レスポンスヘッダーをファイルに保存
-w, --write-out 完了後に %{http_code} などの情報を出力
-r, --range 範囲を指定して取得(0-99 など)
-C - 途中までダウンロードしたファイルの続きから再開
--compressed gzip等での圧縮転送を要求する

表示とエラー

オプション 意味
-s, --silent 進捗表示を出さない
-S, --show-error -s と併用してエラーだけは表示する
-v, --verbose 送受信の詳細(リクエストヘッダー含む)を表示
-f, --fail HTTPが400以上のとき、本文を出さずに失敗(終了コード22)にする
-#, --progress-bar 進捗を棒グラフで表示する

接続・タイムアウト・リダイレクト

オプション 意味
-L, --location リダイレクト(3xx)を追跡する
--max-redirs 追跡するリダイレクトの最大回数
--connect-timeout 接続を待つ最大秒数
-m, --max-time 全体の最大秒数。超えると中断する
--retry 一時的なエラー時に再試行する回数
-x, --proxy プロキシ経由で接続する
--resolve ホスト名を指定のIPに解決する(host:port:address)。DNSを変えずに切り替え先を試せる
-4, -6 IPv4 / IPv6 だけを使う
-g, --globoff URL中の [] {} を展開しない

TLS(HTTPS)

オプション 意味
-k, --insecure サーバー証明書の検証をしない
--cacert 検証に使うCA証明書ファイルを指定する
-E, --cert / --key クライアント証明書と秘密鍵を指定する

-X POST は実は省略できることが多い

-d を付けると、curlは自動的にPOSTになります。つまり次の2つは同じです。

curl -X POST https://api.example.com/items -d '{"a":1}'
curl https://api.example.com/items -d '{"a":1}'

問題は逆のケースです。-X GET と -d を同時に指定すると、GETなのにボディ付きのリクエストになります。プロキシやサーバーによっては無視されたり弾かれたりするため、意図せず「ローカルでは動くのに本番で失敗する」原因になります。

なお -d を複数書くと & で連結されます。これはフォーム送信では便利ですが、JSONを送るつもりで2回書くと壊れた本文になります。

# 期待と違う: {"a":1}&{"b":2} が送られる
curl -d '{"a":1}' -d '{"b":2}' https://api.example.com/items

-d の @ はファイル読み込みになる

-d に渡した値が @ で始まると、curlはそのファイルを読んで中身を送ります。

curl -d @payload.json https://api.example.com/items   # ファイルの中身を送る

便利な機能ですが、メールアドレスやユーザー名を素で渡すと事故ります。

# 意図: 文字列 "@alice" を送りたい
# 実際: ./alice というファイルを探しに行き、無ければエラー
curl -d '@alice' https://api.example.com/items

@ を含む値をそのまま送りたいときは --data-raw を使ってください。これは @ を特別扱いしません。

Content-Type は自動では JSON にならない

-d を使うと、明示しない限り Content-Type: application/x-www-form-urlencoded が付きます。JSONを送っているつもりでヘッダーを付け忘れると、サーバー側でパースに失敗します。

# ヘッダーが必要
curl -H 'Content-Type: application/json' \
     -d '{"name":"Alice"}' https://api.example.com/items

curl 7.82以降は --json という短縮形があり、Content-Type: application/json と Accept: application/json を同時に付けてくれます。ただし古い環境では使えないので、共有するコマンドでは明示的に書くほうが安全です。

クォートの使い分けが一番の事故要因

書き方 挙動
'...'(シングル) 中の $ や " をそのまま渡す。JSONを送るならこちら
"..."(ダブル) シェルが $変数 を展開する

JSONはダブルクォートを含むので、外側はシングルクォートが基本です。

# OK
curl -d '{"name":"Alice"}' https://api.example.com/items

# シェルが "name" のクォートを剥がして壊れる
curl -d "{"name":"Alice"}" https://api.example.com/items

一方、トークンを環境変数から入れたいときはダブルクォートが必要です。混在させる場合は次のように書き分けます。

curl -H "Authorization: Bearer $TOKEN" \
     -d '{"name":"Alice"}' https://api.example.com/items

Windowsのコマンドプロンプトはシングルクォートを解釈しません。 PowerShellでは curl が Invoke-WebRequest のエイリアスになっている場合もあるため、curl.exe と明示するか、WSLやGit Bashで実行するのが確実です。

データ送信オプションの違い

-d の仲間は、「何をどう変換して送るか」で使い分けます。

オプション 変換 向いている用途
-d @ で始まる値はファイル読み込み。ファイルの改行は取り除かれる フォーム・短いJSON
--data-raw @ を特別扱いしない @ を含む文字列をそのまま送る
--data-binary 改行も含めてそのまま送る 改行を保ちたいファイル・バイナリ
--data-urlencode 値をパーセントエンコードする 日本語や記号を含むフォーム値・クエリ
-F multipart/form-data として送る ファイルアップロード

ファイルを読ませるなら -d @payload.json、標準入力から渡すなら -d @- です。JSONファイルの改行を保ちたい場合や、バイナリを送る場合は --data-binary @file を使います。

タイムアウトとリトライ

スクリプトからcurlを呼ぶときは、待ち続けて固まらないように時間を指定します。

curl --connect-timeout 5 --max-time 30 --retry 3 https://api.example.com/items
  • --connect-timeout: 接続できるまで待つ秒数
  • -m, --max-time: 全体(転送完了まで)の秒数。大きいファイルのダウンロードでは長めに
  • --retry: タイムアウトや一部のHTTPエラー(429・502・503・504など)のときに再試行する回数

HTTPが404や500でも、curlは成功(終了コード0)で終わるのが既定です。スクリプトで失敗を検知したいときは -f を付けます。

curl -fsS https://api.example.com/health || echo "失敗"

ステータスコードだけを取りたいときは -w を使います。

curl -s -o /dev/null -w '%{http_code}\n' https://example.com/

Windowsでは /dev/null の代わりに NUL と書きます。-w では %{time_total}(合計秒数)などの変数も使えます。

主な終了コード

スクリプトで $? を確認するときの目安です(全一覧は man curl の「EXIT CODES」)。

コード 意味
0 成功
6 ホスト名を解決できない
7 接続に失敗した
22 HTTPが400以上(-f 指定時)
28 タイムアウト
35 TLS接続(ハンドシェイク)に失敗した
60 サーバー証明書を検証できない

Windowsの curl.exe で使うとき

Windows 10(バージョン1803)以降には、標準で curl.exe が入っています。オプションはLinuxやmacOSと同じですが、シェルの違いで書き方が変わります。

項目 コマンドプロンプト(cmd) PowerShell
呼び出し curl / curl.exe curl.exe と書く(curl は Invoke-WebRequest のエイリアスのことがある)
クォート ダブルクォートのみ(シングルは使えない) シングルもダブルも使えるが、内側の " が落ちることがある
行の継続 ^ バッククォート `

JSONの内側のダブルクォートは、cmdでは \" でエスケープします。

curl.exe -X POST -H "Content-Type: application/json" -d "{\"name\":\"Alice\"}" https://api.example.com/items

PowerShellでもJSONの引用符が崩れやすいので、JSONをファイルに書いて -d @body.json で渡すのが確実です。

curl.exe -X POST -H "Content-Type: application/json" -d "@body.json" https://api.example.com/items

迷ったら、WSLやGit Bashなど、シングルクォートが使えるシェルで実行すれば、この記事の例をそのまま使えます。

URLに & を含むならクォートで囲む

クエリパラメータが複数あるURLをそのまま貼ると、シェルが & をバックグラウンド実行と解釈してコマンドが途中で切れます。

# 壊れる: limit=10 までしか渡らない
curl https://api.example.com/items?limit=10&offset=20

# 正しい
curl 'https://api.example.com/items?limit=10&offset=20'

パラメータに日本語や記号が入る場合は、事前にパーセントエンコードが必要です。手元で確認するなら URLエンコード・デコード が使えます。curlに任せる方法もあり、-G と --data-urlencode を組み合わせるとクエリ文字列として安全に組み立てられます。

curl -G https://api.example.com/search --data-urlencode 'q=東京 タワー'

安易に付けないほうがいいオプション

-k / --insecure: サーバー証明書の検証を無効にします。手元の自己署名証明書を試すときには必要ですが、エラーを消すために付けたまま共有・本番投入されるのが典型的な事故です。証明書の問題は証明書側で直してください。

-L / --location: リダイレクトを追跡します。便利ですが、POSTのリダイレクト時にメソッドやボディの扱いが変わることがあります。挙動を固定したいなら --post301 --post302 --post303 で明示できます。

調べたcurlをそのままコードにする

読み解いたcurlをアプリケーションのコードに移すとき、ヘッダーやボディを手で書き写すのは間違いのもとです。cURLコンバーター にコマンドを貼り付ければ、JavaScript・Python・Goなどのリクエストコードに変換できます。クォートの対応やヘッダーの分解はツール側が処理します。

送信するJSONの整形や構文確認は JSON整形・構文チェック、クエリ文字列の中身を見たいときは URLパラメータ→JSON変換 が便利です。いずれもブラウザ内で処理が完結するため、認証トークンを含むコマンドを貼り付けても外部に送信されません。

まとめ

  • -d を付けると自動でPOSTになる。-X GET と併用するとボディ付きGETという扱いにくい形になる
  • -d の値が @ で始まるとファイル読み込み。文字列として送るなら --data-raw
  • -d だけでは Content-Type はフォーム形式。JSONなら明示するか --json(curl 7.82+)
  • JSONを送るなら外側はシングルクォート。変数展開が必要な箇所だけダブルクォート
  • URLに & があるならクォートで囲む。値のエンコードは -G --data-urlencode が安全
  • -k はエラーを消す道具ではない。-L はPOSTの挙動が変わりうる
  • スクリプトでは --connect-timeout と --max-time を付け、失敗検知には -f(終了コード22)を使う
  • Windowsでは curl.exe と書く。JSONはファイルにして -d @body.json で渡すと崩れにくい

よくある質問

curlのオプションを一覧で確認するには?

curl --help all で全オプションの一覧が、curl --help category でカテゴリ別の一覧が出ます。詳しい説明は man curl で読めます。Windowsでは curl.exe --help all です。よく使うものは、この記事の「オプション一覧(用途別)」の表にまとめています。

curl と curl.exe は何が違うのですか?

Windows PowerShell では curl が Invoke-WebRequest のエイリアスになっていることがあり、オプションも別物です。本物のcurlを呼ぶには curl.exe と書きます。コマンドプロンプトでは、どちらを書いても curl.exe が呼ばれます。

curlはHTTPが404でも終了コード0になります。失敗にできますか?

-f(--fail)を付けると、HTTPが400以上のときに本文を出さず、終了コード22で終わります。スクリプトで失敗を検知したいときに使います。あわせて --connect-timeout と --max-time で待ち時間を決めておくと、固まりません。

-X POST は書かなくてもいいのですか?

-d や -F を付けた時点で自動的にPOSTになるため、多くの場合は不要です。ただし明示しておくと読み手に意図が伝わるので、共有するコマンドでは書いておく価値があります。注意すべきは -X GET と -d の併用で、これはボディ付きGETになり、環境によって無視されたり拒否されたりします。

-d と --data-raw の違いは何ですか?

値が @ で始まったときの扱いだけが違います。-d は @ に続く文字列をファイル名とみなして中身を読み込みますが、--data-raw はそのまま文字列として送ります。@ を含むデータ(メールアドレスなど)を送るなら --data-raw を使ってください。

JSONを送ったのにサーバーがパースしてくれません

-d を使うと既定の Content-Type は application/x-www-form-urlencoded になるため、-H 'Content-Type: application/json' を付ける必要があります。curl 7.82以降なら --json でヘッダーごと指定できます。

Windowsでコマンドが動きません

コマンドプロンプトはシングルクォートを解釈せず、PowerShellでは curl が Invoke-WebRequest のエイリアスになっていることがあります。curl.exe と明示するか、WSLやGit Bashなど、シングルクォートを解釈するシェルで実行してください。

認証トークン付きのコマンドを貼り付けても大丈夫ですか?

cURLコンバーター はブラウザ内で処理が完結し、貼り付けた内容がサーバーへ送信されることはありません。ただし変換後のコードにトークンがそのまま残るため、コードをコミットする前に環境変数へ切り出すことをおすすめします。