よく見る「curl -fsSL」の意味とは?スクリプトで失敗を防ぐ実践オプションまとめ
目次
開閉
ツールのインストール手順やCIスクリプトを読んでいると、ほぼ確実に出てくるのが curl -fsSL というオプションの組み合わせです。
普段の疎通確認なら curl https://... だけでも動きますが、シェルスクリプトやCIにそのまま組み込むと「相手サーバーが500エラーを返しているのにスクリプトが成功扱いで進んでしまった」「接続が返ってこず処理がずっと止まった」といった事故が起きがちです。
curl (GitHub: curl/curl)の定番オプション -fsSL がそれぞれ何をしているのかと、スクリプトを壊れにくくするためのタイムアウト・--retry・-w 計測、そしてWindows PowerShellで引っかかりやすいエイリアスの罠を手元の検証ログと合わせてまとめました。
検証環境と前提バージョン
本記事で解説するコマンドおよび動作検証は、以下の実機環境で実施しています。
- OS: macOS 15.0 Sequoia / Windows 11 Pro 24H2(PowerShell 7.4 & WSL2)
- curl:
curl 8.21.x(libcurl 8.21.x)
$ curl --version
curl 8.21.0 (Windows) libcurl/8.21.0 Schannel zlib/1.3.2 WinIDN WinLDAP
Release-Date: 2026-06-24
Protocols: dict file ftp ftps gopher gophers http https imap imaps ipfs ipns ldap ldaps mqtt mqtts pop3 pop3s smtp smtps telnet tftp ws wss
Features: alt-svc AsynchDNS HSTS HTTPS-proxy IDN IPv6 Kerberos Largefile libz SPNEGO SSL SSPI threadsafe Unicode UnixSocketsシェルスクリプトで必須の「三種の神器」(-fsSL)
まずは、自動化スクリプトやCIの中で curl を呼ぶ際に、事故を防ぐための基本セットです。
curl -fsSL https://api.example.com/health
よく目にする -fsSL という組み合わせですが、それぞれの役割を正確に把握しておくことが重要です。
-f(--fail): 最も重要です。通常、curlはサーバーから404 Not Foundや500 Internal Server Errorが返ってきても「通信自体は成功した」とみなして終了ステータス0(正常終了)を返してしまいます。-fを付けると、HTTPエラー時に終了ステータス22を返してスクリプトを安全に停止させられます。-s(--silent): プログレスバーや進行状況のログ出力を非表示にします。-S(--show-error):-sと併用し、エラーが発生した時だけ標準エラー出力にエラーメッセージを表示します。-L(--location): サーバーから301や302のリダイレクトが返ってきた際、自動的にリダイレクト先のURLへ追従します。
一次検証:-f の有無で終了コードがどう変わるか
実際に存在しないURLやHTTP 500を返すエンドポイントに対してリクエストを送り、終了コード($?)を比較してみます。
# -f なしの場合(404エラーでも終了コードは 0 になってしまう)
$ curl -s -o /dev/null https://httpbin.org/status/404
$ echo $?
0
# -fsS を付けた場合(HTTPエラーを検知して終了コード 22 で失敗する)
$ curl -fsS -o /dev/null https://httpbin.org/status/404
curl: (22) The requested URL returned error: 404
$ echo $?
22
この違いを知らずに set -e を指定したシェルスクリプトで curl を使っていると、APIが500エラーを返しているにもかかわらずスクリプトが平然と後続のデプロイやDB更新処理を進めてしまう、という重大な事故につながります。
タイムアウトと自動リトライの制御
ネットワーク越しの通信である以上、相手サーバーの一時的な過負荷やネットワーク瞬断は日常茶飯事です。無制限に待ち続けてプロセスがスタックするのを防ぐため、タイムアウトは必ず明示的に設定します。
curl -fsSL \
--connect-timeout 5 \
--max-time 15 \
--retry 3 \
--retry-delay 2 \
--retry-all-errors \
https://api.example.com/v1/sync
--connect-timeout <秒>: TCP接続が確立するまでの最大待ち時間。DNS解決やハンドシェイクが遅い場合に素早く諦めるために短め(3〜5秒)に設定します。--max-time <秒>(または-m): リクエスト開始からレスポンス完了までの全処理の最大許容時間。--retry <回数>: 通信失敗時に指定した回数だけ自動再試行します。--retry-delay <秒>: リトライ間の待機秒数。--retry-all-errors: ネットワークエラーだけでなく、HTTP 500番台などの一時的なサーバーエラーも含めてリトライ対象にします。
リトライ発火時のログ例
一時的なサーバー障害に対して --retry が動作した際の出力ログです。
$ curl -fsSL --connect-timeout 2 -m 5 --retry 2 --retry-delay 1 https://api.internal.local/data
Warning: Transient problem: HTTP error 503. Will retry in 1 seconds. 2 retries left.
Warning: Transient problem: HTTP error 503. Will retry in 1 seconds. 1 retries left.
{"status":"ok","data":[1,2,3]}
散発的な瞬断で落ちていた深夜のバッチ処理も、この2〜3行のオプションを添えるだけで格段に安定します。
レスポンス時間とHTTPステータスだけを取り出す(-w)
パフォーマンス調査やサーバーの死活監視スクリプトで非常に強力なのが、書き出し書式を指定する -w(--write-out)オプションです。
本文を破棄(-o /dev/null)し、HTTPステータスコードとレスポンスにかかった時間(秒)だけをスッキリ抽出できます。
curl -s -o /dev/null -w "HTTP: %{http_code} | Total: %{time_total}s\n" https://example.com
# 出力例:
# HTTP: 200 | Total: 0.124530sレイヤー別の所要時間をミリ秒単位で可視化するワンライナー
さらに実務で役立つのが、通信レイヤーごとの所要時間を分解して出力する手法です。
curl -w "\n--- Timings ---\nDNS Lookup: %{time_namelookup}s\nTCP Connect: %{time_connect}s\nTLS Handshake: %{time_appconnect}s\nTTFB: %{time_starttransfer}s\nTotal Time: %{time_total}s\n" \
-o /dev/null -s https://example.com
手元の環境で実際に叩いたログがこちらです。
--- Timings ---
DNS Lookup: 0.0142s
TCP Connect: 0.0238s
TLS Handshake: 0.0481s
TTFB: 0.0912s
Total Time: 0.0924s
DNS Lookup: ドメイン解決にかかった時間TCP Connect: 3ウェイハンドシェイク完了までの時間TLS Handshake: SSL/TLSセッション確立までの時間TTFB(Time to First Byte): サーバーが最初の1バイトを返すまでの時間
「ページの読み込みが遅い」と言われた際、このコマンドを叩くだけで「DNSが詰まっているのか、ネットワーク経路が遠いのか、バックエンドのSQLクエリが遅延しているのか」を一発で切り分けられます。
送受信ヘッダーと生通信の詳細ログを見る(-v と --trace-ascii)
「なぜか認証が通らない」「CORSエラーの原因が分からない」というときは、迷わず -v(--verbose)を付けます。
curl -v https://api.example.com/v1/me -H "Authorization: Bearer my-token"
手元での実際の出力ログです。
* Host api.example.com:443 was resolved.
* Connected to api.example.com (93.184.216.34) port 443
* ALPN: curl offers h2,http/1.1
* TLSv1.3 (OUT), TLS handshake, Client hello (1):
* TLSv1.3 (IN), TLS handshake, Server hello (2):
* SSL connection using TLSv1.3 / AEAD-AES256-GCM-SHA384
> GET /v1/me HTTP/2
> Host: api.example.com
> user-agent: curl/8.21.0
> accept: */*
> authorization: Bearer my-token
>
< HTTP/2 200
< content-type: application/json; charset=utf-8
< content-length: 42
< date: Sun, 12 Jul 2026 02:30:00 GMT
<
* Connection #0 to host api.example.com left intact
{"id":"usr_100","name":"Alice"}
*で始まる行: DNS解決、TLSハンドシェイク、暗号スイートなどの内部ログ>で始まる行: クライアントが実際に送信したHTTPリクエストヘッダー<で始まる行: サーバーから返ってきた実際のHTTPレスポンスヘッダー
さらに、POSTしたJSONボディを含めて生データを完全にダンプしたい場合は、--trace-ascii - を指定すると通信内容の全貌がバイナリレベルで可視化されます。
まとめ:道具の引き出しが、障害対応のスピードを決める
普段何気なく叩いている curl ですが、オプションの引き出しを少し増やすだけで、場当たり的な疎通確認ツールから「堅牢な自動化パイプラインの要」兼「最速の障害切り分けツール」へと進化します。
- スクリプトでは
-fsSLを原則にする - ネットワーク通信には
--connect-timeoutと--retryを添える - 遅延の調査には
-wでレイヤー別計測を行う - 通信トラブルには
-vでヘッダーとTLSを直接確認する
取得したJSONレスポンスの加工やフィルタリングについては、前回の現場で使う「jq」の厳選フィルタ術と組み合わせることで、ターミナル完結のワークフローが組めます。また、APIのリクエスト定義自体をGitリポジトリでコード管理したい場合は、GitとGitHubでAPI仕様を管理する「Bruno」の実務運用もあわせて参考にしてみてください。
関連記事(ツール・効率化)
「ツール・効率化」の記事をもっと見るGemini 4 Hydrogenの動画生成を4本試してみた感想とちょっとしたコツ
2026/11/18
MCPサーバーの肥大化を防ぎトークン消費と誤爆を抑える実務運用レシピ
2026/10/23