Library

cURL

Overview

cURL is "a command line tool for transferring data with URL syntax," developed as the world's most widely used HTTP client tool. Standing for "Client for URLs," it supports over 50 protocols including HTTP/HTTPS, FTP, SCP, and SFTP. Standard on Unix/Linux systems and available on Windows, macOS, and other platforms. With simple command-line operations, it enables all network operations including web API calls, file downloads, authentication, and proxy communication, establishing itself as an indispensable tool for developers' debugging, testing, and automation tasks.

Details

cURL 2025 edition boasts overwhelming stability and versatility through nearly 30 years of development experience. Based on the libcurl library, its highly functional command-line interface enables complex HTTP communication with single commands. Supports enterprise-level requirements including Basic/Digest/OAuth authentication, client certificates, proxy configuration, cookie management, redirect tracking, and resume functionality. Widely utilized in REST API development, CI/CD pipelines, system monitoring, and data collection, it maintains a solid position as the standard HTTP client tool especially in Docker environments and cloud-native development.

Key Features

• 50+ Protocol Support: Comprehensive coverage of HTTP/HTTPS, FTP, SCP, SFTP, LDAP, SMTP, and more
• Outstanding Portability: Broad platform support including Unix/Linux, Windows, macOS, and others
• Rich Authentication Features: Basic, Digest, NTLM, OAuth, Kerberos, and client certificate authentication
• Advanced HTTP Functionality: Custom headers, cookie management, redirect tracking, and resume capability
• Complete Proxy Support: HTTP/HTTPS/SOCKS4/SOCKS5 proxy and proxy authentication
• Detailed Debug Features: Complete communication content display and trace functionality

Pros and Cons

Pros

• Standard on Unix/Linux systems requiring no additional installation
• High learning efficiency and automation support through simple command-line operations
• Versatility and one-stop solution with 50+ protocol support
• Overwhelming stability and reliability through nearly 30 years of development
• Available as library (libcurl) for program integration
• Standard debugging tool in container environments like Docker and Kubernetes

Cons

• Specialized for single file transfers, unsuitable for large-scale site mirroring
• Limitations of not supporting JavaScript or browser-specific features
• High learning cost due to complex option combinations
• Limited to command-line operations with no GUI environment
• Requires other specialized tools for massive parallel connection processing
• Technical error messages difficult for beginners to understand

Reference Pages

• cURL Official Site
• cURL Documentation
• cURL GitHub Repository

Code Examples

Installation and Basic Verification

# Check system default cURL version
curl --version

# Installation on Ubuntu/Debian (usually standard)
sudo apt update && sudo apt install curl

# Installation on CentOS/RHEL/Fedora
sudo yum install curl    # CentOS 7 and earlier
sudo dnf install curl    # CentOS 8+, Fedora

# Installation on macOS (using Homebrew)
brew install curl

# Installation on Windows (standard or using WinGet)
winget install curl.curl

# Installation verification and detailed information
curl --version
curl --help

# Display list of supported protocols
curl --version | grep -i protocols

Basic HTTP Requests (GET/POST/PUT/DELETE)

# Basic GET request
curl https://api.example.com/users

# Display response headers as well
curl -i https://api.example.com/users
curl --include https://api.example.com/users

# Display headers only (HEAD request)
curl -I https://api.example.com/users
curl --head https://api.example.com/users

# Detailed communication content display (for debugging)
curl -v https://api.example.com/users
curl --verbose https://api.example.com/users

# More detailed trace information
curl --trace-ascii trace.log https://api.example.com/users

# Pretty print JSON response (combined with jq)
curl -s https://api.example.com/users | jq '.'

# GET request with query parameters
curl "https://api.example.com/users?page=1&limit=10&sort=created_at"

# When URL encoding is needed
curl -G -d "search=John Doe" -d "page=1" https://api.example.com/users

# POST request (sending JSON)
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "name": "John Doe",
    "email": "[email protected]",
    "age": 30
  }'

# POST request (sending form data)
curl -X POST https://api.example.com/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=testuser&password=secret123"

# POST request (reading from file)
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d @user_data.json

# PUT request (data update)
curl -X PUT https://api.example.com/users/123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "name": "Jane Doe",
    "email": "[email protected]"
  }'

# DELETE request
curl -X DELETE https://api.example.com/users/123 \
  -H "Authorization: Bearer your-token"

# Save response to file
curl -o response.json https://api.example.com/users
curl --output response.json https://api.example.com/users

# Display only status code
curl -o /dev/null -s -w "%{http_code}\n" https://api.example.com/users

# Measure response time
curl -o /dev/null -s -w "Total time: %{time_total}s\n" https://api.example.com/users

Authentication and Header Configuration

# Basic authentication
curl -u username:password https://api.example.com/protected
curl --user username:password https://api.example.com/protected

# Hide password input (interactive)
curl -u username https://api.example.com/protected

# Bearer Token authentication
curl -H "Authorization: Bearer your-jwt-token" https://api.example.com/protected

# API Key authentication (custom header)
curl -H "X-API-Key: your-api-key" https://api.example.com/data
curl -H "Authorization: API-Key your-api-key" https://api.example.com/data

# Digest authentication
curl --digest -u username:password https://api.example.com/digest-auth

# NTLM authentication (Windows environment)
curl --ntlm -u domain\\username:password https://api.example.com/ntlm-auth

# OAuth 2.0 Bearer Token
curl --oauth2-bearer "mF_9.B5f-4.1JqM" https://api.example.com/oauth-protected

# Multiple custom header configuration
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "User-Agent: MyApp/1.0" \
     -H "X-Request-ID: req-12345" \
     -H "Authorization: Bearer your-token" \
     https://api.example.com/data

# Referrer configuration
curl -e "https://www.example.org" https://api.example.com/data
curl --referer "https://www.example.org" https://api.example.com/data

# User-Agent configuration
curl -A "Mozilla/5.0 (compatible; MyBot/1.0)" https://api.example.com/data
curl --user-agent "Mozilla/5.0 (compatible; MyBot/1.0)" https://api.example.com/data

# Read headers from file
curl -H @headers.txt https://api.example.com/data

# Remove default headers
curl -H "Host:" https://api.example.com/data
curl -H "User-Agent:" https://api.example.com/data

SSL/TLS Configuration and Proxy

# Skip SSL certificate verification (development only)
curl -k https://self-signed.example.com/
curl --insecure https://self-signed.example.com/

# Use specific CA certificate
curl --cacert /path/to/ca-cert.pem https://secure.example.com/

# Use client certificate
curl --cert /path/to/client.pem https://secure.example.com/
curl --cert /path/to/client.pem:password https://secure.example.com/

# Specify private key
curl --cert /path/to/client.pem --key /path/to/private.key https://secure.example.com/

# Force TLS 1.2 or higher
curl --tlsv1.2 https://api.example.com/data

# Specify specific TLS version
curl --tls-max 1.2 https://api.example.com/data

# Use HTTP proxy
curl -x http://proxy.example.com:8080 https://api.example.com/data
curl --proxy http://proxy.example.com:8080 https://api.example.com/data

# Authenticated proxy
curl -x http://user:[email protected]:8080 https://api.example.com/data
curl --proxy-user user:pass -x http://proxy.example.com:8080 https://api.example.com/data

# Use SOCKS5 proxy
curl --socks5 proxy.example.com:1080 https://api.example.com/data

# Exclude specific hosts from proxy
curl -x http://proxy.example.com:8080 --noproxy localhost,127.0.0.1 https://api.example.com/data

# Ignore system proxy settings
curl --noproxy "*" https://api.example.com/data

Cookie Management and Sessions

# Save cookies
curl -c cookies.txt https://api.example.com/login \
  -d "username=user&password=pass"

# Use saved cookies
curl -b cookies.txt https://api.example.com/dashboard

# Save and use cookies simultaneously
curl -c cookies.txt -b cookies.txt https://api.example.com/api

# Specify cookies directly
curl -b "session_id=abc123; user_pref=dark_mode" https://api.example.com/data

# Check cookie information with header dump
curl --dump-header headers.txt https://api.example.com/login

# Login sequence example for session maintenance
# 1. Login and save cookies
curl -c session.txt -X POST https://api.example.com/login \
  -H "Content-Type: application/json" \
  -d '{"username": "user", "password": "pass"}'

# 2. Access API with saved session
curl -b session.txt https://api.example.com/user/profile

# 3. Logout
curl -b session.txt -X POST https://api.example.com/logout

# Cookie management in JAR format (Netscape/Mozilla compatible)
curl -c cookies.jar -b cookies.jar https://api.example.com/data

File Operations and Large Transfer

# File download (automatic filename)
curl -O https://example.com/files/document.pdf
curl --remote-name https://example.com/files/document.pdf

# File download (specify filename)
curl -o mydocument.pdf https://example.com/files/document.pdf

# Display download progress
curl --progress-bar -O https://example.com/files/large-file.zip

# Resume large file download
curl -C - -O https://example.com/files/large-file.zip

# Parallel download of multiple files
curl -O https://example.com/file1.zip -O https://example.com/file2.zip

# File upload (POST)
curl -X POST https://api.example.com/upload \
  -H "Authorization: Bearer your-token" \
  -F "file=@/path/to/upload.pdf" \
  -F "category=documents"

# File upload (PUT)
curl -X PUT https://api.example.com/files/document.pdf \
  -H "Content-Type: application/pdf" \
  -H "Authorization: Bearer your-token" \
  --data-binary @document.pdf

# FTP upload
curl -T upload.txt ftp://ftp.example.com/uploads/ --user username:password

# Directory creation (FTP)
curl ftp://ftp.example.com/ --user username:password -Q "MKD newdir"

# Streaming download (to stdout)
curl -s https://api.example.com/stream | jq '.'

# Upload from stdin
echo '{"message": "Hello World"}' | curl -X POST https://api.example.com/messages \
  -H "Content-Type: application/json" \
  -d @-

# Partial download (range specification)
curl -r 0-1023 https://example.com/large-file.zip  # First 1024 bytes
curl -r 1024-2047 https://example.com/large-file.zip  # Next 1024 bytes

Advanced Configuration and Troubleshooting

# Timeout configuration
curl --connect-timeout 10 --max-time 60 https://api.example.com/data

# Retry configuration
curl --retry 3 --retry-delay 5 --retry-max-time 120 https://api.example.com/data

# Redirect tracking
curl -L https://bit.ly/shorturl  # Automatically follow redirects
curl --location --max-redirs 5 https://example.com/redirect

# Force IPv4/IPv6
curl -4 https://api.example.com/data  # IPv4 only
curl -6 https://api.example.com/data  # IPv6 only

# DNS specification
curl --resolve api.example.com:443:192.168.1.100 https://api.example.com/data

# Interface specification
curl --interface eth0 https://api.example.com/data

# Rate limiting (bandwidth limiting)
curl --limit-rate 100k https://example.com/large-file.zip

# Silent mode (no output)
curl -s https://api.example.com/data
curl --silent https://api.example.com/data

# No output even on error
curl -s -f https://api.example.com/data  # Non-zero exit code on error

# Use configuration file
echo 'url = "https://api.example.com/data"' > curl.conf
echo 'header = "Authorization: Bearer token"' >> curl.conf
curl -K curl.conf

# Multiple URL processing
curl https://api.example.com/users/{1,2,3,4,5}
curl https://api.example.com/page[1-10]

# Conditional requests
curl -H "If-Modified-Since: Wed, 21 Oct 2015 07:28:00 GMT" https://api.example.com/data

# gzip/deflate compression support
curl -H "Accept-Encoding: gzip, deflate" --compressed https://api.example.com/data

# Detailed performance measurement
curl -w "DNS lookup: %{time_namelookup}s\n\
Connect: %{time_connect}s\n\
TLS handshake: %{time_appconnect}s\n\
Pre-transfer: %{time_pretransfer}s\n\
Redirect: %{time_redirect}s\n\
Start transfer: %{time_starttransfer}s\n\
Total: %{time_total}s\n\
Speed: %{speed_download} bytes/sec\n" \
-o /dev/null -s https://api.example.com/data

CI/CD and Automation Examples

# Health check (monitoring script)
#!/bin/bash
response=$(curl -s -o /dev/null -w "%{http_code}" https://api.example.com/health)
if [ "$response" = "200" ]; then
    echo "Service is healthy"
    exit 0
else
    echo "Service is down (HTTP $response)"
    exit 1
fi

# API test (test script)
#!/bin/bash
# User creation test
response=$(curl -s -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_TOKEN" \
  -d '{"name": "Test User", "email": "[email protected]"}' \
  -w "%{http_code}")

if echo "$response" | tail -1 | grep -q "201"; then
    echo "User creation test: PASS"
    user_id=$(echo "$response" | head -n -1 | jq -r '.id')
    
    # Delete created user
    curl -s -X DELETE "https://api.example.com/users/$user_id" \
      -H "Authorization: Bearer $API_TOKEN"
else
    echo "User creation test: FAIL"
    exit 1
fi

# Webhook sending (notification script)
curl -X POST https://hooks.slack.com/webhook-url \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Deployment completed successfully",
    "username": "Deploy Bot",
    "icon_emoji": ":rocket:"
  }'

# Dynamic configuration retrieval (configuration management)
config=$(curl -s -H "Authorization: Bearer $CONFIG_TOKEN" \
  https://config.example.com/api/v1/config/production)
export DATABASE_URL=$(echo "$config" | jq -r '.database.url')
export REDIS_URL=$(echo "$config" | jq -r '.redis.url')

# Log forwarding (log aggregation)
tail -f /var/log/application.log | while read line; do
  echo "$line" | curl -X POST https://logs.example.com/api/v1/logs \
    -H "Content-Type: text/plain" \
    -H "Authorization: Bearer $LOG_TOKEN" \
    -d @-
done