-sと-Lしか使ってない人必見！知ると得するcurlオプション集

-sと-Lしか使ってない人必見！知ると得するcurlオプション集

APIの動作確認をするとき、多くの方はとりあえず次のように叩いているのではないでしょうか。

curl -s https://example.com/api/users

これだけでも十分動きますが、実はもう少しオプションを足すだけで、レスポンスタイムの計測やエラーハンドリング、リトライまでcurl単体で完結してしまいます。

この記事では、知らなくても困らないけれど知っていると地味に得をする、実務で使えるcurlオプションをまとめます。

本記事はcurl公式マニュアル（curl(1) man page）をもとに、2026年9月時点で最新の8.19系（2026年3月リリース）を基準に確認しています。Ubuntu 24.04標準搭載のcurlは8.5系のため、環境によっては一部オプションが使えない場合があります。curl --version で手元のバージョンを確認してから読み進めてください。

レスポンスタイムをその場で数値化する

APIが遅いかどうかを体感ではなく数値で確認したいときは、-w（--write-out）オプションが便利です。

curl -s -o /dev/null -w "status=%{http_code} time=%{time_total}s\n" https://example.com/api/users

• -o /dev/null でレスポンス本文を捨てる
• -w で好きな情報だけをフォーマットして出力する

このコマンドを実行すると、以下のように結果だけが1行で表示されます。

status=200 time=0.183s

わざわざブラウザの開発者ツールを開かなくても、ターミナルの中でレスポンスタイムを確認できるのが利点です。

CIのヘルスチェックスクリプトに組み込んでおくと、地味に重宝します。

エラーなのに正常終了したように見える問題を防ぐ

curl はデフォルトだと、404や500が返ってきてもエラーメッセージのHTML本文を出力するだけで、コマンド自体の終了ステータスは0（成功扱い）になります。

シェルスクリプトの中で使う場合、これに気づかずハマった経験がある方も多いはずです。

対処法は -f（--fail）を付けるだけです。

curl -f https://example.com/api/users || echo "リクエストに失敗しました"

-f を付けておくと、HTTPステータスが400番台・500番台のときにcurl自体が失敗扱いになり、終了ステータスが0以外になります。

シェルスクリプトの && や || と組み合わせて使うことを考えるなら、基本セットとして付けておいて損はありません。

一時的なエラーを自動でリトライする

ネットワークが不安定な環境や、起動直後でまだ応答が安定しないサーバーに対して疎通確認をしたいとき、自前でリトライ用のループを書かなくてもcurlだけで完結します。

curl --retry 5 --retry-delay 2 --retry-all-errors https://example.com/health

• --retry 5 失敗時に最大5回まで再試行する
• --retry-delay 2 再試行の間隔を2秒に固定する
• --retry-all-errors 本来リトライ対象外の4xx/5xxエラーもリトライ対象に含める

--retry-all-errors はcurl 7.71.0以降で使えるオプションです。CI上でコンテナの起動待ちをするような場面で、bashの while ループを自作するよりも短く書けます。

--retry-all-errors は本来失敗として扱われるべきエラーまでリトライしてしまう可能性があるオプションです。認証エラー（401など）のように、リトライしても状況が変わらないケースでは無限に待たされることがあるため、必ず --max-time などと組み合わせて上限を設けてください。

-oと-O、-iと-Iの違いを整理する

似た見た目のオプションを混同しやすいので、ここで一度整理しておきます。

オプション	意味
-o ファイル名	レスポンス本文を指定したファイル名で保存する
-O	URLの末尾のファイル名をそのまま使って保存する
-i	レスポンスヘッダーを本文と一緒に表示する
-I	ヘッダーだけを取得する（本文は取得しない）

小文字と大文字で挙動がまったく違うため、-o のつもりで -O と打ってしまい、意図しないファイル名で保存されてしまうというのは意外とよくあるミスです。

jqと組み合わせてJSONを見やすくする

APIのレスポンスがJSONの場合、そのまま表示すると1行にまとまって読みにくいことがあります。

jq コマンドと組み合わせると、整形と抽出が同時にできます。

curl -s https://example.com/api/users | jq '.[] | {id, name}'

jq が入っていない環境では、python3 -m json.tool でも簡易的な整形は可能です。

curl -s https://example.com/api/users | python3 -m json.tool

jq のほうが柔軟にフィールドを抽出できるので、日常的にAPIを触るならインストールしておくことをおすすめします。

まとめ

• -w を使うとレスポンスタイムやステータスコードを数値としてその場で取得できる
• -f を付けないと、HTTPエラーでもcurlの終了ステータスは成功扱いになってしまう
• --retry 系のオプションを使えば、リトライ処理を自分でループとして書く必要がない
• -o/-O と -i/-I は大文字小文字で挙動が変わるので注意する
• jq と組み合わせるとJSONレスポンスの確認が一気に楽になる

普段何気なく打っている curl コマンドですが、オプションを2つ3つ足すだけでデバッグの手間がかなり減ります。

次にAPIをさわるときは、ぜひ試してみてください。