curl 명령어 치트시트: API 테스트를 위한 50+ 예제

REST API 테스트, 웹훅 디버그, HTTP 요청 자동화 등 curl은 모든 개발자에게 필요한 만능 도구입니다. 이 포괄적인 치트시트에는 카테고리별로 정리된 50개 이상의 curl 명령어 예제가 포함되어 있습니다.

cURL 코드 변환기로 curl 명령어를 코드로 변환 →

기본 HTTP 메서드

curl로 API 테스트의 기초. RESTful API에서 사용되는 5가지 핵심 HTTP 메서드: GET, POST, PUT, DELETE, PATCH.

GET Request

The most basic curl command. By default, curl performs a GET request. Use it to retrieve data from any URL.

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

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

# GET and show response headers too
curl -i https://api.example.com/users

# GET only the response headers
curl -I https://api.example.com/users

# GET with a specific HTTP version
curl --http2 https://api.example.com/users

POST Request

Send data to create a new resource. The -X POST flag is optional when using -d since curl automatically uses POST when data is included.

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

# POST with data from a file
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d @payload.json

# POST with URL-encoded form data
curl -X POST https://api.example.com/login \
  -d "username=admin&password=secret"

# POST and follow redirects
curl -L -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "John"}'

PUT Request

Replace an entire resource with new data. PUT is idempotent, meaning multiple identical requests have the same effect as a single one.

# PUT to update a resource
curl -X PUT https://api.example.com/users/123 \
  -H "Content-Type: application/json" \
  -d '{"name": "John Updated", "email": "john.new@example.com"}'

# PUT with data from file
curl -X PUT https://api.example.com/users/123 \
  -H "Content-Type: application/json" \
  -d @updated-user.json

DELETE Request

Remove a resource from the server. DELETE requests typically do not require a body.

# DELETE a resource
curl -X DELETE https://api.example.com/users/123

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

# DELETE with confirmation body
curl -X DELETE https://api.example.com/users/123 \
  -H "Content-Type: application/json" \
  -d '{"confirm": true}'

PATCH Request

Partially update a resource. Unlike PUT, PATCH only sends the fields that need to be changed.

# PATCH to partially update
curl -X PATCH https://api.example.com/users/123 \
  -H "Content-Type: application/json" \
  -d '{"email": "newemail@example.com"}'

# PATCH with JSON Merge Patch
curl -X PATCH https://api.example.com/users/123 \
  -H "Content-Type: application/merge-patch+json" \
  -d '{"nickname": null, "email": "new@example.com"}'

헤더 및 인증 헤더

HTTP 헤더로 요청에 추가 정보를 전달할 수 있습니다. 인증 헤더는 API 작업 시 가장 많이 사용하는 헤더입니다.

Bearer Token (OAuth 2.0)

# Bearer token authentication
curl https://api.example.com/protected \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# Bearer token with POST
curl -X POST https://api.example.com/data \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

Basic Authentication

# Basic auth with -u flag (recommended)
curl -u username:password https://api.example.com/protected

# Basic auth with header (manual base64)
curl https://api.example.com/protected \
  -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ="

# Prompt for password (more secure)
curl -u username https://api.example.com/protected

Custom Headers

# Set Content-Type
curl https://api.example.com/data \
  -H "Content-Type: application/json"

# Set Accept header
curl https://api.example.com/data \
  -H "Accept: application/xml"

# Multiple custom headers
curl https://api.example.com/data \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Request-ID: abc-123" \
  -H "X-API-Version: 2"

# Remove a default header (send empty)
curl https://api.example.com/data \
  -H "User-Agent:"

데이터 전송

대부분의 API 상호작용은 요청 본문에 데이터를 보내야 합니다. curl은 JSON, 폼 데이터, 파일 업로드, 멀티파트 요청을 지원합니다.

JSON Body

# Inline JSON
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "age": 30, "roles": ["admin", "user"]}'

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

# JSON with nested objects
curl -X POST https://api.example.com/orders \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {"id": 123, "name": "Alice"},
    "items": [
      {"product": "Widget", "qty": 2, "price": 9.99},
      {"product": "Gadget", "qty": 1, "price": 24.99}
    ]
  }'

Form Data

# URL-encoded form data (application/x-www-form-urlencoded)
curl -X POST https://api.example.com/login \
  -d "username=admin&password=secret123"

# Form data with --data-urlencode (auto-encodes special chars)
curl -X POST https://api.example.com/search \
  --data-urlencode "query=hello world&special=a+b"

# Read form value from file
curl -X POST https://api.example.com/submit \
  --data-urlencode "essay@essay.txt"

File Upload

# Upload a single file
curl -X POST https://api.example.com/upload \
  -F "file=@/path/to/document.pdf"

# Upload with custom filename
curl -X POST https://api.example.com/upload \
  -F "file=@localfile.jpg;filename=avatar.jpg"

# Upload with content type
curl -X POST https://api.example.com/upload \
  -F "file=@data.csv;type=text/csv"

Multipart Form Data

# File + text fields (multipart/form-data)
curl -X POST https://api.example.com/profile \
  -F "name=Alice" \
  -F "avatar=@photo.jpg" \
  -F "bio=Software developer"

# Multiple files
curl -X POST https://api.example.com/gallery \
  -F "images=@photo1.jpg" \
  -F "images=@photo2.jpg" \
  -F "images=@photo3.jpg"

# Multipart with JSON field
curl -X POST https://api.example.com/submit \
  -F "metadata={\"title\":\"Report\"};type=application/json" \
  -F "attachment=@report.pdf"

인증 방법

API는 다양한 인증 메커니즘을 사용합니다. OAuth, API 키, 쿠키, JWT 토큰 등 가장 일반적인 인증 패턴의 curl 예제입니다.

OAuth 2.0 Token Flow

# Step 1: Get access token (client credentials)
curl -X POST https://auth.example.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=your-client-id" \
  -d "client_secret=your-client-secret"

# Step 2: Use the token
curl https://api.example.com/resource \
  -H "Authorization: Bearer ACCESS_TOKEN_HERE"

# Refresh an expired token
curl -X POST https://auth.example.com/oauth/token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=your-refresh-token" \
  -d "client_id=your-client-id"

API Key Authentication

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

# API key in query parameter
curl "https://api.example.com/data?api_key=your-api-key-here"

# API key in Authorization header
curl https://api.example.com/data \
  -H "Authorization: ApiKey your-api-key-here"

Cookie-Based Authentication

# Send cookies with request
curl https://api.example.com/dashboard \
  -b "session_id=abc123; csrf_token=xyz789"

# Save cookies from response to file
curl -c cookies.txt https://api.example.com/login \
  -d "username=admin&password=secret"

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

# Save and send cookies (cookie jar)
curl -b cookies.txt -c cookies.txt https://api.example.com/profile

JWT Token Authentication

# Login to get JWT
curl -X POST https://api.example.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "secret"}'

# Use JWT in Authorization header
curl https://api.example.com/protected \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Refresh JWT token
curl -X POST https://api.example.com/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "your-refresh-token"}'

디버그 및 트러블슈팅

API 호출이 실패하거나 예상치 못한 동작을 할 때, 이러한 curl 플래그로 HTTP 레벨에서 무슨 일이 일어나는지 확인할 수 있습니다.

Verbose Output (-v)

# Show full request and response headers
curl -v https://api.example.com/users

# Even more verbose (includes SSL handshake)
curl -vvv https://api.example.com/users

# Verbose output to stderr, response to file
curl -v -o response.json https://api.example.com/users

# Trace full data transfer (hex dump)
curl --trace trace.log https://api.example.com/users

# Trace as ASCII
curl --trace-ascii trace.txt https://api.example.com/users

Timing & Performance

# Show detailed timing information
curl -w "\n---TIMING---\nDNS Lookup:    %{time_namelookup}s\nTCP Connect:   %{time_connect}s\nSSL Handshake: %{time_appconnect}s\nServer Process:%{time_starttransfer}s\nTotal Time:    %{time_total}s\nDownload Size: %{size_download} bytes\nHTTP Code:     %{http_code}\n" \
  -o /dev/null -s https://api.example.com/data

# Simple total time only
curl -w "\nTime: %{time_total}s\n" -o /dev/null -s https://api.example.com

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

# Timing with format file (reusable)
# Create curl-timing.txt with: time_total: %{time_total}\n
curl -w @curl-timing.txt -o /dev/null -s https://api.example.com

Follow Redirects (-L)

# Follow redirects automatically
curl -L https://example.com/short-url

# Follow redirects with a max limit
curl -L --max-redirs 5 https://example.com/short-url

# Show redirect chain
curl -L -v https://example.com/short-url 2>&1 | grep "< HTTP\|< Location"

# Follow redirects but change POST to GET after redirect
curl -L --post301 --post302 -X POST https://example.com/api \
  -d "data=value"

SSL Issues (-k)

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

# Use a custom CA certificate
curl --cacert /path/to/ca-cert.pem https://api.example.com

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

# Show SSL certificate info
curl -vI https://api.example.com 2>&1 | grep -A6 "Server certificate"

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

고급 사용법

프로덕션 워크플로우를 위한 curl 고급 기능: 프록시, 재시도, 속도 제한, 응답 파일 저장.

Proxy

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

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

# Proxy with authentication
curl -x http://user:pass@proxy.example.com:8080 https://api.example.com

# Use HTTPS proxy
curl --proxy-cacert proxy-ca.pem -x https://proxy.example.com:443 https://api.example.com

# Bypass proxy for specific hosts
curl --noproxy "localhost,127.0.0.1,.internal.com" \
  -x http://proxy:8080 https://api.example.com

Retry

# Retry on transient errors (3 times)
curl --retry 3 https://api.example.com/data

# Retry with delay between attempts
curl --retry 5 --retry-delay 2 https://api.example.com/data

# Retry with exponential backoff (max wait)
curl --retry 5 --retry-max-time 60 https://api.example.com/data

# Retry on all errors (not just transient)
curl --retry 3 --retry-all-errors https://api.example.com/data

Rate Limiting & Timeouts

# Limit download speed
curl --limit-rate 100K https://example.com/large-file.zip -o file.zip

# Set connection timeout (seconds)
curl --connect-timeout 5 https://api.example.com

# Set maximum time for entire operation
curl --max-time 30 https://api.example.com/slow-endpoint

# Both timeouts together
curl --connect-timeout 5 --max-time 30 https://api.example.com

Save Response to File

# Save with custom filename
curl -o response.json https://api.example.com/data

# Save with remote filename
curl -O https://example.com/files/report.pdf

# Save headers and body separately
curl -D headers.txt -o body.json https://api.example.com/data

# Append to file
curl https://api.example.com/logs >> all-logs.txt

# Download multiple files
curl -O https://example.com/file1.zip -O https://example.com/file2.zip

# Resume interrupted download
curl -C - -O https://example.com/large-file.iso

Other Advanced Options

# Silent mode (suppress progress bar)
curl -s https://api.example.com/data

# Silent but show errors
curl -sS https://api.example.com/data

# Send request from specific network interface
curl --interface eth0 https://api.example.com

# Set custom DNS resolver
curl --resolve api.example.com:443:127.0.0.1 https://api.example.com

# Parallel requests (curl 7.66+)
curl --parallel --parallel-max 5 \
  -O https://example.com/file1.zip \
  -O https://example.com/file2.zip \
  -O https://example.com/file3.zip

# Use a config file
curl -K curl.config https://api.example.com

curl을 코드로 변환

작동하는 curl 명령어가 있으면 프로그래밍 언어로 변환해야 합니다. 수동으로 변환하는 대신 자동 변환기를 사용하세요.

For example, this curl command:

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer token123" \
  -d '{"name": "Alice", "email": "alice@example.com"}'

Can be converted to Python:

import requests

response = requests.post(
    "https://api.example.com/users",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer token123"
    },
    json={"name": "Alice", "email": "alice@example.com"}
)
print(response.json())

Or to JavaScript (fetch):

const response = await fetch("https://api.example.com/users", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer token123"
  },
  body: JSON.stringify({
    name: "Alice",
    email: "alice@example.com"
  })
});
const data = await response.json();

Or to Go:

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body, _ := json.Marshal(map[string]string{
        "name":  "Alice",
        "email": "alice@example.com",
    })

    req, _ := http.NewRequest("POST", "https://api.example.com/users",
        bytes.NewBuffer(body))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer token123")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Instead of writing these conversions by hand, use our cURL to Code Converter to instantly generate production-ready code in Python, JavaScript, Go, PHP, Ruby, Java, C#, and more.

빠른 참조: curl 플래그 톱 20

가장 많이 사용되는 curl 플래그 한눈에 보기. 이 표를 북마크하여 빠르게 참조하세요.

플래그	설명	예제
`-X`	Set HTTP method (GET, POST, PUT, DELETE, PATCH)	`-X POST`
`-H`	Add a custom header	`-H "Content-Type: application/json"`
`-d`	Send data in request body	`-d '{"key":"val"}'`
`-F`	Send multipart form data / file upload	`-F "file=@photo.jpg"`
`-u`	Basic authentication (user:password)	`-u admin:secret`
`-o`	Save output to file (custom name)	`-o result.json`
`-O`	Save output using remote filename	`-O`
`-i`	Include response headers in output	`-i`
`-I`	Fetch headers only (HEAD request)	`-I`
`-v`	Verbose output (debug requests)	`-v`
`-s`	Silent mode (hide progress bar)	`-s`
`-S`	Show errors in silent mode	`-sS`
`-L`	Follow redirects (3xx responses)	`-L`
`-k`	Skip SSL certificate verification	`-k`
`-b`	Send cookies (string or file)	`-b cookies.txt`
`-c`	Save response cookies to file	`-c cookies.txt`
`-w`	Write-out format (timing, status code)	`-w "%{http_code}"`
`--retry`	Retry on transient failures	`--retry 3`
`--connect-timeout`	Max time for connection (seconds)	`--connect-timeout 5`
`--max-time`	Max time for entire operation (seconds)	`--max-time 30`

자주 묻는 질문

curl과 wget의 차이점은?

curl은 URL로 데이터 전송용으로 설계되어 다양한 프로토콜을 지원합니다. wget은 주로 파일 다운로더입니다. API 테스트에는 curl이 표준입니다.

curl로 JSON 데이터를 POST하려면?

-X POST -H "Content-Type: application/json" -d로 JSON 본문을 지정합니다. -d 플래그는 자동으로 POST를 설정하므로 -X POST는 기술적으로 선택사항입니다.

curl에서 SSL 인증서 오류를 처리하려면?

-k 또는 --insecure 플래그로 SSL 인증서 검증을 건너뜅니다. 개발에는 유용하지만 프로덕션에서는 사용하지 마세요.

curl 출력을 파일로 저장하려면?

-o(소문자)로 사용자 지정 파일명, -O(대문자)로 원격 파일명으로 저장합니다.

curl에서 여러 헤더를 보내려면?

여러 개의 -H 플래그를 추가합니다. -H 플래그 수에는 제한이 없습니다.

curl로 API 응답 시간을 측정하려면?

-w 플래그와 타이밍 변수를 사용합니다. 총 시간, DNS 조회 시간, 연결 시간, 첫 바이트까지의 시간을 표시할 수 있습니다.

이 치트시트를 북마크하세요. curl 명령어를 코드로 변환하려면 아래 변환 도구를 사용해 보세요.

cURL 코드 변환기 사용하기 →