Curl Command

What is Linux curl Command?#

curl is a powerful command-line tool for transferring data from or to servers. It supports numerous protocols including HTTP, HTTPS, FTP, FTPS, SFTP, and many others. The name “curl” stands for “Client URL” and it’s designed to work without user interaction, making it perfect for scripts and automation. From the man page:

curl is a tool for transfering data from or to a server. It supports these protocols: DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, POP3, POP3S, RTMP, RTMPS, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET or TFTP. The command is designed to work without user interaction.

curl offers a comprehensive set of features including proxy support, user authentication, FTP upload, HTTP post, SSL connections, cookies, file transfer resume, and much more.

curl Syntax#

curl [options] <url>

Basic curl Examples#

Simple GET Request#

The most basic curl command performs a GET request to retrieve content from a URL:

curl https://httpbin.org/get

Download a File#

Download a file and save it with its original name:

curl -O https://example.com/file.zip

Download a file and save it with a custom name:

curl -o myfile.zip https://example.com/file.zip

Display Only Response Headers#

View only the HTTP headers without the response body:

curl -I https://httpbin.org/get

Include Response Headers with Body#

Display both headers and response body:

curl -i https://httpbin.org/get

Follow Redirects#

Automatically follow HTTP redirects:

curl -L https://bit.ly/shortened-url

HTTP Methods with curl#

GET Request (Default)#

curl https://httpbin.org/get

POST Request with Data#

Send data in a POST request:

curl -X POST -d "name=John&age=30" https://httpbin.org/post

Send JSON data:

curl -X POST \
-H "Content-Type: application/json" \
-d '{"name":"John","age":30}' \
https://httpbin.org/post

PUT Request#

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

DELETE Request#

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

PATCH Request#

curl -X PATCH \
-H "Content-Type: application/json" \
-d '{"age":31}' \
https://httpbin.org/patch

Set Custom Headers#

curl -H "User-Agent: MyApp/1.0" \
-H "Accept: application/json" \
https://httpbin.org/headers

Multiple Headers#

curl -H "Authorization: Bearer token123" \
-H "Content-Type: application/json" \
-H "X-Custom-Header: value" \
https://api.example.com/data

Authentication with curl#

Basic Authentication#

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

Bearer Token Authentication#

curl -H "Authorization: Bearer YOUR_TOKEN" https://api.example.com/resource

API Key Authentication#

curl -H "X-API-Key: YOUR_API_KEY" https://api.example.com/resource

Working with Cookies#

Save Cookies to File#

curl -c cookies.txt https://example.com/login

Send Cookies from File#

curl -b cookies.txt https://example.com/dashboard

Set Cookie Manually#

curl -b "session=abc123; theme=dark" https://example.com/page

File Uploads and Downloads#

Upload a File#

curl -F "file=@/path/to/your/file.txt" https://httpbin.org/post

Download a File (Resuming)#

curl -C - -O https://example.com/large-file.zip

Advanced Features#

Using Proxy#

curl --proxy http://proxy-server:8080 https://example.com

Ignore SSL Certificate Errors#

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

Set Maximum Time for Request#

curl --max-time 30 https://slow-server.com

Retry Failed Requests#

curl --retry 3 --retry-delay 2 https://unreliable-server.com

Verbose Output for Debugging#

curl -v https://httpbin.org/get

Silent Mode (No Progress Bar)#

curl -s https://api.example.com/data

Rate Limiting#

curl --limit-rate 100k -O https://example.com/largefile.zip

Working with JSON APIs#

GET JSON Data#

curl -H "Accept: application/json" https://jsonplaceholder.typicode.com/posts/1

POST JSON Data#

curl -X POST \
-H "Content-Type: application/json" \
-d '{ "title": "My Post", "body": "This is the post content", "userId": 1 }' \
https://jsonplaceholder.typicode.com/posts

Pretty Print JSON Response#

curl -s https://api.github.com/users/octocat | python -m json.tool

Testing and Development#

Check Website Response Time#

curl -w "@curl-format.txt" -o /dev/null -s https://example.com

Create curl-format.txt:

time_namelookup: %{time_namelookup}

time_connect: %{time_connect}

time_appconnect: %{time_appconnect}

time_pretransfer: %{time_pretransfer}

time_redirect: %{time_redirect}

time_starttransfer: %{time_starttransfer}

----------

time_total: %{time_total}

Check HTTP Status Code Only#

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

Save Response to Variable (in scripts)#

response=$(curl -s https://api.example.com/status)
echo "API Status: $response"

Common Use Cases#

Health Check Endpoint#

curl -f https://api.example.com/health || echo "Service is down"

Download and Extract Archive#

curl -L https://github.com/user/repo/archive/main.tar.gz | tar -xz

Send Slack Notification#

curl -X POST \
-H "Content-Type: application/json" \
-d '{"text":"Deployment completed successfully!"}' \
https://hooks.slack.com/services/YOUR/WEBHOOK/URL

Weather API Example#

curl -s "https://wttr.in/London?format=3"

Troubleshooting#

Common Error Messages#

“Connection refused”

• The server is not running or not accessible
• Check the URL and port number

“SSL certificate problem”

• Use -k to ignore SSL errors (not recommended for production)
• Or fix the certificate issue

“HTTP 404 Not Found”

• Check the URL path
• Verify the endpoint exists

“HTTP 401 Unauthorized”

• Check authentication credentials
• Verify API key or token

Debugging Tips#

1. Use -v for verbose output to see full request/response details
2. Use -I to check headers without downloading content
3. Use --trace-ascii trace.txt for detailed debugging information
4. Check connectivity with a simple GET request first

Best Practices#

1. Always validate SSL certificates in production - avoid using -k
2. Set appropriate timeouts - use --max-time to prevent hanging requests
3. Handle errors properly in scripts - check exit codes and use -f for failure detection
4. Use proper headers - set Content-Type, User-Agent, etc.
5. Implement retry logic - use --retry for unreliable networks
6. Store sensitive data securely - avoid putting passwords/tokens directly in commands

curl Command Manual / Help#

We can use man and info command to see the manual page of curl command. curl command also have --help option to show list of options. To open man page for curl command we can use command below. To exit man or info page you can press q.

man curl

To open info page for curl command we can use command below.

info curl

To open help page from curl command we can run command below.

curl --help

References#

You can find more information about curl from the following links:

• curl Website
• curl source code on GitHub
• curl Manual
• HTTPBin - HTTP Request & Response Service

Related Linux Commands#

You can read tutorials of related Linux commands below:

• wget Command

Summary#

In this comprehensive tutorial, we’ve covered the essential aspects of using curl, from basic GET requests to advanced features like authentication, file uploads, and debugging. curl is an invaluable tool for web developers, system administrators, and anyone working with APIs or web services.

Key takeaways:

• curl supports numerous protocols and HTTP methods
• Authentication can be handled through various methods (Basic, Bearer tokens, API keys)
• File uploads and downloads are straightforward with the right options
• Debugging features help troubleshoot connection and request issues
• Best practices ensure secure and reliable usage

Visit our Linux Commands guide to learn more about using command line interface in Linux.