5 min to read

Understanding and Using Curl - A Comprehensive Guide

A detailed guide to using Curl for HTTP requests and API testing

Featured image

Image Reference link


Overview

Today, we’ll explore Curl (Client URL), a powerful command-line tool for transferring data using various protocols.

Before diving deep into Curl, it’s recommended to understand HTTP methods, which you can find in my previous post: HTTP Methods and Status Codes.


What is Curl?

Curl is a command-line tool for transferring data using various protocols including HTTP, HTTPS, FTP, and more. It’s widely used for:


Common Curl Options

Option Description
-X, --request Specifies a custom request method
-H, --header Sends custom HTTP headers
-d, --data Sends data in POST requests
-I, --head Fetches only headers
-v, --verbose Shows detailed output
-o, --output Saves output to a file
-O, --remote-name Saves with remote filename
-L, --location Follows redirects
-k, --insecure Allows insecure SSL connections
-s, --silent Suppresses progress output


Basic Usage Examples

1. Simple GET Request

curl https://www.example.com

2. POST Request with Data

curl -X POST -d "param1=value1&param2=value2" https://www.example.com

3. JSON POST Request

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"key":"value"}' \
     https://www.example.com

4. Saving Output to File

# Save with custom name
curl -o example.html https://www.example.com

# Save with original filename
curl -O https://www.example.com/file.zip

5. Following Redirects

curl -L https://www.example.com

6. Verbose Output

curl -v https://www.example.com


🔍 Advanced Usage

1. GitHub API Example

curl -s -X POST \
     -H "Authorization: token $GITHUB_TOKEN" \
     -H "Accept: application/vnd.github+json" \
     https://api.github.com/repos/owner/repo/pulls \
     -d '{"title":"PR Title","head":"branch","base":"main"}'

2. Ignore SSL Certificate Validation

curl -k https://self-signed.badssl.com/


Fun and Useful Commands

Check Public IP

curl -s ipinfo.io/ip
# or
curl ifconfig.me

Check Weather

curl wttr.in/Seoul

Weather report: Seoul

      \   /     Sunny
       .-.      +2(-3) °C      
    ― (   ) ―   ↘ 22 km/h      
       `-’      10 km          
      /   \     0.0 mm         
                                                       ┌─────────────┐                                                       
┌──────────────────────────────┬───────────────────────┤  Thu 20 Feb ├───────────────────────┬──────────────────────────────┐
│            Morning           │             Noon      └──────┬──────┘     Evening           │             Night            │
├──────────────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────────────────────┤
│     \   /     Sunny          │     \   /     Sunny          │     \   /     Sunny          │     \   /     Clear          │
│      .-.      -4(-8) °C      │      .-.      -1(-6) °C      │      .-.      -1(-7) °C      │      .-.      -3(-9) °C      │
│   ― (   ) ―   → 11-14 km/h   │   ― (   ) ―   → 17-19 km/h   │   ― (   ) ―   ↘ 19-25 km/h   │   ― (   ) ―   ↘ 18-23 km/h   │
│      `-’      10 km          │      `-’      10 km          │      `-’      10 km          │      `-’      10 km          │
│     /   \     0.0 mm | 0%    │     /   \     0.0 mm | 0%    │     /   \     0.0 mm | 0%    │     /   \     0.0 mm | 0%    │
└──────────────────────────────┴──────────────────────────────┴──────────────────────────────┴──────────────────────────────┘
                                                       ┌─────────────┐                                                       
┌──────────────────────────────┬───────────────────────┤  Fri 21 Feb ├───────────────────────┬──────────────────────────────┐
│            Morning           │             Noon      └──────┬──────┘     Evening           │             Night            │
├──────────────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────────────────────┤
│     \   /     Sunny          │     \   /     Sunny          │     \   /     Sunny          │     \   /     Clear          │
│      .-.      -4(-10) °C     │      .-.      -2(-7) °C      │      .-.      -1(-7) °C      │      .-.      -3(-9) °C      │
│   ― (   ) ―   ↘ 14-17 km/h   │   ― (   ) ―   → 15-17 km/h   │   ― (   ) ―   → 18-23 km/h   │   ― (   ) ―   ↘ 17-22 km/h   │
│      `-’      10 km          │      `-’      10 km          │      `-’      10 km          │      `-’      10 km          │
│     /   \     0.0 mm | 0%    │     /   \     0.0 mm | 0%    │     /   \     0.0 mm | 0%    │     /   \     0.0 mm | 0%    │
└──────────────────────────────┴──────────────────────────────┴──────────────────────────────┴──────────────────────────────┘
                                                       ┌─────────────┐                                                       
┌──────────────────────────────┬───────────────────────┤  Sat 22 Feb ├───────────────────────┬──────────────────────────────┐
│            Morning           │             Noon      └──────┬──────┘     Evening           │             Night            │
├──────────────────────────────┼──────────────────────────────┼──────────────────────────────┼──────────────────────────────┤
│     \   /     Sunny          │     \   /     Sunny          │     \   /     Sunny          │     \   /     Clear          │
│      .-.      -5(-10) °C     │      .-.      -2(-7) °C      │      .-.      -1(-6) °C      │      .-.      -3(-9) °C      │
│   ― (   ) ―   → 15-19 km/h   │   ― (   ) ―   → 15-17 km/h   │   ― (   ) ―   → 17-23 km/h   │   ― (   ) ―   ↘ 18-23 km/h   │
│      `-’      10 km          │      `-’      10 km          │      `-’      10 km          │      `-’      10 km          │
│     /   \     0.0 mm | 0%    │     /   \     0.0 mm | 0%    │     /   \     0.0 mm | 0%    │     /   \     0.0 mm | 0%    │
└──────────────────────────────┴──────────────────────────────┴──────────────────────────────┴──────────────────────────────┘
Location: 서울특별시, 대한민국 [37.5666791,126.9782914]

Follow @igor_chubin for wttr.in updates


Best Practices

  1. Always use -s (silent) in scripts to suppress progress output
  2. Include proper headers for API requests
  3. Use -L when dealing with redirects
  4. Consider using -k only for testing purposes
  5. Add proper error handling in scripts


References