curl

Dev Tools•

•C

Command-line tool for transferring data with URLs.

Official Website

Features

Multiple ProtocolsSSL SupportProxy SupportCookie Handling

Installation

Homebrew

brew install curl

APT (Debian/Ubuntu)

apt install curl

Pacman (Arch)

pacman -S curl

Why use curl?

curl is the standard command-line tool for data transfer using URLs. Pre-installed on virtually all Unix/Linux systems, it's ideal for automation in scripts and CI/CD pipelines.

Multi-Protocol Support

Supports numerous protocols including HTTP, HTTPS, FTP, SFTP, SCP, and LDAP.

Authentication Support

Supports various authentication methods including Basic, Digest, NTLM, OAuth, and client certificates.

File Transfer

Advanced file transfers with upload, download, and resume capabilities.

Script-Friendly

Complete features for automation scripts including exit codes, silent mode, and output control.

Installation

# macOS (pre-installed, for latest version)
brew install curl

# Ubuntu/Debian
sudo apt install curl

# CentOS/RHEL/Fedora
sudo dnf install curl

# Windows (Chocolatey)
choco install curl

# Windows (Scoop)
scoop install curl

curl is pre-installed on most systems. You can check the version with curl --version.

Basic Usage

GET Request

GET

# Simple GET
curl https://api.github.com/users/octocat

# Show verbose information (-v: verbose)
curl -v https://api.example.com/health

# Add header
curl -H "Accept: application/json" https://api.example.com/data

# Multiple headers
curl -H "Accept: application/json" -H "X-API-Key: secret" https://api.example.com/data

# Show response headers (-i: include)
curl -i https://api.example.com/data

POST Request

POST

# Form data (application/x-www-form-urlencoded)
curl -X POST -d "name=John&email=john@example.com" https://api.example.com/users

# JSON data
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"name":"John","email":"john@example.com"}' \
  https://api.example.com/users

# Read JSON from file
curl -X POST \
  -H "Content-Type: application/json" \
  -d @user.json \
  https://api.example.com/users

Other HTTP Methods

HTTP Methods

# PUT
curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane"}' \
  https://api.example.com/users/1

# PATCH
curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com"}' \
  https://api.example.com/users/1

# DELETE
curl -X DELETE https://api.example.com/users/1

# HEAD (headers only)
curl -I https://api.example.com/health

Common Patterns

Authentication

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

# Enter password interactively
curl -u username https://api.example.com/secure

# Bearer Token
curl -H "Authorization: Bearer your-token-here" https://api.example.com/data

# OAuth 2.0 Bearer Token (shorthand)
curl --oauth2-bearer your-token-here https://api.example.com/data

# API Key
curl -H "X-API-Key: your-api-key" https://api.example.com/data

File Upload

Upload

# Upload file (multipart/form-data)
curl -F "file=@/path/to/image.jpg" https://api.example.com/upload

# Multiple files
curl -F "file1=@image1.jpg" -F "file2=@image2.jpg" https://api.example.com/upload

# Combine file with fields
curl -F "file=@document.pdf" -F "description=Report" https://api.example.com/upload

# Specify Content-Type
curl -F "file=@data.json;type=application/json" https://api.example.com/upload

File Download

Download

# Download with specified filename
curl -o output.zip https://example.com/file.zip

# Use filename from URL
curl -O https://example.com/file.zip

# Resume (continue download)
curl -C - -O https://example.com/largefile.zip

# Hide progress
curl -s -O https://example.com/file.zip

# Show progress bar
curl -# -O https://example.com/file.zip

Advanced Usage

SSL/TLS

# Skip SSL certificate verification (development only)
curl -k https://localhost:8443/api

# Use client certificate
curl --cert client.pem --key client-key.pem https://api.example.com

# Specify CA certificate
curl --cacert /path/to/ca-bundle.crt https://api.example.com

# Specify TLS version
curl --tlsv1.2 https://api.example.com

Proxy

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

# SOCKS proxy
curl --socks5 localhost:1080 https://api.example.com

# Proxy authentication
curl -x http://proxy.example.com:8080 -U proxyuser:proxypass https://api.example.com

# Use environment variable
export http_proxy=http://proxy.example.com:8080
curl https://api.example.com

Cookie

# Send cookie
curl -b "session=abc123" https://api.example.com/dashboard

# Save cookies to file
curl -c cookies.txt https://api.example.com/login -d "user=admin&pass=secret"

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

# Send and receive cookies
curl -b cookies.txt -c cookies.txt https://api.example.com/action

Timeout and Retry

Timeout

# Connection timeout (seconds)
curl --connect-timeout 10 https://api.example.com

# Maximum time (seconds)
curl -m 30 https://api.example.com

# Retry
curl --retry 3 --retry-delay 5 https://api.example.com

# Extend retry scope
curl --retry 3 --retry-all-errors https://api.example.com

Common Options

Option	Description	Example
`-X`	Specify HTTP method	`curl -X POST url`
`-H`	Add header	`curl -H "Key: val" url`
`-d`	Send data	`curl -d "key=val" url`
`-F`	Form data (including files)	`curl -F "f=@file" url`
`-o`	Specify output file	`curl -o out.txt url`
`-s`	Silent mode	`curl -s url`
`-v`	Verbose output	`curl -v url`
`-i`	Include headers in output	`curl -i url`
`-L`	Follow redirects	`curl -L url`

Practical Examples

Response Processing

# Format JSON with jq
curl -s https://api.github.com/users/octocat | jq '.'

# Extract specific fields
curl -s https://api.github.com/users/octocat | jq '.login, .name'

# Get HTTP status code only
curl -s -o /dev/null -w "%{http_code}" https://api.example.com/health

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

Using in Shell Scripts

Shell Script

#!/bin/bash

# API health check
check_health() {
  local status=$(curl -s -o /dev/null -w "%{http_code}" "$1")
  if [ "$status" -eq 200 ]; then
    echo "OK"
    return 0
  else
    echo "FAIL (status: $status)"
    return 1
  fi
}

# Usage example
check_health "https://api.example.com/health"

# Store response in variable
response=$(curl -s https://api.example.com/data)
echo "$response" | jq '.status'

Tips

•Use -sS to hide progress while still showing errors
•Use --data-raw to prevent @ from being interpreted as file reference
•Use -w (write-out) option to get various metrics (time, size, etc.)
•You can set default options in ~/.curlrc
•For long commands, use -K config.txt to load from a config file for easier management

HTTPie - HTTP Client

User-friendly command-line HTTP client

tools8 min read

curl Command Guide

Transfer data from URLs

linux8 min read

wget Command Guide

Download files from the web

linux6 min read

Explore More

Browse Dev Tools

See all tools in this category

All CLI Tools

Explore all tool categories

Features

Installation

Why use curl?

Multi-Protocol Support

Authentication Support

File Transfer

Script-Friendly

Installation

Basic Usage

GET Request

POST Request

Other HTTP Methods

Common Patterns

Authentication

File Upload

File Download

Advanced Usage

SSL/TLS

Proxy

Cookie

Timeout and Retry

Common Options

Practical Examples

Response Processing

Using in Shell Scripts

Tips

Related Articles

HTTPie - HTTP Client

curl Command Guide

wget Command Guide

Explore More