curl

概要

curl は URL を使ってデータを送受信する CLI ツールで、HTTP/HTTPS、FTP、SMTP などのプロトコルをサポートします。本チートシートは HTTP API の動作確認やスクリプト利用で頻出するオプションを、公式 man ページに沿って整理したものです。

基本

メソッドとボディ

ヘッダ

認証

Cookie

プロキシ・TLS

HTTP/2・HTTP/3

ファイルアップロード

ダウンロード

実用スニペット集

1. JSON を POST

curl -X POST https://api.example.com/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada","age":30}'

2. 認証付き API 呼び出し

curl -H "Authorization: Bearer $TOKEN" \
     -H 'Accept: application/json' \
     https://api.example.com/me

3. レスポンスを jq で整形

curl -s https://api.github.com/repos/curl/curl | jq '.stargazers_count'

4. ステータスコードだけ取得

curl -o /dev/null -s -w '%{http_code}\n' https://example.com

5. 詳細タイミング計測

curl -o /dev/null -s -w \
  'dns=%{time_namelookup} connect=%{time_connect} ttfb=%{time_starttransfer} total=%{time_total}\n' \
  https://example.com

6. リダイレクト先の URL を取得

curl -o /dev/null -s -w '%{url_effective}\n' -L https://example.com

7. フォームログイン → セッション維持

curl -c jar.txt -d 'user=ada&pass=secret' https://example.com/login
curl -b jar.txt https://example.com/dashboard

8. GraphQL リクエスト

curl -X POST https://api.example.com/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ me { id name } }"}'

9. 大きなファイルをアップロード（進捗表示）

curl -# -T big.bin https://example.com/upload/

10. ヘッダとボディを別ファイルへ

curl -D head.txt -o body.html https://example.com

11. Bearer トークンを環境変数から

TOKEN=$(cat ~/.token)
curl -H "Authorization: Bearer $TOKEN" https://api.example.com/secure

12. curl 設定ファイルを使う

# ~/.curlrc
user-agent = "my-agent/1.0"
silent
location

13. 複数 URL 一括取得

curl -O 'https://example.com/file[1-5].txt'
curl -O 'https://example.com/{a,b,c}/index.html'

14. POST で JSON ファイルを送る

curl -X POST -H 'Content-Type: application/json' \
  --data @payload.json https://api.example.com/import

15. 実行するだけで失敗判定する CI 用

curl -fsSL https://example.com/script.sh | bash

書式変数（-w）早見表

オプション早見表

トラブルシューティング

Tips

• 秘密情報を -u user:pass で渡すとプロセス一覧に見える。環境変数・.netrc を活用する。
• ~/.netrc に machine host login u password p を書くと自動で認証される。
• curl -v の出力で > は送信行、< は受信行、* はメタ情報。
• JSON 系では Content-Type と Accept を明示すると再現性が高い。
• スクリプト内では必ず -fsSL のいずれかを状況に応じて付ける。
• --next を使うと 1 コマンドで複数リクエストを連続実行できる。

.netrc の活用

~/.netrc に認証情報を書いておくと、curl は該当ホストに対して自動で認証を付けます（.netrc 形式の仕様: https://everything.curl.dev/usingcurl/netrc）。

machine api.example.com
login alice
password s3cret

chmod 600 ~/.netrc
curl --netrc https://api.example.com/me

複数リクエストを 1 コマンドで（—next）

curl https://api.example.com/a \
     --next -X POST -d '{"x":1}' https://api.example.com/b \
     --next -H "Authorization: Bearer $T" https://api.example.com/c

ファイル名テンプレート（-o）

curl 'https://example.com/img/[001-010].png' -o 'img_#1.png'
curl 'https://example.com/{en,ja,fr}/index.html' -o '#1.html'

#1, #2 は URL 内のブレース/ブラケット展開順に対応します。

再利用可能なシェル関数例

# JSON POST ヘルパ
jpost() {
  local url="$1"; shift
  curl -fsS -X POST "$url" \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $API_TOKEN" \
    -d "$@"
}

# ダウンロードのリトライ
dlretry() {
  curl -fL --retry 5 --retry-delay 2 --retry-max-time 60 \
       --continue-at - -O "$1"
}

実運用での比較: curl と他ツール

Content-Type とボディの組み合わせ

プロトコル別の基本例

FTP

curl ftp://ftp.example.com/ -u user:pass
curl -T upload.bin ftp://ftp.example.com/dir/ -u user:pass

SFTP / SCP

curl -u user: --key ~/.ssh/id_rsa sftp://host/path/file
curl -u user: -T local.txt scp://host/remote/path/

SMTP（メール送信）

curl --ssl-reqd smtp://smtp.example.com:587 \
     --mail-from from@example.com \
     --mail-rcpt to@example.com \
     --upload-file mail.txt \
     -u from@example.com:pass

WebSocket（7.86+）

curl --include --no-buffer \
  --header "Connection: Upgrade" \
  --header "Upgrade: websocket" \
  --header "Sec-WebSocket-Key: $(openssl rand -base64 16)" \
  --header "Sec-WebSocket-Version: 13" \
  https://example.com/ws

HTTPS 証明書の調査

# サーバ証明書情報を表示
curl -vI https://example.com 2>&1 | grep -E '^(\*|<)'

# 特定の CA バンドルで検証
curl --cacert /path/to/ca.pem https://internal.example

# 証明書を保存
echo | openssl s_client -connect example.com:443 -servername example.com \
  | openssl x509 > server.pem

デバッグのコツ

• -v で始めて、--trace-ascii debug.txt で詳細を取る。
• -w '\nHTTP %{http_code}\n' を末尾に付けてステータスを確実に出す。
• 再現性のあるコマンドを --libcurl out.c で C コードとして出力できる。
• ブラウザの「コピー as cURL」で得たコマンドをそのまま実行・修正できる。
• CURL_HOME や --config file で設定を切り替えると環境ごとの差異を吸収しやすい。

環境変数

よくある書式変数の組合せ

# API レイテンシ計測
curl -o /dev/null -s \
  -w 'code=%{http_code} ttfb=%{time_starttransfer}s total=%{time_total}s\n' \
  https://api.example.com/health

# リクエスト・レスポンスのサイズ
curl -o /dev/null -s \
  -w 'upload=%{size_upload} download=%{size_download}\n' \
  -X POST -d @body.json https://api.example.com/ingest

参考リソース

• curl 公式 man ページ
• curl Documentation
• Everything curl (書籍)
• MDN: HTTP overview