32blogby StudioMitsu

curlコマンド完全ガイド:API操作からデバッグまで

curlの基本からAPI呼び出し・ヘッダー操作・認証・ファイル転送・スクリプト活用まで実例付きで解説。wgetとの使い分けも。

12 min read
目次

「APIのレスポンスをターミナルで確認したい」「サーバーがリダイレクトしてるか調べたい」「CIスクリプトからWebhookを叩きたい」

こういう場面で真っ先に使うのが curl だ。HTTP通信に関わるほぼすべての操作をコマンド一発でこなせる。Linux・macOS にはほぼ確実にプリインストールされているし、Windows でも WSL や Git Bash で使える。

今回は curl の基本から、API操作・デバッグ・スクリプト活用まで、実行可能なコマンド例を交えて解説する。

curl とは

curl は URL を指定してデータを送受信するコマンドラインツールだ。正式名称は「Client URL」。HTTP / HTTPS / FTP / SFTP / SCP など、20以上のプロトコルに対応している。

主な特徴:

  • HTTP通信の万能ツール:GET / POST / PUT / DELETE などあらゆるメソッドを使える
  • レスポンス制御が柔軟:ヘッダーだけ取得、ボディだけ取得、レスポンスタイム計測など自在
  • libcurl:C言語のライブラリとしても提供されており、Python・PHP・Ruby など多くの言語から利用できる
  • クロスプラットフォーム:Linux / macOS / Windows のどれでも動く

wget との違い を一言で言うと、wget は「ファイルダウンロード特化」、curl は「HTTP通信全般の万能ツール」だ。再帰ダウンロードやサイトミラーリングは wget の方が得意だが、API呼び出し・レスポンス操作・複雑なHTTPリクエストは curl の独壇場になる。

詳しい使い分けは wgetコマンド完全ガイド を参照してほしい。

基本的な使い方

インストール確認

まず curl が使えるか確認する。

bash
curl --version

WSL(Windows Subsystem for Linux)を使っている場合は Linux 版が利用できる。Git Bash にも curl が同梱されている。PowerShell の curlInvoke-WebRequest のエイリアスなので注意。

bash
# WSL(Ubuntu の場合)
sudo apt install curl

GETリクエスト

bash
curl https://example.com

指定した URL のレスポンスボディが標準出力に表示される。ファイルに保存したい場合:

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

# URLのファイル名で保存
curl -O https://example.com/file.zip

レスポンスヘッダーを確認

bash
# ヘッダーだけ表示(HEADリクエスト)
curl -I https://example.com

# ヘッダー + ボディ両方
curl -i https://example.com

詳細表示(デバッグ用)

bash
curl -v https://example.com

TLSハンドシェイク、リクエストヘッダー、レスポンスヘッダーがすべて表示される。通信トラブルの調査に欠かせない。

サイレントモード

bash
# 進捗バーやエラーメッセージを非表示
curl -s https://example.com

# 進捗バーを # で表示(大きなファイル向け)
curl -# -O https://example.com/file.zip

よく使うオプション一覧

オプション意味
-o FILE出力ファイル名を指定
-OURLのファイル名で保存
-I / --headヘッダーのみ取得(HEADリクエスト)
-iレスポンスヘッダーも一緒に出力
-v / --verbose詳細表示(TLS含む全通信)
-s / --silent出力を抑制
-L / --locationリダイレクト追従
-X METHODHTTPメソッドを指定(POST, PUT, DELETE 等)
-H "Header: Value"カスタムヘッダーを追加
-d "data"POSTデータを送信
-u user:passBasic認証
-k / --insecureSSL証明書の検証をスキップ
-c FILECookieをファイルに保存
-b FILECookieをファイルから送信
--limit-rate RATE速度制限(例: --limit-rate 1M
-w "format"レスポンス情報をカスタム表示
--connect-timeout SEC接続タイムアウト(秒)
-C -ダウンロードを途中から再開
-F "key=@file"フォームデータ送信(ファイルアップロード)

実践ユースケース

REST API の呼び出し(GET / POST / PUT / DELETE)

APIテストで最も使うパターンをまとめる。

JSON を POST する:

bash
curl -s -X POST \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}' \
  https://api.example.com/users

Bearer トークンで認証する:

bash
curl -s \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  https://api.example.com/me

PUT でリソースを更新する:

bash
curl -s -X PUT \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice Updated"}' \
  https://api.example.com/users/123

DELETE でリソースを削除する:

bash
curl -s -X DELETE \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  https://api.example.com/users/123

レスポンスを jq で整形する:

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

JSON API のレスポンスを見やすくするなら jqコマンド完全ガイド も参考にしてほしい。

ヘッダー・リダイレクトのデバッグ

TLSハンドシェイクを含む全通信を確認する:

bash
curl -v https://example.com 2>&1 | head -30

-v の出力は stderr に出るため、2>&1 でまとめてから head で必要な分だけ確認できる。

レスポンスタイムを計測する:

bash
curl -o /dev/null -s -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTLS: %{time_appconnect}s\nTotal: %{time_total}s\n" https://example.com

このコマンドは DNS 解決、TCP 接続、TLS ハンドシェイク、合計時間をそれぞれ表示する。パフォーマンスのボトルネック特定に便利だ。

リダイレクトチェーンを追跡する:

bash
curl -s -L -o /dev/null -w "Final URL: %{url_effective}\nRedirects: %{num_redirects}\n" https://example.com

ファイルアップロード

フォームデータとしてファイルを送信する:

bash
curl -F "file=@photo.jpg" https://api.example.com/upload

複数ファイルを同時にアップロードする:

bash
curl -F "file1=@document.pdf" \
     -F "file2=@image.png" \
     -F "description=Monthly report" \
     https://api.example.com/upload

MIME タイプを明示する:

bash
curl -F "file=@data.csv;type=text/csv" https://api.example.com/import

ログインが必要なサイトでセッションを維持する方法。

bash
# Step 1: ログインして Cookie を保存
curl -c cookies.txt \
  -d "username=admin&password=secret" \
  https://example.com/login

# Step 2: 保存した Cookie を使ってアクセス
curl -b cookies.txt https://example.com/dashboard

# Step 3: Cookie を送りつつ新しい Cookie も保存
curl -b cookies.txt -c cookies.txt https://example.com/profile

ダウンロード再開

大きなファイルのダウンロードが途中で切れた場合:

bash
# 最初のダウンロード(途中で Ctrl+C 等)
curl -O https://example.com/largefile.iso

# 途中から再開
curl -C - -O https://example.com/largefile.iso

-C -- は「現在のファイルサイズを自動検出して続きから」という意味だ。

スクリプト活用例

API ヘルスチェック

複数のエンドポイントのステータスコードを一括確認するスクリプト。

bash
#!/bin/bash

ENDPOINTS=(
  "https://api.example.com/health"
  "https://api.example.com/v2/status"
  "https://cdn.example.com/ping"
  "https://auth.example.com/health"
)

echo "=== API Health Check ==="
echo ""

FAILED=0

for URL in "${ENDPOINTS[@]}"; do
  STATUS=$(curl -s -o /dev/null -w "%{http_code}" --connect-timeout 5 --max-time 10 "$URL")

  if [ "$STATUS" -ge 200 ] && [ "$STATUS" -lt 300 ]; then
    echo "[OK]   $STATUS  $URL"
  else
    echo "[FAIL] $STATUS  $URL"
    FAILED=$((FAILED + 1))
  fi
done

echo ""
echo "Results: $((${#ENDPOINTS[@]} - FAILED))/${#ENDPOINTS[@]} passed"

if [ "$FAILED" -gt 0 ]; then
  exit 1
fi

ファイル一括ダウンロード(リトライ付き)

bash
#!/bin/bash

URLS=(
  "https://example.com/data/january.csv"
  "https://example.com/data/february.csv"
  "https://example.com/data/march.csv"
)

DEST_DIR="./downloads"
MAX_RETRIES=3

mkdir -p "$DEST_DIR"

for URL in "${URLS[@]}"; do
  FILENAME=$(basename "$URL")
  ATTEMPT=1

  while [ "$ATTEMPT" -le "$MAX_RETRIES" ]; do
    echo "Downloading $FILENAME (attempt $ATTEMPT/$MAX_RETRIES)..."

    if curl -s -f -L -o "${DEST_DIR}/${FILENAME}" --connect-timeout 10 --max-time 120 "$URL"; then
      echo "  OK: $FILENAME"
      break
    else
      echo "  FAILED: $FILENAME"
      ATTEMPT=$((ATTEMPT + 1))

      if [ "$ATTEMPT" -le "$MAX_RETRIES" ]; then
        echo "  Retrying in 5 seconds..."
        sleep 5
      fi
    fi
  done

  if [ "$ATTEMPT" -gt "$MAX_RETRIES" ]; then
    echo "  GAVE UP: $FILENAME after $MAX_RETRIES attempts"
  fi
done

echo "Done."

セキュリティの注意点

curl 8.18.0 のセキュリティ修正

curl 8.18.0(2026年1月7日リリース)では6件のセキュリティ修正が含まれ、そのうち3件は AI ツールによって発見された。これは curl プロジェクトとして初めてAIツールによるバグ発見が公式に認められたケースだ。

一方、curl のバグバウンティプログラムは2026年1月末に終了した。AI生成レポートの大量投稿により、品質の低い報告がトリアージのリソースを圧迫したことが原因だ。

-k は本番で使わない

bash
# テスト環境でのみ使用すること
curl -k https://self-signed.example.com/api

-k--insecure)は SSL 証明書の検証をスキップする。自己署名証明書のテスト環境で一時的に使う分にはいいが、本番環境やスクリプトへの常用は中間者攻撃のリスクを生む。

パスワードをコマンドに書かない

bash
# 悪い例:シェル履歴に残る
curl -u admin:P@ssw0rd https://api.example.com/admin

# 良い例:.netrc を使う
echo "machine api.example.com login admin password P@ssw0rd" > ~/.netrc
chmod 600 ~/.netrc
curl -n https://api.example.com/admin

.netrc ファイルのパーミッションは必ず 600 にすること。他のユーザーから読めない状態にしておく。

環境変数を使う方法もある:

bash
curl -u "admin:${API_PASSWORD}" https://api.example.com/admin

まとめ

curl は HTTP 通信をコマンドラインから自在に操れる万能ツールだ。APIテストからデバッグ、ファイル転送、スクリプト自動化まで幅広くカバーする。

今日から使えるポイントをおさらい:

  • 基本は curl URL。ファイル保存は -o-O
  • API テストは -X POST -H "Content-Type: application/json" -d '{...}'
  • デバッグは -v で全通信を確認、-w でレスポンスタイム計測
  • スクリプトでは -s -f を付けてサイレント + エラー検出
  • 認証情報はコマンドに書かず .netrc か環境変数を使う

ファイルダウンロードが中心なら wget の方がシンプルだ。API 呼び出しや HTTP デバッグが目的なら curl 一択。両方を場面で使い分けるのがベストだ。

他の CLI ツールとの組み合わせは CLIツール完全マップ にまとめている。