curl コマンドの使い方・主要オプション実践ガイド

コマンドリファレンス

2025.08.212026.08.26

API bash curl HTTPS JSON Linux エラーハンドリングコマンドライン

curl（カール）コマンドは、コマンドラインから HTTP や HTTPS、FTP などの多彩なプロトコルを使ってデータ通信を行うための標準的なツールです。Web API の動作検証（REST API テスト）やレスポンスヘッダーの確認、ファイルのダウンロード・アップロード、さらには Bash スクリプトによる運用自動化まで、エンジニアの実務において不可欠な存在となっています。

本記事では、curl コマンドの基本構文から、実務で頻出する主要オプション（-X POST, -H, -d, -o/-O, -s, -I など）の早見表、API リクエストやヘルスチェックの実践レシピ、エラーハンドリングのベストプラクティスまで、実務目線でわかりやすく解説します。

1. 【早見表】curl コマンドの基本構文と主要オプション一覧
1. 即コピペで使える最頻出コマンド 5 選
2. 主要オプション早見表（カテゴリ別）
2. 基本的な使い方（初歩からのステップ）
3. 主要オプション詳細リファレンス（目的別）
4. 実務で役立つ実践レシピ（逆引きチートシート）
5. よくあるエラーコードとトラブルシューティング
1. URL 内の特殊文字（& や ?）によるシェル展開エラーに注意
6. curl と wget の違い・使い分け
7. よくある質問（FAQ）
8. 関連コマンド
9. まとめ
関連記事

1. 【早見表】curl コマンドの基本構文と主要オプション一覧

curl の基本構文は非常にシンプルです。

curl [オプション] <URL>

オプションを付けずに実行すると、指定した URL に対して HTTP GET リクエストを送信し、取得したレスポンス本文（HTML や JSON 等）を標準出力にそのまま出力します。

即コピペで使える最頻出コマンド 5 選

用途	コマンド例	解説
ヘッダーのみ確認	`curl -I https://example.com`	ステータスコードやレスポンスヘッダーを素早く確認
ファイル保存（URL名）	`curl -O https://example.com/file.tar.gz`	リモートのファイル名そのままでローカルに保存
JSON POST送信	`curl -X POST https://example.com/api -H "Content-Type: application/json" -d '{"key":"val"}'`	Web API に JSON データを送信
リダイレクト追跡	`curl -L https://example.com`	301 / 302 リダイレクト先に自動追従
スクリプト用安全実行	`curl -sSfL https://example.com/script.sh`	サイレント・エラー時即停止・リダイレクト追従

主要オプション早見表（カテゴリ別）

実務で頻出するオプションを目的別に整理しました。短縮形とロングネームの両方を把握しておくと、CLI での即座の実行やスクリプト記述で役立ちます。

分類	短縮	ロングオプション	説明
リクエスト制御	`-X`	`--request <METHOD>`	HTTP メソッド（GET, POST, PUT, DELETE, PATCH 等）を指定
	`-d`	`--data <DATA>`	POST 用リクエストボディ（データ）を送信（自動で POST 扱い）
	`-G`	`--get`	`-d` で指定したデータを URL のクエリ文字列として GET 送信
	`-F`	`--form <NAME=CONTENT>`	`multipart/form-data` 形式でフォームやファイルを送信
ヘッダー・認証	`-H`	`--header <HEADER>`	カスタム HTTP ヘッダー（`Content-Type` や `Authorization` 等）を追加
	`-u`	`--user <USER:PASS>`	Basic 認証または Digest 認証のユーザー名とパスワードを指定
	`-A`	`--user-agent <AGENT>`	User-Agent 文字列を指定
	`-b / -c`	`--cookie / --cookie-jar`	Cookie データの送信（`-b`）およびファイルへの保存（`-c`）
出力・保存	`-o`	`--output <FILE>`	レスポンスを指定したファイル名で保存
	`-O`	`--remote-name`	URL 末尾のファイル名をそのまま使ってローカルに保存
	`-I`	`--head`	HTTP レスポンスヘッダーのみを取得（HEAD メソッド）
	`-i`	`--include`	レスポンスヘッダーとレスポンス本文の両方をまとめて表示
	`-w`	`--write-out <FORMAT>`	通信完了時にステータスコードやレスポンス時間などをフォーマット出力
通信・エラー制御	`-s / -S`	`--silent / --show-error`	進捗・エラー表示を非表示（`-s`）。`-S` を足すとエラー時のみ表示
	`-L`	`--location`	3xx 系の HTTP リダイレクト先を自動追跡
	`-f`	`--fail`	HTTP ステータス 4xx / 5xx 受信時に本文を出力せず異常終了コードを返す
	`-k`	`--insecure`	SSL / TLS 証明書の検証をスキップ（検証・開発用途限定）
	`-m`	`--max-time <SEC>`	通信全体の最大タイムアウト秒数を設定

2. 基本的な使い方（初歩からのステップ）

① Webページ・APIレスポンスの取得（基本のGET通信）

もっとも単純な使い方は、URL をそのまま渡す方法です。

curl https://example.com

サーバーから返された HTML や JSON のテキストデータがターミナル画面に一括で流れます。

② ファイルとして保存する（-o と -O の使い分け）

レスポンスをファイルに保存したい場合、-o（小文字）と -O（大文字）の2種類があります。

-o <ファイル名>（output）: 保存するローカルファイル名を自分で指定する
-O（remote-name）: URL の末尾にあるファイル名をそのままローカルの保存先にする

# ファイル名を指定して保存（-o）
curl -o downloaded_page.html https://example.com

# リモートのファイル名（package.tar.gz）で保存（-O）
curl -O https://example.com/downloads/package.tar.gz

ダウンロード用途の比較対象となる wget コマンドとの違いについては後述します。

③ レスポンスヘッダーのみを取得する（-I / –head）

Web サーバーの生死確認や HTTP ステータスコード、キャッシュ設定（Cache-Control）、Content-Type などを手軽に調査したいときは -I を指定します。

curl -I https://example.com

出力例：

HTTP/2 200 
content-type: text/html; charset=UTF-8
date: Wed, 26 Aug 2026 07:00:00 GMT
server: nginx
cache-control: max-age=600

④ リダイレクトを自動追跡する（-L / –location）

http:// から https:// への転送や短縮 URL など、301 / 302 リダイレクトが設定されている URL に対して curl を実行すると、既定ではリダイレクト指示のヘッダーのみで終了してしまいます。最終的な転送先コンテンツを取得するには -L オプションを付与します。

curl -L http://example.com

3. 主要オプション詳細リファレンス（目的別）

リクエスト方式・データ送信オプション

API テストやフォーム送信で重要となるデータ送信系オプションです。

-X <METHOD>: HTTP メソッドを明示的に指定します（-X POST, -X PUT, -X DELETE, -X PATCH 等）。
-d <DATA>: リクエストボディを送信します。-d を指定すると、特に -X を書かなくても自動的に POST メソッドとして送信されます。
-d @filename.json: @ をプレフィックスに付けることで、ファイルの中身をそのまま POST ボディとして送信できます。
--data-urlencode "key=value": 日本語やスペース、記号が含まれる文字列を自動的に URL エンコードして送信します。
-F "name=value": multipart/form-data 形式で送信します。ファイル添付時は -F "upload=@/path/to/image.png" のように指定します。

ヘッダー指定・認証・Cookie オプション

-H "Header-Name: Value": 任意の HTTP ヘッダーを送信します。複数指定する場合は -H "Header1: ..." -H "Header2: ..." のように重ねて指定します。
-u "username:password": Basic 認証のクレデンシャルを送信します。パスワード部分を省略（-u username）するとターミナルで対話型入力プロンプトが表示されます。
-A "User-Agent名": サーバーに通知する User-Agent を変更します。スマホ端末や特定ブラウザの挙動検証に便利です。
-c <ファイル> / -b <ファイルまたは文字列>: サーバーから送られてきた Cookie をファイルに保存（-c cookie.txt）し、次回リクエスト時に送信（-b cookie.txt）します。

出力・ログ・デバッグオプション

-s（–silent）: 通信中のプログレスメーター（進捗バー）や不要なメッセージを非表示にします。
-S（–show-error）: -s と併用することで、通常時は無口（サイレント）でありながら、通信エラーが発生したときだけ標準エラー出力に原因を表示します（curl -sS）。
-v（–verbose）: リクエストヘッダー（> で表示）、レスポンスヘッダー（< で表示）、TLS ハンドシェイク情報などの詳細な通信ログを出力します。デバッグの必須オプションです。
-w <フォーマット>: 通信完了時に HTTP ステータスコードや所要時間をカスタマイズして出力します（例: -w "%{http_code}\n"）。

通信制御・タイムアウト・エラーハンドリング

--connect-timeout <秒>: サーバーとの TCP 接続確立までのタイムアウト秒数を設定します。
-m <秒>（–max-time）: データ送受信を含む通信全体のタイムアウト秒数を指定します。スクリプトが無限待機するのを防ぐために必須です。
--retry <回数>: 5xx エラーや一時的なネットワーク不通時に自動でリトライする回数を指定します。--retry-delay <秒> と併用します。
-f（–fail）: 404 や 500 などの HTTP エラー時に、HTML エラーページを画面出力せず、curl の終了ステータスコードを非 0（エラー）にして即座に失敗させます。
-k（–insecure）: 自己署名証明書（オレオレ証明書）などの SSL/TLS 検証エラーを無視して通信します。本番通信ではセキュリティ上使用を避けてください。
-x <[プロトコル://]ホスト:ポート>: HTTP/SOCKS プロキシサーバーを経由して通信します。

4. 実務で役立つ実践レシピ（逆引きチートシート）

① REST API（JSON）へのリクエストと jq 連携

Web API に対して JSON データを POST 送信し、Bearer 認証トークンを付与する典型的なパターンです。jq コマンドをパイプで繋ぐことで、JSON レスポンスの整形やキー抽出が容易になります。

# JSON データの POST 送信
curl -s -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer my_secret_token_123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bash玄",
    "role": "admin"
  }' | jq .

# ファイル内の JSON をそのまま POST 送信
curl -s -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer my_secret_token_123" \
  -H "Content-Type: application/json" \
  -d @payload.json | jq '.id'

外部 API とのスクリプト連携については、bashでChatGPT APIを使う方法でも具体的な自動化コードを解説しています。

② HTTPステータスコード・通信レイテンシの測定

-o /dev/null でレスポンス本文を破棄し、-w オプションを使ってステータスコードや応答時間をミリ秒単位で計測します。監視スクリプトや死活監視で強力な手法です。

# ステータスコードのみを取得（例: 200）
HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" https://example.com)
echo "Status: ${HTTP_STATUS}"

# 詳細な通信時間内訳（DNS名前解決、TCP接続、TTFB、総時間）を計測
curl -s -o /dev/null -w "\
DNS名前解決時間:  %{time_namelookup}s\n\
TCP接続完了時間:  %{time_connect}s\n\
TLS接続完了時間:  %{time_appconnect}s\n\
初回レスポンス(TTFB): %{time_starttransfer}s\n\
総所要時間:      %{time_total}s\n\
HTTPコード:      %{http_code}\n" https://example.com

③ ファイルのダウンロード（中断再開・帯域制限）

大きなサイズのファイルをダウンロードする際、ネットワーク切断からの再開や、社内回線を圧迫しないための帯域制限を設定できます。

# 中断したダウンロードを途中から再開（-C -）
curl -C - -O https://example.com/large_backup.tar.gz

# ダウンロード転送速度を 1MB/s に制限（--limit-rate）
curl --limit-rate 1M -O https://example.com/large_backup.tar.gz

④ フォーム送信とファイルアップロード（multipart/form-data）

Web フォームからのファイル添付アップロードを再現する場合、-F オプションを使用します。ファイル名の前に @ を付けるのがポイントです。

# ファイルとテキストパラメータを同時に POST アップロード
curl -X POST https://example.com/api/upload \
  -F "user_id=1024" \
  -F "document=@/path/to/report.pdf;type=application/pdf"

⑤ Cookie を利用したログインセッションの維持

ログイン処理を行って Cookie を保存し、その認証状態を保持したままマイページ等の限定 URL にアクセスする流れです。

# Step 1: ログインして Cookie をファイルに保存（-c）
curl -s -c cookie.txt \
  -X POST https://example.com/login \
  -d "username=myuser&password=mypassword"

# Step 2: 保存した Cookie を送信して保護されたページを取得（-b）
curl -s -b cookie.txt https://example.com/dashboard/data.json

⑥ シェルスクリプト内での安全な実行テンプレート

Bash スクリプト内で curl を呼び出す際、エラーを検知できずに処理が続行してしまう事故を防ぐための定型パターンです。-sSfL の組み合わせが黄金律となります。

#!/usr/bin/env bash
set -euo pipefail

API_URL="https://api.example.com/health"
MAX_RETRY=3
TIMEOUT_SEC=10

# -s: サイレント
# -S: エラー時のみエラー出力
# -f: HTTP 4xx/5xx で即座に終了ステータス非0を返す
# -L: リダイレクトを自動追跡
if response=$(curl -sSfL --max-time "${TIMEOUT_SEC}" --retry "${MAX_RETRY}" "${API_URL}"); then
    echo "API 疎通成功:"
    echo "${response}" | jq .
else
    echo "エラー: API への通信に失敗しました (Exit Code: $?)" >&2
    exit 1
fi

5. よくあるエラーコードとトラブルシューティング

エラー表示 / 終了コード	主な原因	切り分け・対処法
`curl: (6) Could not resolve host`	DNS 名前解決に失敗	URL のタイポ確認。ping や `nslookup` でドメイン解決を確認
`curl: (7) Failed to connect`	接続先ポートが閉鎖、またはサーバーが停止	ポート番号確認、Web サーバーの起動状態（nginx 等）やファイアウォール設定を確認
`curl: (22) The requested URL returned error: 404 / 500`	`-f` 指定時に HTTP エラーを検知	リクエスト先エンドポイントの存在確認、API パラメータの妥当性を確認
`curl: (28) Operation timed out`	通信がタイムアウト時間に到達	`--max-time` や `--connect-timeout` を延長。サーバー負荷やネットワーク帯域を確認
`curl: (35) / (60) SSL certificate problem`	SSL/TLS 証明書の期限切れや信頼チェーン不備	OS の CA 証明書パッケージ（`ca-certificates`）を更新。検証時のみ `-k` で一時回避
`curl: command not found`	OS に curl が未導入	パッケージマネージャー（`apt install curl` 等）で導入

URL 内の特殊文字（& や ?）によるシェル展開エラーに注意

クエリパラメータを含む URL（例: https://example.com/api?a=1&b=2）をクォート（" " や ' '）で囲まずに実行すると、シェルが & をバックグラウンド実行指示として解釈してしまい、意図しないリクエストになります。URL は必ずダブルクォートまたはシングルクォートで囲む習慣をつけましょう。

# NG（& の直前でバックグラウンド実行と誤認される）
curl https://example.com/api?user=taro&role=admin

# OK（クォートで確実に囲む）
curl "https://example.com/api?user=taro&role=admin"

6. curl と wget の違い・使い分け

Linux 環境で Web からデータを取得するコマンドとして、curl と wget コマンドはよく比較されます。両者の特徴と実務での使い分け基準は以下の通りです。

比較項目	curl	wget
主な得意領域	Web API 通信、多様な HTTP メソッド、ヘッダー操作、双方向通信	Web サイトやファイルの一括・再帰ダウンロード
対応プロトコル	HTTP/HTTPS, FTP/FTPS, SFTP, SCP, LDAP, TELNET, DICT 等多数	HTTP/HTTPS, FTP
再帰ダウンロード（-r）	非対応（クローラー機能なし）	対応（サイト全体のミラーリング保存が可能）
既定の出力先	標準出力（ターミナル画面 / パイプ渡しが基本）	ファイルとして保存
スクリプト・API連携	`jq` や各種シェル処理とのパイプ連携に最適	単体ダウンロードスクリプト向き
ライブラリ提供	`libcurl` として C/Python/PHP 等の内部実装で広く採用	独立した CLI コマンド

使い分けの結論：「API を叩く、リクエストヘッダーを制御する、取得データをパイプで別コマンドに渡す」場合は curl を選び、「ファイルやサイト全体をそのまま再帰的にダウンロード・ミラーリング保存する」場合は wget を選ぶのが確実です。

7. よくある質問（FAQ）

Q1: スクリプトでよく見る「curl -sSfL」にはどんな意味がありますか？

4つの代表的なオプションをまとめた鉄板の記述です。不要な進捗メーターを消し（-s）、エラー発生時のみ原因を表示し（-S）、HTTP 4xx/5xx エラーで即座に異常終了させ（-f）、リダイレクトを自動追従（-L）します。スクリプトを安定稼働させるためのデファクトスタンダードです。

Q2: -d オプションを指定するとき、-X POST は省略できますか？

はい、省略可能です。curl は -d（または --data）が指定されると、内部的に既定のリクエストメソッドを POST に切り替え、Content-Type: application/x-www-form-urlencoded ヘッダーを自動設定します。ただし PUT や PATCH などのメソッドに変更したい場合は -X PUT -d "..." のように明示指定が必要です。

Q3: Windows の PowerShell で curl が意図通りに動かないのはなぜですか？

Windows PowerShell では、curl が標準コマンドレット Invoke-WebRequest のエイリアスとして登録されているためです。本来の curl を動かすには、拡張子を付けて curl.exe と実行するか、PowerShell 7 以降（エイリアス解除済み）を使用してください。

Q4: SSL証明書エラーを無視する「-k」オプションは本番で使っても良いですか？

原則として開発環境や内部検証環境のみに限定してください。-k（--insecure）を指定すると中間者攻撃（MITM）を検知できなくなるため、本番環境の API 連携や機密データ送信では正規の SSL 証明書を配置・検証することが必須です。

8. 関連コマンド

jq : curl で受信した JSON データの整形・フィールド抽出
wget : ファイルの再帰ダウンロード・ミラーリング専用コマンド
ping : サーバーとのネットワーク疎通確認
ssh / scp / sftp : リモートサーバー接続および暗号化ファイル転送
xargs : URL 一覧ファイルから curl を並列実行する処理
linux コマンド一覧 : Linux でよく使う基本コマンドを用途別に総まとめ

9. まとめ

curl コマンドは、単なる Web ページの取得にとどまらず、REST API の操作、ヘッダー解析、認証付き通信、運用スクリプトの自動化まで幅広くカバーするコマンドラインの必須ツールです。

基本取得: curl -I（ヘッダー確認）、curl -O（ファイル保存）、curl -L（リダイレクト追従）
API テスト: curl -X POST -H "Content-Type: application/json" -d '{...}' と jq の連携
スクリプト自動化: curl -sSfL --max-time 10 で安全かつ堅牢なエラーハンドリングを徹底

まずは早見表のコマンドから試し、日々のターミナル操作や自動化スクリプトに積極的に取り入れてみてください。