【Linux】curlコマンドの使い方完全ガイド｜GET/POST・JSON送信・オプション早見表

コマンドリファレンス

2025.08.212026.10.20

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

Linuxのターミナルやシェルスクリプトで外部Webサーバーと通信するとき、最も頼りになる標準コマンドが `curl`（Client URL）です。Web APIの動作検証からJSONデータの送受信、ファイルのダウンロード、サーバー監視スクリプトまで、エンジニアの実務現場で使わない日はありません。

今回は、実務で今すぐ役立つ コピペスニペット をはじめ、主要オプションの早見表、REST API検証やヘルスチェックの実践レシピ、現場でハマりがちなエラー対処法まで、Bash玄が徹底解説します。

## 【今すぐ使える】curlコマンド最速コピペスニペット

日々の業務ですぐに実行したい頻出コマンドスニペットをまとめました。まずはこの3つを押さえておけば、大半の日常作業を素早くこなせます。

### 【GET】WebページやAPIのレスポンスを取得・表示する（curl URL）

オプションを指定せずにURLを渡すと、指定したエンドポイントへHTTP GETリクエストを送信し、取得したレスポンス本文（HTMLやJSONなど）を標準出力にそのまま表示します。

“`bash
# WebページやAPIエンドポイントへGETリクエストを送信
curl https://example.com
“`

取得したレスポンスをパイプで別のコマンド（`grep` や `jq` など）に渡して加工する際にも、この基本形が起点となります。

### 【POST】JSONデータを送信してAPIを呼び出す（curl -X POST -H …）

Web APIに対してJSONボディを送信する場合は、`-X POST` でメソッドを指定し、`-H “Content-Type: application/json”` でヘッダーを付与した上で、`-d` にJSON文字列を渡します。

“`bash
# JSONデータをPOST送信してAPIを実行
curl -X POST https://api.example.com/v1/users \
-H “Content-Type: application/json” \
-d ‘{“name”: “Bash玄”, “role”: “admin”}’
“`

なお、curlは `-d` オプションを指定した時点で自動的にPOSTリクエストとして解釈するため、`-X POST` は省略可能です。ただし、スクリプトの可読性や明示的な設計を重視する場合は `-X POST` を明記しておくのが実務での安全なプラクティスです。

### 【ヘッダー確認】レスポンスヘッダーのみを取得する（curl -I URL）

Webサーバーの死活確認やHTTPステータスコード、キャッシュ制御（`Cache-Control`）、Content-Typeなどを調査したいときは、`-I`（大文字のアイ、または `–head`）を使用します。

“`bash
# HTTPレスポンスヘッダーのみを取得（HEADリクエスト）
curl -I https://example.com
“`

実行結果の先頭に `HTTP/2 200` や `HTTP/1.1 301 Moved Permanently` などのステータス行が表示されるため、重いコンテンツ本体をダウンロードすることなくサーバーの状態を瞬時に判定できます。

## curlコマンドとは？wgetとの違いと用途

`curl` は、HTTP/HTTPSをはじめ、FTP、FTPS、SFTP、SCP、LDAP、TELNETなど数十種類以上のプロトコルに対応した高機能なデータ転送ツールです。内部コアである `libcurl` は、Python、PHP、Goなど様々なプログラミング言語のHTTPクライアントライブラリとしても広く採用されています。

LinuxでURLからデータを取得するコマンドとして、よく `wget` と比較されます。両者には明確な得意分野の違いがあるため、用途に応じて正しく使い分けることが重要です。

### curlとwgetの機能比較と使い分け基準

実務における使い分けの判断基準はシンプルです：

– curlを選ぶ場面: 「REST APIのテストを行いたい」「カスタムヘッダーや認証情報を細かく制御したい」「レスポンスをパイプで `jq` に渡して処理したい」場合。
– wgetを選ぶ場面: 「巨大なアーカイブファイルを単体でダウンロードしたい」「Webサイト全体をリンク階層ごとミラーリング保存したい」「回線切断時にバックグラウンドで自動再試行させたい」場合。

## よく使う主要オプション一覧早見表

curlには数百におよぶオプションが用意されていますが、実務で頻繁に使うものは限られています。目的別にカテゴリ分けした早見表で整理しました。

### リクエスト・データ送信オプション（-X, -d, -H, -F）

Web APIの呼び出しやフォーム送信、ヘッダー付与などで必須となるオプション群です。

### 出力・表示制御オプション（-o, -O, -s, -S, -v, -I, -i）

レスポンスの保存方法や、ターミナルへのログ・進捗表示を切り替えるオプション群です。

| オプション | ロングオプション | 機能・説明 | 実用コマンド例 |
| :— | :— | :— | :— |
| `-o` | `–output ` | レスポンスを指定したファイル名で保存 | `curl -o my_backup.tar.gz https://example.com/file` |
| `-O` | `–remote-name` | URL末尾のファイル名をそのまま使ってローカルに保存 | `curl -O https://example.com/archive.zip` |
| `-s` | `–silent` | プログレスメーター（進捗バー）やエラーメッセージを非表示 | `curl -s https://example.com` |
| `-S` | `–show-error` | `-s` と併用し、エラー発生時のみ標準エラー出力に詳細を表示 | `curl -sS https://example.com` |
| `-v` | `–verbose` | 送受信ヘッダーやTLSハンドシェイクを含む詳細デバッグログを出力 | `curl -v https://example.com` |
| `-I` | `–head` | HTTPレスポンスヘッダーのみを取得（HEADリクエスト） | `curl -I https://example.com` |
| `-i` | `–include` | レスポンスヘッダーと本文（ボディ）の両方をまとめて画面に表示 | `curl -i https://example.com` |
| `-w` | `–write-out ` | 通信完了時にステータスコードや応答時間などをフォーマット出力 | `curl -s -o /dev/null -w “%{http_code}\n” https://example.com` |

### ネットワーク・通信制御オプション（-L, -u, -k, -m, –retry, –fail）

リダイレクト処理、タイムアウト、認証、SSL検証、リトライなど、ネットワーク接続の信頼性を高めるオプション群です。

## 実務で役立つ頻出ユースケースと活用レシピ

ここからは、インフラ運用やWeb開発の現場で実際によく使われる具体的なユースケースを4つのレシピに分けて解説します。

### REST APIの検証（JSON送受信・Bearerトークン認証）

現代のWeb開発で最も多いのが、OAuth2やJWTなどのBearerトークンを用いた認証付きAPIへのリクエストです。レスポンスを `jq` コマンドで整形・パースすることで、目的のデータを素早く取り出せます。

“`bash
# Bearerトークンをヘッダーに含めてJSONをPOST送信
curl -s -X POST https://api.example.com/v1/deployments \
-H “Authorization: Bearer my_api_secret_token_xyz” \
-H “Content-Type: application/json” \
-d ‘{
“environment”: “production”,
“branch”: “main”,
“notify”: true
}’ | jq .

# ファイルに保存したJSONを送信し、返却されたIDのみを抽出
curl -s -X POST https://api.example.com/v1/tasks \
-H “Authorization: Bearer my_api_secret_token_xyz” \
-H “Content-Type: application/json” \
-d @task_payload.json | jq -r ‘.id’
“`

`-s`（サイレント）を併用することで、余計なプログレスメーターが混入せず、純粋なJSON文字列だけをパイプラインで安全に `jq` へ引き渡せます。

### HTTPステータスコード・応答時間の取得（-w “%{http_code}\n”）

システムの死活監視やデプロイ後のヘルスチェック、Webサーバーの応答パフォーマンス計測では、`-w`（`–write-out`）と `-o /dev/null` の組み合わせが強力です。

“`bash
# HTTPステータスコードのみを取得（例: 200）
STATUS=$(curl -s -o /dev/null -w “%{http_code}\n” https://example.com)
echo “HTTP Status Code: ${STATUS}”

# DNS名前解決、TCP接続、TLSハンドシェイク、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
“`

本文出力を `/dev/null` に破棄することで、大容量ページであってもネットワーク負荷や画面表示を汚すことなく、純粋な接続メトリクスのみを高速に抽出できます。

### ファイルのダウンロードとレジューム再開（-O, -C -）

数GBにおよぶ巨大なOSイメージやバックアップアーカイブをダウンロードする際、ネットワークの瞬断で最初からやり直しになるのを防ぐには `-C -`（レジューム機能）を活用します。

“`bash
# URL末尾のファイル名で保存し、中断時は自動的に再開（-C -）
curl -C – -O https://example.com/backups/database_dump.tar.gz

# 社内ネットワーク帯域を圧迫しないよう転送速度を2MB/sに制限（–limit-rate）
curl –limit-rate 2M -C – -O https://example.com/backups/database_dump.tar.gz
“`

`-C -` を指定すると、curlがローカルに既に存在するファイルサイズを自動測定し、サーバーに対して `Range: bytes=XXXX-` リクエストヘッダーを送信して続きのバイト列から受信を再開します。

### シェルスクリプトでの安全な活用（-sSf によるエラー即検知とset -e連携）

Bashスクリプトの中でcurlを呼ぶ場合、最大の落とし穴となるのが「HTTP 404や500エラーが返ってきても、curlコマンド自体は終了ステータス0（成功）で抜けてしまう」という仕様です。

これを防ぎ、スクリプトの `set -e` と連動させて安全に異常終了させるための鉄板オプションが `-sSf`（または `-sSfL`） です。

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

HEALTH_CHECK_URL=”https://api.example.com/healthz”
MAX_WAIT_SEC=10
RETRY_COUNT=3

echo “ヘルスチェック通信を開始します: ${HEALTH_CHECK_URL}”

# -s: 進捗バーを抑制
# -S: エラー時のみエラー詳細を標準エラー出力へ表示
# -f: HTTP 4xx/5xx レスポンスで即座に非0の終了ステータスを返す
# -L: リダイレクトを自動追従
# -m: 全体タイムアウト秒数
if response=$(curl -sSfL -m “${MAX_WAIT_SEC}” –retry “${RETRY_COUNT}” “${HEALTH_CHECK_URL}”); then
echo “疎通成功: APIは正常に稼働しています”
echo “${response}”
else
EXIT_CODE=$?
echo “エラー: APIへの接続またはHTTPレスポンスに失敗しました (Exit Code: ${EXIT_CODE})” >&2
exit 1
fi
“`

`-f`（`–fail`）を付与することで、Webサーバーからエラー画面のHTML（404 Not Foundや500 Internal Server Error）が返ってきた場合に本文を出力せず、終了ステータス `22` などの非0で即座に失敗判定を行えます。

## よくあるエラーと落とし穴・トラブルシューティング

curlの実行時によく遭遇する代表的なエラーコードと、原因の切り分け手順・対策を解説します。

### curl: (6) Could not resolve host / (7) Failed to connect の原因と対策

名前解決や接続確立時のトラブルで最も頻出するエラーです。

– curl: (6) Could not resolve host:
– 原因: 指定したドメイン名のDNS名前解決に失敗しています。URLのタイポ、またはクライアント端末のDNSサーバー（`/etc/resolv.conf`）の設定不備が考えられます。
– 対策: `nslookup example.com` や `dig example.com` でドメインがIPアドレスに変換できるか確認してください。ローカル環境の場合は `/etc/hosts` の設定も見直します。
– curl: (7) Failed to connect to host port XXX: Connection refused:
– 原因: サーバーのIPアドレスには到達できたものの、指定したポート（80や443など）でWebサーバープロセスが待ち受けていない、またはファイアウォール（iptablesやUFW、クラウドのセキュリティグループ）で遮断されています。
– 対策: Webサーバー（nginxやApache等）が起動しているか `systemctl status nginx` で確認し、ファイアウォール設定で当該ポートが解放されているかを点検してください。

### curl: (28) Operation timed out（タイムアウト防止の -m / –connect-timeout）

リクエスト送信後、応答が返ってこないまま指定時間が経過した場合に発生します（終了コード28）。

“`bash
# 通信全体のタイムアウトを10秒に設定（-m）
curl -m 10 https://api.example.com/slow-endpoint

# TCP接続確立までのタイムアウトを3秒に設定（–connect-timeout）
curl –connect-timeout 3 -m 10 https://api.example.com
“`

デフォルトのcurlはタイムアウトが無期限に設定されているため、リモートサーバーが高負荷でハングアップしていると、実行プロセスが永久にブロックされてしまいます。自動化スクリプト内では、必ず `-m`（`–max-time`）を指定してタイムアウト上限を明示的に設けてください。

### curl: (60) SSL certificate problem（自己署名証明書と -k の危険性）

HTTPS通信時に、リモートサーバーのSSL/TLS証明書が信頼できない場合に発生します（終了コード60）。社内開発サーバーのオレオレ証明書（自己署名証明書）や証明書の有効期限切れが主な原因です。

“`bash
# 検証環境限定: SSL証明書の検証をスキップ（-k / –insecure）
curl -k https://dev-internal.local/api
“`

注意：本番環境での `-k` 乱用は厳禁です。 `-k` を常用すると、通信経路で第三者が通信内容を盗聴・改ざんする「中間者攻撃（Man-in-the-Middle）」を検知できなくなります。本番環境でエラーが発生した場合は、OS側の認証局リスト（`sudo apt install ca-certificates` 等）を最新化するか、サーバー側に正規の証明書（Let’s Encrypt等）を正しく配備してください。

### Windows環境（PowerShell / cmd）でのクォート消失と curl.exe の明記

Windows端末でcurlを実行する際、多くのエンジニアが直面する特有の落とし穴が2点あります。

1. PowerShell 5.1でのエイリアス問題:
Windows標準のPowerShell 5.1環境では、`curl` コマンドが .NETの `Invoke-WebRequest` の短縮エイリアスとして登録されています。そのため、Linuxのcurlオプション（`-I` や `-s` など）を渡すと文法エラーになります。
対策: 拡張子を明示して curl.exe と実行するか、PowerShell 7（pwsh）を使用してください。

“`powershell
# Windows PowerShellでは curl.exe を明示実行
curl.exe -I https://example.com
“`

2. JSON送信時のダブルクォート消失問題:
Windowsのコマンドプロンプト（cmd.exe）やPowerShellでは、シングルクォート `'{“key”: “val”}’` でJSONを囲むと、内部のダブルクォートが展開時に消失してJSONパースエラーになります。
対策: 外側をダブルクォートで囲み、内部のダブルクォートをバックスラッシュ（またはバッククォート）でエスケープします。

“`powershell
# PowerShellでの安全なJSON送信（エスケープ）
curl.exe -X POST https://api.example.com -H “Content-Type: application/json” -d “{\”key\”:\”val\”}”
“`

## まとめ

`curl` コマンドは、Linuxのターミナル操作やシェルスクリプト開発において欠かせない強力なデータ転送ツールです。

– 基本の3大操作: `curl URL`（GET取得）、`curl -X POST -H … -d …`（JSON送信）、`curl -I`（ヘッダー確認）をまずはマスターしましょう。
– 主要オプションの活用: ファイル保存には `-o` / `-O`、デバッグには `-v`、メトリクス測定には `-w “%{http_code}\n”` が活躍します。
– スクリプト自動化の安全策: 実務スクリプトでは -sSfL -m 10 の組み合わせを徹底し、異常終了を確実に検知できる設計にしましょう。

手作業でのAPI検証はもちろん、サーバー運用の自動化スクリプトにも積極的に取り入れてみてください。