cURL Commands: A Developer's Essential Guide

If you have ever worked with APIs, debugged a web server, or automated a deployment pipeline, chances are you have used cURL. Short for "Client URL," cURL is one of the most versatile and widely adopted command-line tools in a developer's toolkit. It allows you to transfer data to and from servers using virtually any protocol — HTTP, HTTPS, FTP, SMTP, and many more. In this comprehensive guide, we will explore everything you need to know about cURL, from basic syntax to advanced debugging techniques. Along the way, you will discover how tools like the cURL to Code converter can streamline your workflow.

What is cURL?

cURL is a free, open-source command-line tool and library (libcurl) for transferring data with URLs. It was first released in 1997 by Swedish developer Daniel Stenberg as a small project called "httpget," which was later renamed to cURL. Over the nearly three decades since its creation, cURL has grown into one of the most ubiquitous pieces of software in existence — installed by default on macOS, most Linux distributions, and Windows 10 and later.

The tool supports over 25 protocols, including HTTP, HTTPS, FTP, FTPS, SCP, SFTP, LDAP, MQTT, and more. Its versatility makes it indispensable in a wide range of scenarios:

• Testing and debugging REST APIs during development
• Downloading files from remote servers in scripts
• Automating CI/CD pipelines and health checks
• Sending webhooks and notifications
• Inspecting HTTP headers and SSL certificates
• Benchmarking server response times

Because cURL runs in the terminal, it integrates seamlessly with shell scripts, cron jobs, and automation tools. It is the go-to choice when you need a quick, reliable way to interact with a remote service without writing an entire application.

Basic cURL Syntax

The simplest cURL command fetches the content of a URL and prints it to standard output. Understanding the basic syntax is the foundation for everything more advanced.

Fetching a URL

The most basic usage simply passes a URL as an argument:

# URL 내용을 표준 출력으로 가져오기
curl https://api.example.com/data

Saving Output to a File

Use the -o flag to save the response body to a file, or -O to use the remote filename:

# 지정한 파일명으로 저장
curl -o response.json https://api.example.com/data

# 원격 파일명 그대로 저장
curl -O https://example.com/archive.zip

Viewing Headers Only

The -I flag sends a HEAD request and displays only the response headers. This is useful for checking content types, caching headers, or server information without downloading the full body:

# 응답 헤더만 출력
curl -I https://example.com

# 출력 예시:
# HTTP/2 200
# content-type: text/html; charset=UTF-8
# cache-control: max-age=3600

Verbose Mode

The -v flag enables verbose output, showing the full request and response exchange including TLS handshake details, request headers, and response headers. This is invaluable for debugging:

# 상세 요청/응답 정보 출력
curl -v https://api.example.com/health

HTTP Methods with cURL

cURL supports all HTTP methods. By default, it sends a GET request, but you can specify any method using the -X flag. Let us walk through each commonly used method with practical examples.

GET (Default)

GET requests retrieve data from a server. Since GET is the default method, the -X GET flag is optional:

# 사용자 목록 조회
curl https://api.example.com/users

# 쿼리 파라미터 포함
curl "https://api.example.com/users?page=2&limit=10"

POST

POST requests send data to the server to create a new resource. Use -X POST along with -d to include the request body:

# JSON 데이터로 새 사용자 생성
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "John Doe", "email": "john@example.com"}'

PUT

PUT requests replace an entire resource with new data:

# 사용자 정보 전체 업데이트
curl -X PUT https://api.example.com/users/42 \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Doe", "email": "jane@example.com", "role": "admin"}'

PATCH

PATCH requests partially update a resource, sending only the fields that need to change:

# 사용자 이메일만 부분 업데이트
curl -X PATCH https://api.example.com/users/42 \
  -H "Content-Type: application/json" \
  -d '{"email": "newemail@example.com"}'

DELETE

DELETE requests remove a resource from the server:

# 사용자 삭제
curl -X DELETE https://api.example.com/users/42

# 인증 포함 삭제 요청
curl -X DELETE https://api.example.com/users/42 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Headers and Authentication

HTTP headers carry essential metadata about requests and responses. cURL provides several flags to set headers and handle authentication, which are critical when working with APIs. You can inspect and analyze headers in detail using the HTTP Header Parser.

Custom Headers

Use the -H flag to set any HTTP header. You can specify multiple headers by repeating the flag:

# 여러 커스텀 헤더 설정
curl https://api.example.com/data \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Request-ID: abc-123-def"

Basic Authentication

The -u flag provides a convenient way to send HTTP Basic Authentication credentials:

# 기본 인증 (username:password)
curl -u admin:secret123 https://api.example.com/admin/dashboard

# 비밀번호를 프롬프트로 입력 (보안 강화)
curl -u admin https://api.example.com/admin/dashboard

Bearer Token

Most modern APIs use Bearer tokens (often JWTs) for authentication. Pass them through the Authorization header:

# Bearer 토큰으로 인증
curl https://api.example.com/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

API Key Authentication

Some APIs require an API key passed as a header or query parameter:

# 헤더로 API 키 전달
curl https://api.example.com/data \
  -H "X-API-Key: your-api-key-here"

# 쿼리 파라미터로 API 키 전달
curl "https://api.example.com/data?api_key=your-api-key-here"

Sending Data

cURL provides multiple ways to send data in request bodies. The right approach depends on the content type and the API's expectations.

Form Data (-d)

The -d flag sends data as application/x-www-form-urlencoded by default:

# URL 인코딩된 폼 데이터 전송
curl -X POST https://example.com/login \
  -d "username=admin&password=secret123"

Raw JSON (--data-raw)

When sending JSON payloads, use --data-raw or -d along with the appropriate Content-Type header. You can validate your JSON payload with the JSON Formatter before sending:

# JSON 데이터 직접 전송
curl -X POST https://api.example.com/orders \
  -H "Content-Type: application/json" \
  --data-raw '{
    "product_id": 101,
    "quantity": 3,
    "shipping_address": "123 Main St"
  }'

Multipart File Upload (-F)

The -F flag sends data as multipart/form-data, which is required for file uploads:

# 파일 업로드
curl -X POST https://api.example.com/upload \
  -F "file=@/path/to/document.pdf" \
  -F "description=Monthly Report"

# 여러 파일 동시 업로드
curl -X POST https://api.example.com/upload \
  -F "images[]=@photo1.jpg" \
  -F "images[]=@photo2.jpg"

Setting Content-Type

Always set the Content-Type header explicitly when the server expects a specific format:

# XML 데이터 전송
curl -X POST https://api.example.com/soap \
  -H "Content-Type: application/xml" \
  -d '<request><action>query</action></request>'

# 일반 텍스트 전송
curl -X POST https://api.example.com/log \
  -H "Content-Type: text/plain" \
  -d "Application started at 2024-01-15T10:30:00Z"

Common cURL Options

cURL offers hundreds of options, but a handful cover the vast majority of use cases. The following table summarizes the most important flags every developer should know:

These options can be combined to create robust, production-ready cURL commands. For instance, a common pattern for health checks in CI/CD pipelines:

# 프로덕션 헬스체크: 조용하게, 리다이렉트 따라가기, 30초 타임아웃, 3회 재시도
curl -s -L --max-time 30 --retry 3 \
  -o /dev/null -w "%{http_code}" \
  https://api.example.com/health

cURL for API Testing

cURL is one of the fastest ways to test an API without setting up Postman, Insomnia, or writing code. Here is a practical workflow for testing a REST API from the command line.

A Complete REST API Testing Workflow

# 1단계: 리소스 생성 (POST)
curl -s -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name": "Alice", "email": "alice@example.com"}'

# 2단계: 생성된 리소스 확인 (GET)
curl -s https://api.example.com/users/1 \
  -H "Authorization: Bearer $TOKEN"

# 3단계: 리소스 업데이트 (PATCH)
curl -s -X PATCH https://api.example.com/users/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name": "Alice Smith"}'

# 4단계: 리소스 삭제 (DELETE)
curl -s -X DELETE https://api.example.com/users/1 \
  -H "Authorization: Bearer $TOKEN"

Parsing Responses with jq

Piping cURL output to jq lets you parse, filter, and format JSON responses directly in the terminal:

# 응답에서 특정 필드만 추출
curl -s https://api.example.com/users | jq '.[].name'

# 조건부 필터링
curl -s https://api.example.com/users | jq '.[] | select(.role == "admin")'

# 응답을 보기 좋게 포맷팅
curl -s https://api.example.com/users/1 | jq '.'

Using Environment Variables

Environment variables make cURL commands portable across different environments (development, staging, production). You can parse and validate your API URLs with the URL Parser tool:

# 환경 변수 설정
export API_BASE="https://api.example.com"
export API_TOKEN="eyJhbGciOiJIUzI1NiIs..."

# 변수를 사용한 cURL 요청
curl -s "$API_BASE/users" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json"

# .env 파일에서 변수 로드
source .env && curl -s "$API_BASE/health"

cURL to Code Conversion

While cURL is perfect for quick testing, at some point you need to integrate API calls into your application code. Manually translating a complex cURL command — with its headers, authentication, data payloads, and options — into Python requests, JavaScript fetch, Java HttpClient, or any other language is tedious and error-prone.

This is exactly why cURL-to-code conversion tools exist. Instead of manually mapping -H flags to header dictionaries and -d payloads to request bodies, you can paste your working cURL command and instantly get production-ready code in your target language.

Common scenarios where cURL-to-code conversion saves time:

• Prototyping API integrations — test with cURL first, then convert to application code
• Onboarding — share cURL examples in API docs and let developers convert to their language
• Debugging — copy a failing request from browser DevTools as cURL, then convert to code
• Migration — moving API calls from shell scripts to a proper programming language

Debugging with cURL

cURL is not just for sending requests — it is a powerful debugging tool. When something goes wrong with an API call, cURL can help you pinpoint the exact issue.

Verbose Output (-v)

The verbose flag shows the complete conversation between client and server, including DNS resolution, TCP connection, TLS handshake, request headers sent, and response headers received:

# 전체 요청/응답 흐름 확인
curl -v https://api.example.com/data 2>&1 | head -30

# 출력 예시:
# * Trying 93.184.216.34:443...
# * Connected to api.example.com (93.184.216.34) port 443
# * SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384
# > GET /data HTTP/2
# > Host: api.example.com
# > User-Agent: curl/8.1.2
# < HTTP/2 200
# < content-type: application/json

Full Trace (--trace)

For even deeper inspection, the --trace flag logs every byte sent and received, including hex dumps:

# 전체 트레이스를 파일로 저장
curl --trace trace.log https://api.example.com/data

# ASCII 형식 트레이스 (읽기 편함)
curl --trace-ascii trace.txt https://api.example.com/data

Timing Analysis

The -w flag lets you measure exactly where time is being spent in a request. This is invaluable for diagnosing slow API calls:

# 상세 타이밍 분석
curl -s -o /dev/null -w "\
  DNS Lookup:    %{time_namelookup}s\n\
  TCP Connect:   %{time_connect}s\n\
  TLS Handshake: %{time_appconnect}s\n\
  First Byte:    %{time_starttransfer}s\n\
  Total Time:    %{time_total}s\n\
  HTTP Code:     %{http_code}\n" \
  https://api.example.com/data

SSL/TLS Debugging

cURL can help diagnose SSL certificate issues, which are a common source of API connection failures:

# SSL 인증서 상세 정보 확인
curl -vI https://example.com 2>&1 | grep -A 6 "Server certificate"

# 특정 CA 번들 사용
curl --cacert /path/to/ca-bundle.crt https://internal-api.company.com

# 클라이언트 인증서 사용 (mTLS)
curl --cert client.pem --key client-key.pem https://secure-api.example.com

Frequently Asked Questions

What is the difference between cURL and wget?

Both are command-line tools for transferring data, but they serve different primary purposes. cURL is designed for single URL transfers and supports over 25 protocols, making it ideal for API testing and scripting. wget is optimized for recursive downloads and mirroring websites. cURL sends output to stdout by default (great for piping), while wget saves to files. For API work, cURL is almost always the better choice.

How do I send a POST request with JSON data using cURL?

Use the -X POST flag along with -d for the data and -H to set the Content-Type header: curl -X POST -H "Content-Type: application/json" -d '{"key":"value"}' URL. Note that when using -d, cURL automatically sets the method to POST, so -X POST is technically optional.

How can I see the response headers in cURL?

You have several options: use -I to see headers only (sends a HEAD request), use -i to include headers in the output along with the body, or use -v for verbose mode which shows both request and response headers. For structured header analysis, try our HTTP Header Parser.

Can I use cURL on Windows?

Yes. cURL has been included by default in Windows 10 (build 17063 and later) and Windows 11. Open Command Prompt or PowerShell and type curl --version to verify. Note that in PowerShell, curl is aliased to Invoke-WebRequest. To use the real cURL, type curl.exe instead. On older Windows versions, you can install cURL via Chocolatey, Scoop, or download it directly from the official website.

How do I convert a cURL command to code?

The easiest way is to use an online converter tool. Simply copy your cURL command and paste it into a cURL to Code converter. These tools parse the cURL syntax and generate equivalent code in languages like Python, JavaScript, Go, PHP, Java, Ruby, and C#. This saves time and reduces the risk of translation errors, especially for complex commands with multiple headers, authentication, and data payloads.