curlコマンドの使い方入門｜GET・POST・ヘッダー確認まで

Webサイトが正常に動いているか確かめたい、APIにデータを送ってみたい。そんなときに役立つのがcurl（カール）コマンドだ。ブラウザを開かずに、ターミナルからWebサーバーと通信できる。

この記事では、最初にcurlの仕組みを理解し、GET・POST・レスポンスの確認からファイルの保存まで、コマンドを一つずつ試していく。

対象はUbuntu 24.04やWSL上のUbuntuなど、Bashを使うLinux環境。例はHTTP・HTTPSの基本的な使い方で、特殊なサーバー設定は必要ない。公開のテストサービスを使う例もあるが、実行環境やサービスの状況によって結果は変わる。この記事のコマンドを実行して動作確認した記録ではなく、公式ドキュメントに基づく解説だ。

curlって何？ ブラウザとの違い

curlはURLを指定してデータを送受信できるコマンドラインツール。特にWeb開発では、HTTPリクエストを送り、返ってきたHTTPレスポンスを確かめるのに使う。

ブラウザでページを開くときも、内部では似た流れで通信している。

自分のPC（クライアント）           Webサーバー
           |                           |
           | -- HTTPリクエスト ------> |
           |    「このページを見たい」    |
           |                           |
           | <----- HTTPレスポンス ---- |
           |    「結果は200、本文はこれ」 |
           |                           |

ブラウザは受け取ったHTMLを画面として表示する。一方、curlは基本的に受け取ったデータをターミナルにそのまま表示する。画像やデザインを表示するためのツールではなく、通信内容を確かめるためのツールだ。

覚えておきたい言葉は三つある。

1. curlが使えるか確認する

まずターミナルで次を実行する。

curl --version

バージョンなどが表示されれば使用できる。curl: command not foundと出た場合は、Ubuntuなら次のコマンドでインストールする。

sudo apt update
sudo apt install curl

以降の例は、Bashで実行する前提だ。

2. GETリクエストでWebページを取得する

最初はURLを指定するだけでよい。

curl https://example.com

GETは「データを取得する」ためのHTTPメソッド。curlでは、オプションを付けずにHTTP・HTTPSのURLを指定すると、通常はGETリクエストになる。

成功すると、HTMLなどのレスポンス本文が表示される。<h1>や<p>などの文字列が見えても異常ではない。ブラウザのようにHTMLを画面として描画せず、内容をそのまま出しているからだ。

APIのJSONを見てみたい場合は、公開の練習用サービスhttpbinを使える。

curl https://httpbin.org/get

httpbinは、受け取ったHTTPリクエストの内容を返すテストサービスだ。JSONの中にurlやheadersなどが含まれる。公開サービスのため、使えない時間帯もあり得る。

3. -Iと-iでHTTPヘッダーを確認する

HTTPレスポンスには、本文のほかにヘッダーがある。ヘッダーは、結果の種類やデータの形式などを伝える情報だ。

curl -I https://example.com

-IはHEADリクエストを送り、レスポンスヘッダーを表示する。例えば次のような情報を確認できる（内容は一例）。

HTTP/2 200
content-type: text/html
cache-control: max-age=3600

HTTP/2 200の200は成功を表す。content-type: text/htmlは、データの種類がHTMLであることを表している。

一方、GETで取得した本文とヘッダーを両方見たいなら-iを使う。

curl -i https://example.com

注意したいのは、-Iと-iは違うこと。-IはHEADという別のメソッドを使うため、サーバーによってはGETは成功してもHEADは拒否される。GETの実際の結果を調べるときは-iが便利だ。

4. HTTPステータスコードだけを表示する

サイトの監視やAPIの動作確認では、HTML全文よりも「成功したか」を知りたいことがある。

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

成功したときの表示例：

200

オプションを分解すると次のようになる。

よく見る番号は以下のとおり。

重要：通常のcurlはHTTP 404や500を受け取っても、通信自体ができていれば終了コード0になることがある。 HTTPの失敗をシェルスクリプトで検出したいときは、--fail-with-body（curl 7.76.0以降）などを検討する。

5. URLに条件を付けてGETする

URLの末尾に付く?name=Taro&age=25のような部分をクエリパラメータという。検索条件などを渡すときによく使う。

curl "https://httpbin.org/get?name=Taro&age=25"

テストサービスから返るJSONのargsにnameとageが含まれる。

ここではURLを"..."で囲む。Bashでは&に特別な意味があるため、囲まずに書くと意図しない動作になるからだ。

6. POSTリクエストでJSONを送る

POSTは、サーバーへデータを送信するときによく使うメソッド。たとえばユーザー登録APIなどで使われる。

curl https://httpbin.org/post \
  -H "Content-Type: application/json" \
  -d '{"name":"Taro","age":25}'

各部分の意味は次のとおり。

• -H：HTTPリクエストヘッダーを追加する。ここでは「送信データはJSON」と知らせる。
• -d：リクエスト本文として送るデータを指定する。
• \：Bashで長いコマンドを次の行に続ける記号。改行せず一行で書いてもよい。

-dを使うと通常はPOSTになるので、-X POSTを書く必要はない。httpbin.org/postは受け取った内容をJSONで返すため、jsonという項目にnameやageが含まれているか確認できる。

curl 7.82.0以降なら、JSON送信を次のように短く書くこともできる。

curl --json '{"name":"Taro","age":25}' https://httpbin.org/post

--jsonはJSON用のヘッダーを付けて本文を送る便利な指定だ。ただし、curl自身がJSONの書き方の正しさを検証するわけではない。

7. PUTとDELETEも試してみる

Web APIではGET・POST以外にも、次のようなメソッドがよく使われる。

-Xを使うとメソッドを指定できる。例としてPUTを送る。

curl -X PUT https://httpbin.org/put \
  -H "Content-Type: application/json" \
  -d '{"name":"Jiro"}'

DELETEの例：

curl -X DELETE https://httpbin.org/delete

これらは練習用サービスへのリクエストなので、実際の会員情報などを変更・削除するものではない。自分のAPIに対してPUTやDELETEを使う際は、本当にデータが変更される可能性があるため対象URLを確認する。

8. リダイレクト先までアクセスする

Webサイトを開いたとき、別のURLへ案内されることがある。これをリダイレクトという。

curl -L https://example.com

-Lは、サーバーからリダイレクトを指示された場合に移動先へアクセスするオプション。curlは標準ではHTTPリダイレクトを自動追跡しない。

9. 取得したデータをファイルに保存する

画面に表示する代わりに、HTMLをファイルへ書き込める。

curl -L -o example.html https://example.com

-o example.htmlは「example.htmlという名前で保存する」という指定だ。保存したら、次でファイルを確認できる。

ls -l example.html

ダウンロードURLの末尾の名前で保存したいときは-Oを使う。

curl -LO https://example.com/sample.zip

最後のURLはファイル保存の書き方を示す例で、sample.zipが実在することを意味しない。実際にダウンロードするときは、有効な配布URLに置き換える。

10. -vで通信の流れを詳しく見る

「なぜAPIが動かないのか」を調べたいときは-vが役立つ。

curl -v https://example.com

詳細表示では、行頭の記号がおおむね次の意味を持つ。

例えば> GET / HTTP/2は「/というパスへGETを送信した」という意味だ。< HTTP/2 200ならサーバーから成功レスポンスが返っている。

注意：認証トークンやCookieなど、秘密にすべき情報が出力される場合がある。 -vの結果をSNSやIssueに貼る前には必ず内容を確認する。

11. よくあるエラーの見方

HTTPSの証明書エラーを-kで回避する例を見かけるが、-kはTLS証明書の検証を無効にする。安全性が落ちるため、まず証明書や接続先の設定を直す。知らないスクリプトをcurlで取得して、そのままシェルで実行することも避けたい。

まずはこの4つから覚える

最初からすべてのオプションを暗記する必要はない。次の四つを使えるようになると、WebサイトやAPIの簡単な確認ができる。

# GETして本文を表示する
curl https://example.com

# HTTPヘッダーと本文を確認する
curl -i https://example.com

# HTTPステータスコードだけを確認する
curl -sS -o /dev/null -w '%{http_code}\n' https://example.com

# JSONをPOSTする
curl --json '{"message":"hello"}' https://httpbin.org/post

Laravelで作ったAPIの動作確認にも応用できる。自分の開発環境ならURLをhttp://127.0.0.1:8000/api/...など、実際のAPIルートに置き換えて試してみよう。

参考資料

• curl公式チュートリアル
• curl公式マニュアル（オプション一覧）
• Everything curl：HTTPの基本
• Everything curl：JSONをPOSTする
• httpbin：HTTPリクエストを試せるサービス