curl オプション一覧｜目的別の使い方と実行例まとめ

curl のオプションを使うと、出力先の指定、POSTデータの送信、認証、ヘッダー操作、通信のタイムアウトやリトライなど、リクエストの挙動を細かく制御できます。この記事では curl オプションを「出力・保存」「リクエスト・データ送信」「ヘッダー・認証」「通信制御」「アップロード・その他」の目的別に整理し、それぞれの使用例までまとめて解説します。基本構文やインストール方法、よくあるエラーの対処法もあわせて確認できます。

curl とは

curl（Client for URLs）は、コマンドラインから URL 相手に HTTP, HTTPS, FTP, SFTP, SCP などのプロトコルで通信するツールです。ブラウザのように画面表示は行わず、レスポンス本文やヘッダーをそのまま標準出力やファイルへ出力します。オプションを組み合わせることで、Web API の疎通確認、ファイルのダウンロード・アップロード、フォームデータの送信、シェルスクリプトや CI/CD パイプラインへの組み込みなど幅広い用途に対応できます。

macOS・多くの Linux ディストリビューションには標準でインストールされており、追加設定なしですぐに使い始められます。

基本構文（Syntax）

curl [オプション] [URL...]

オプションを省略すると、URL に対して GET リクエストを送信し、レスポンス本文を標準出力に表示します。オプションは複数同時に指定でき、curl -sL -o out.html https://example.com のように短縮形をまとめて書くことも可能です。

curl https://example.com

curl オプション一覧（目的別）

curl のオプションは数十種類ありますが、実務でよく使うものは「出力・保存」「リクエスト・データ送信」「ヘッダー・認証」「通信制御」「アップロード・その他」の5つに分類すると把握しやすくなります。

出力・保存に関するオプション

オプション	説明	使用例
-o FILE	出力先ファイルを指定	curl -o index.html https://example.com
-O	URL のファイル名で保存	curl -O https://example.com/file.zip
-I	HTTP ヘッダのみ取得	curl -I https://example.com
-D FILE	受信したヘッダーをファイルに保存	curl -D headers.txt https://example.com
-s	進行状況やエラーを非表示 (silent)	curl -s https://example.com
-v	詳細な通信ログを表示 (verbose)	curl -v https://example.com
-w FORMAT	完了後に指定した書式で情報を出力（ステータスコードや所要時間など）	curl -o /dev/null -s -w "%{http_code}\n" https://example.com

リクエスト・データ送信に関するオプション

オプション	説明	使用例
-X METHOD	HTTP メソッドを指定 (GET/POST/PUT/DELETE など)	curl -X POST https://example.com/api
-d DATA	POST データを送信	curl -d "user=alice&pass=1234" https://example.com/login
-F NAME=CONTENT	multipart/form-data でファイル等を送信	curl -F "file=@report.csv" https://example.com/upload
-G	-d のデータを URL クエリとして GET 送信	curl -G -d "q=curl" https://example.com/search
--data-urlencode DATA	パラメータを URL エンコードして送信	curl --data-urlencode "q=検索 語" -G https://example.com/search

ヘッダー・認証に関するオプション

オプション	説明	使用例
-H HEADER	追加の HTTP ヘッダを送信	curl -H "Authorization: Bearer TOKEN" https://example.com/api
-u USER:PASS	Basic認証でアクセス	curl -u alice:secret https://example.com
-A AGENT	User-Agent を偽装	curl -A "Mozilla/5.0" https://example.com
-b DATA	Cookie を送信	curl -b "session=abc123" https://example.com
-c FILE	受信した Cookie をファイルに保存	curl -c cookies.txt https://example.com/login
-e URL	Referer ヘッダーを指定	curl -e "https://example.com/" https://example.com/api

通信制御に関するオプション

オプション	説明	使用例
-L	リダイレクトを追跡	curl -L http://example.com
-C -	中断したダウンロードを再開	curl -C - -O https://example.com/file.zip
--limit-rate RATE	転送速度を制限	curl --limit-rate 100k https://example.com/file.zip
--max-time SEC	全体のタイムアウト秒数を指定	curl --max-time 5 https://example.com
--retry N	失敗時のリトライ回数を指定	curl --retry 3 https://example.com
-x [protocol://]host:port	プロキシ経由でアクセス	curl -x http://proxy.local:8080 https://example.com
-k	SSL 証明書の検証を無効化	curl -k https://selfsigned.local

アップロード・その他のオプション

オプション	説明	使用例
-T FILE	ファイルをアップロード（PUT）	curl -T local.txt https://example.com/upload/local.txt
-f	HTTPエラー時に本文を表示せず異常終了させる	curl -f https://example.com/notfound

-k は証明書検証をスキップするための一時的な確認用オプションです。本番運用や機密情報を扱う通信では使わないようにします。

よく使うオプションの組み合わせ例

ステータスコードだけを確認する

-o でレスポンス本文を捨て、-w でステータスコードのみ出力します。ヘルスチェックスクリプトなどでよく使う組み合わせです。

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

サーバのレスポンスヘッダを確認

curl -I https://example.com

出力例:

HTTP/1.1 200 OK
Date: Wed, 21 Aug 2024 12:34:56 GMT
Content-Type: text/html; charset=UTF-8

JSON API にリクエスト

curl -H "Content-Type: application/json" \
     -d '{"user":"alice","pass":"1234"}' \
     https://example.com/api/login

レスポンスの JSON を整形して読みたい場合は jq コマンドと組み合わせます。curl と jq を使った ChatGPT API 連携の実例はbashでChatGPT APIを使う方法で解説しています。

curl -s https://example.com/api/users/1 | jq .

Basic認証を使ってアクセス

curl -u alice:password https://example.com/secure

Cookie を送受信する

ログイン状態を維持したまま複数リクエストを送る場合は、-c で Cookie を保存し、次のリクエストで -b を使って読み込みます。

curl -c cookies.txt -d "user=alice&pass=1234" https://example.com/login
curl -b cookies.txt https://example.com/mypage

ファイルをアップロード

-T は主に FTP/SFTP や PUT に対応したエンドポイントへのアップロードに使い、-F はフォーム経由のファイルアップロード（multipart/form-data）に使います。

curl -T report.csv https://example.com/upload/report.csv
curl -F "file=@report.csv" https://example.com/upload

ダウンロードを途中から再開

curl -C - -O https://example.com/largefile.iso

タイムアウトとリトライを設定

不安定な回線やスクリプトからの自動実行では、応答が返らないまま処理が止まらないようタイムアウトとリトライを併用します。

curl --max-time 10 --retry 3 https://example.com/api/health

エラー例（存在しないページ）

curl は既定では 404 などの HTTP エラーが返っても、そのままレスポンス本文を表示して正常終了します。スクリプトで失敗を検知したい場合は -f（fail）を付けます。

curl -f https://example.com/notfound

出力例:

curl: (22) The requested URL returned error: 404

インストール・動作確認

まずはインストール状況とバージョンを確認します。

curl --version

コマンドが見つからない場合は、環境に応じて次の方法でインストールします。

環境	インストール方法
Ubuntu / Debian系	sudo apt install curl
RHEL / CentOS / Amazon Linux	sudo yum install curl（または dnf install curl）
macOS	標準搭載。最新版が必要な場合は brew install curl
Windows	Windows 10 (1803) 以降は標準搭載。無い場合は curl.se/windows から入手

macOS へのパッケージ導入手順は brew コマンドの記事もあわせて参照してください。

よくあるエラーと対処法

エラーメッセージ	主な原因	対処法
curl: command not found	curl 未インストール	「インストール・動作確認」の手順でインストールする
curl: (6) Could not resolve host	DNS が名前解決できない	URL のスペルミス確認、ping コマンドで名前解決自体を確認する
curl: (7) Failed to connect	ポートが閉じている・サーバがダウン	ファイアウォールやサーバの起動状態を確認する
curl: (28) Operation timed out	応答がなくタイムアウト	--max-time を延長するか、サーバ側の負荷・回線を確認する
curl: (35) SSL connect error	SSL/TLS のバージョン不一致・証明書不備	curl のバージョンを更新する。自己署名証明書の検証時のみ -k を使う
curl: (60) SSL certificate problem	証明書チェーンを検証できない	ルート証明書を最新化する。検証を無効化する -k は動作確認用途に限定する

curl と wget の違い

ファイルダウンロード用途では wget コマンドもよく使われます。用途に応じて使い分けます。

観点	curl	wget
対応プロトコル	HTTP/HTTPS/FTP/SFTP/SCP など多数	主に HTTP/HTTPS/FTP
得意な用途	API 通信・任意のHTTPメソッド・ヘッダー操作	ファイルの一括・再帰ダウンロード
出力先の既定	標準出力	ファイルに保存
再帰ダウンロード	非対応	-r で対応
ライブラリとしての利用	libcurl として多言語から利用可能	非対応

「API を叩く・レスポンスヘッダーを見る・POSTでデータを送る」なら curl、「サイトのファイル一式をまとめて取得する」なら wget が適しています。

よくある質問

curl のオプションはどれくらいありますか？

curl --help all で確認できるだけでも200種類近くあります。ただし実務でよく使うのは「curl オプション一覧（目的別）」で紹介した20個前後で、まずはこの範囲を覚えれば大半のケースに対応できます。

複数のオプションを同時に指定できますか？

指定できます。curl -sL -o out.html https://example.com のように、引数を取らない短縮オプションはまとめて書けます。-o や -H のように値を伴うオプションは個別に指定してください。

curl コマンドが使えない場合はどうすればいいですか？

curl --version を実行してインストール状況を確認します。見つからない場合は「インストール・動作確認」の章の手順でインストールしてください。

curl と wget はどちらを使うべきですか？

API通信やヘッダー確認、POST送信であれば curl、ファイルの一括・再帰ダウンロードであれば wget が向いています。詳細は「curl と wget の違い」を参照してください。

SSL証明書エラーが出るときはどうすればいいですか？

まずは curl 自体とルート証明書を最新化してください。自己署名証明書に対する動作確認に限り -k で検証を一時的にスキップできますが、本番通信には使用しないでください。

関連コマンド

• wget : ファイルダウンロード専用のコマンド
• jq : curl で取得した JSON レスポンスの整形・抽出
• scp / sftp : SSH 経由でファイルを転送
• ssh : リモートホストへの接続
• ftp : FTP プロトコルによるファイル転送
• ping : ネットワーク疎通確認

コマンド全体を俯瞰したい場合は linux コマンド一覧もあわせて確認してください。

備考

• curl は非常に多機能で、FTP/SFTP でのファイル操作、SMTP を使ったメール送信、WebSocket の簡易確認などにも利用可能です。
• SSL 証明書の検証はデフォルトで有効になっています。自己署名証明書を扱う場合は -k を付ける必要があります。
• API テストやスクリプト内でのデータ送受信において、curl は最も広く利用されるツールの一つです。

参考

• manページ: man7.org curl(1)
• 公式サイト: https://curl.se/