April 7, 2025 9 min to read

Understanding and Using Curl - A Comprehensive Guide

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

Image Reference link

Introduction to Curl

Curl (Client URL) is a powerful command-line tool and library for transferring data with URLs using various protocols. It’s an essential tool for developers, system administrators, and security professionals, enabling everything from simple web requests to complex API interactions, with support for over 25 protocols including HTTP, HTTPS, FTP, and SMTP.

Before You Begin

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.

Curl offers several key capabilities that make it indispensable for development and troubleshooting:

• Universal Protocol Support: Works with numerous protocols beyond just HTTP
• Cross-Platform Compatibility: Available on virtually all operating systems
• Scriptability: Easily incorporated into shell scripts and automation
• No GUI Dependencies: Works in headless environments and terminals
• Extensive Documentation: Comprehensive man pages and online resources
• Active Development: Regular updates and security patches

Curl Command Structure

Understanding the structure of curl commands is essential for effective usage. This section explains the basic syntax, common options, and how to combine them for different tasks.

Basic Syntax

Command Structure

The basic syntax for curl commands follows this pattern:

curl [options] [URL]

For example, a simple GET request:

curl https://www.example.com

A more complex POST request:

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

Common Curl Options

Basic Curl Usage Examples

These examples demonstrate the fundamental ways to use curl for common tasks. Each example includes the command and a brief explanation of what it does, providing a practical foundation for using curl effectively.

HTTP Request Methods

Simple GET Request

Fetch the content of a webpage:

curl https://www.example.com

Making a POST Request

Send form data to a server:

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

Sending JSON Data

Submit JSON data to an API endpoint:

PUT Request for Updates

Update an existing resource:

DELETE Request

Remove a resource from the server:

curl -X DELETE https://api.example.com/resources/123

Handling Output

Saving Response to a File

Save the response body to a specific 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

Viewing Headers Only

Check HTTP headers without downloading the body:

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

Verbose Output for Debugging

Show detailed information about the request and response:

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

Common Connection Options

Following Redirects

Automatically follow HTTP redirect responses:

curl -L https://github.com

Setting Timeouts

Limit the connection time to prevent hanging:

curl --connect-timeout 5 https://slow-server.example.com

Ignoring SSL Certificate Validation

Bypass SSL verification for testing or self-signed certificates (use with caution):

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

Advanced Curl Techniques

For more complex tasks, curl offers advanced features that allow for sophisticated request handling, authentication, and integration with other tools and services. These examples demonstrate how to leverage curl’s powerful capabilities for professional use cases.

Working with APIs

GitHub API Example

Create a pull request using GitHub’s API:

Using Query Parameters

Search for repositories on GitHub:

Authentication Methods

Basic Authentication

Access resources that require username and password:

curl -u username:password https://api.example.com/protected-resource

Bearer Token Authentication

Use OAuth 2.0 or JWT tokens for authentication:

Cookies and Sessions

Handling Cookies

Maintain session state across requests:

File Upload

Uploading Files

Send files to a server using multipart/form-data:

Custom File Uploads

Set content type and filename for uploaded files:

Practical Curl Use Cases

Beyond basic web requests, curl serves as a versatile tool for a wide range of practical applications. This section demonstrates useful real-world examples that showcase curl’s flexibility and utility for everyday tasks.

Network Diagnostics

Check Public IP Address

Quickly determine your public IP address:

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

Testing DNS Resolution

Verify DNS resolution by forcing curl to use a specific IP:

curl -v --resolve example.com:443:93.184.216.34 https://example.com

s

Web Services and Information

Weather Information

Get current weather conditions in a terminal-friendly format:

curl wttr.in/Seoul

Currency Exchange Rates

Get the latest exchange rates:

curl -s https://api.exchangerate-api.com/v4/latest/USD | jq

HTTP Server Testing

Load Testing

Perform basic load testing with multiple requests:

# Make 10 concurrent requests
for i in {1..10}; do
  curl -s https://example.com > /dev/null &
done

Website Response Time

Measure how long it takes to connect to a website and receive data:

Best Practices and Tips

Following best practices ensures effective and secure usage of curl. These guidelines help avoid common pitfalls and enhance the usefulness of curl in both development and production environments.

Security Considerations

Scripting Efficiency

Script Example with Best Practices

Key Points

References

• Official Curl Documentation
• Curl Manual
• HTTP Protocol Documentation
• Curl Cookbook
• Everything curl (free ebook)
• Common Curl Examples