이 글에서 소개한 도구
글을 읽으면서 브라우저에서 바로 도구를 열어 작업 흐름을 직접 확인해 보세요.
붙여 넣은 curl을 읽을 수 있으면 API 조사가 빨라진다
문서나 브라우저 개발자 도구에서 복사한 curl 명령은 보통 이런 모습입니다.
curl -X POST 'https://api.example.com/v1/items?limit=10' \
-H 'Authorization: Bearer TOKEN' \
-H 'Content-Type: application/json' \
-d '{"name":"Alice","tags":["a","b"]}'
읽을 줄 알면 단순하지만, 옵션 조합에 따라 동작이 달라지는 지점이 몇 군데 있고, 이를 모르면 “같은 명령인데 여기서는 안 된다”를 만나게 됩니다.
curl 옵션 목록(목적별)
가장 자주 만나는 옵션을 하는 일별로 묶었습니다. 사용 중인 빌드가 지원하는 전체를 보려면 curl --help all(전체 목록), curl --help category(카테고리 목록), man curl(자세한 설명)을 실행하세요.
요청 만들기
| 옵션 | 의미 |
|---|---|
-X, --request |
HTTP 메서드 지정(GET / POST / PUT / DELETE) |
-H, --header |
요청 헤더 추가. 여러 번 쓸 수 있음 |
-A, --user-agent |
User-Agent 헤더 지정 |
-e, --referer |
Referer 헤더 지정 |
-b, --cookie |
쿠키 전송 |
-c, --cookie-jar |
받은 쿠키를 파일에 저장 |
-u, --user |
Basic 인증(user:password) |
-G, --get |
-d의 데이터를 본문이 아니라 URL 쿼리 문자열에 넣음 |
데이터 보내기
| 옵션 | 의미 |
|---|---|
-d, --data |
요청 본문 전송. POST를 암시 |
--data-raw |
-d와 같지만 맨 앞의 @를 파일 이름으로 취급하지 않음 |
--data-binary |
줄바꿈을 포함해 주어진 그대로 전송(파일, 바이너리) |
--data-urlencode |
값을 퍼센트 인코딩해서 전송 |
-F, --form |
multipart/form-data로 전송(파일 업로드) |
-T, --upload-file |
파일 업로드(HTTP에서는 PUT) |
--json |
JSON을 보내고 Content-Type과 Accept도 설정(curl 7.82+) |
응답 다루기
| 옵션 | 의미 |
|---|---|
-o, --output |
응답을 파일에 기록 |
-O, --remote-name |
URL의 파일 이름으로 저장 |
-i, --include |
응답 헤더를 출력에 포함 |
-I, --head |
HEAD를 보내 헤더만 표시 |
-D, --dump-header |
응답 헤더를 파일에 기록 |
-w, --write-out |
끝났을 때 %{http_code} 같은 정보를 출력 |
-r, --range |
바이트 범위 요청(예: 0-99) |
-C - |
일부만 내려받은 파일을 이어받기 |
--compressed |
압축 전송 요청(gzip 등) |
출력과 오류
| 옵션 | 의미 |
|---|---|
-s, --silent |
진행 표시를 숨김 |
-S, --show-error |
-s와 함께 쓰면 오류는 여전히 표시 |
-v, --verbose |
요청 헤더를 포함해 주고받는 내용 전체를 표시 |
-f, --fail |
HTTP 400 이상이면 본문을 출력하지 않고 종료 코드 22로 종료 |
-#, --progress-bar |
진행 상황을 막대로 표시 |
연결·타임아웃·리다이렉트
| 옵션 | 의미 |
|---|---|
-L, --location |
리다이렉트(3xx)를 따라감 |
--max-redirs |
따라갈 리다이렉트의 최대 횟수 |
--connect-timeout |
연결을 기다리는 초 |
-m, --max-time |
전체 최대 초. 이 시간이 지나면 전송을 중단 |
--retry |
일시적 오류 시 재시도 횟수 |
-x, --proxy |
프록시를 거쳐 연결 |
--resolve |
호스트 이름을 지정한 IP로 해석(host:port:address). DNS를 바꾸지 않고 새 서버를 시험할 때 편리 |
-4, -6 |
IPv4 / IPv6만 사용 |
-g, --globoff |
URL의 []와 {}를 확장하지 않음 |
TLS(HTTPS)
| 옵션 | 의미 |
|---|---|
-k, --insecure |
서버 인증서 검증을 건너뜀 |
--cacert |
검증에 쓸 CA 인증서 파일 |
-E, --cert / --key |
클라이언트 인증서와 개인 키 |
-X POST 는 대개 생략할 수 있다
-d 를 붙이면 curl은 자동으로 POST가 됩니다. 아래 두 줄은 같습니다.
curl -X POST https://api.example.com/items -d '{"a":1}'
curl https://api.example.com/items -d '{"a":1}'
문제는 반대 경우입니다. -X GET 과 -d 를 함께 쓰면 본문이 있는 GET 요청이 되고, 프록시나 서버에 따라 무시되거나 거부됩니다. “로컬에서는 되는데 운영에서 실패”의 전형적인 원인입니다.
-d 를 여러 번 쓰면 값들이 & 로 이어집니다. 폼 전송에는 편하지만 JSON에는 치명적입니다.
# 의도와 다름: {"a":1}&{"b":2} 가 전송됨
curl -d '{"a":1}' -d '{"b":2}' https://api.example.com/items
-d 의 @ 는 파일 읽기가 된다
-d 에 넘긴 값이 @ 로 시작하면 curl은 그 파일을 읽어 내용을 보냅니다.
curl -d @payload.json https://api.example.com/items # 파일 내용을 전송
편리하지만 사용자명이나 이메일을 그대로 넘기면 사고가 납니다.
# 의도: 문자열 "@alice" 전송
# 실제: ./alice 파일을 찾다가 없으면 오류
curl -d '@alice' https://api.example.com/items
@ 가 포함된 값을 그대로 보내려면 --data-raw 를 쓰세요. @ 를 특별 취급하지 않습니다.
Content-Type 은 저절로 JSON이 되지 않는다
-d 를 쓰면 따로 지정하지 않는 한 Content-Type: application/x-www-form-urlencoded 가 붙습니다. JSON을 보내면서 헤더를 빠뜨리면 서버가 파싱에 실패합니다.
curl -H 'Content-Type: application/json' \
-d '{"name":"Alice"}' https://api.example.com/items
curl 7.82 이후에는 --json 이 있어 Content-Type: application/json 과 Accept: application/json 을 함께 붙여 줍니다. 다만 예전 환경에는 없으므로, 공유할 명령에는 헤더를 명시하는 편이 안전합니다.
따옴표 구분이 가장 큰 사고 요인
| 표기 | 동작 |
|---|---|
'...'(작은따옴표) |
안의 $ 와 " 를 그대로 전달. JSON이라면 이쪽 |
"..."(큰따옴표) |
셸이 $변수 를 전개 |
JSON은 큰따옴표를 포함하므로 바깥쪽은 작은따옴표가 기본입니다.
# OK
curl -d '{"name":"Alice"}' https://api.example.com/items
# 셸이 안쪽 따옴표를 벗겨 본문이 깨짐
curl -d "{"name":"Alice"}" https://api.example.com/items
토큰을 환경 변수에서 넣어야 할 때는 두 가지를 의도적으로 섞습니다.
curl -H "Authorization: Bearer $TOKEN" \
-d '{"name":"Alice"}' https://api.example.com/items
Windows 명령 프롬프트는 작은따옴표를 해석하지 않으며, PowerShell에서는 curl 이 Invoke-WebRequest 의 별칭인 경우가 있습니다. curl.exe 를 명시하거나 WSL·Git Bash에서 실행하세요.
어떤 데이터 옵션을 쓸까
-d 계열은 전송 전에 무엇이 변환되는지가 다릅니다.
| 옵션 | 변환 | 알맞은 용도 |
|---|---|---|
-d |
@로 시작하는 값은 파일을 읽고, 파일의 줄바꿈은 제거됨 |
폼, 짧은 JSON |
--data-raw |
@가 특별하지 않음 |
@가 들어 있는 문자열을 그대로 보낼 때 |
--data-binary |
줄바꿈을 포함해 주어진 그대로 전송 | 줄바꿈이 중요한 파일, 바이너리 데이터 |
--data-urlencode |
값을 퍼센트 인코딩 | 폼 값이나 쿼리의 비ASCII 텍스트·기호 |
-F |
multipart/form-data로 전송 |
파일 업로드 |
파일을 읽으려면 -d @payload.json, 표준 입력을 읽으려면 -d @-를 씁니다. 줄바꿈을 보존하고 싶은 JSON 파일이나 바이너리 데이터에는 --data-binary @file을 쓰세요.
타임아웃과 재시도
curl을 스크립트에서 실행할 때는 절대 무한정 기다리지 않도록 시간 제한을 두세요.
curl --connect-timeout 5 --max-time 30 --retry 3 https://api.example.com/items
--connect-timeout: 연결을 기다리는 초-m, --max-time: 전체 전송에 허용하는 초. 큰 다운로드에는 더 넉넉하게 주세요--retry: 타임아웃이나 일부 HTTP 오류(429, 502, 503, 504 등) 시 재시도하는 횟수
기본적으로 curl은 서버가 404나 500을 돌려줘도 종료 코드 0으로 끝납니다. 스크립트에서 실패를 감지하려면 -f를 더하세요.
curl -fsS https://api.example.com/health || echo "failed"
상태 코드만 얻으려면 -w를 씁니다.
curl -s -o /dev/null -w '%{http_code}\n' https://example.com/
Windows에서는 /dev/null 대신 NUL을 씁니다. -w는 %{time_total}(전체 소요 초) 같은 변수도 지원합니다.
자주 보는 종료 코드
스크립트에서 $?를 확인할 때의 길잡이입니다(전체 목록은 man curl의 “EXIT CODES”에 있습니다).
| 코드 | 의미 |
|---|---|
| 0 | 성공 |
| 6 | 호스트를 해석할 수 없음 |
| 7 | 연결 실패 |
| 22 | HTTP 400 이상(-f 사용 시) |
| 28 | 타임아웃 |
| 35 | TLS 핸드셰이크 실패 |
| 60 | 서버 인증서를 검증할 수 없음 |
Windows에서 curl.exe 쓰기
Windows 10(버전 1803) 이후에는 curl.exe가 포함되어 있습니다. 옵션은 Linux·macOS와 같지만 명령을 쓰는 방법은 셸에 따라 다릅니다.
| 항목 | 명령 프롬프트(cmd) | PowerShell |
|---|---|---|
| 호출 | curl / curl.exe |
curl.exe로 쓰세요(curl이 Invoke-WebRequest의 별칭일 수 있음) |
| 따옴표 | 큰따옴표만(작은따옴표는 동작하지 않음) | 작은따옴표·큰따옴표 모두 가능하지만 안쪽 "가 사라질 수 있음 |
| 줄 이음 | ^ |
백틱 ` |
cmd에서는 JSON 안의 큰따옴표를 \"로 이스케이프합니다.
curl.exe -X POST -H "Content-Type: application/json" -d "{\"name\":\"Alice\"}" https://api.example.com/items
PowerShell도 JSON의 따옴표를 쉽게 망가뜨리므로 가장 확실한 방법은 JSON을 파일에 넣고 -d @body.json으로 넘기는 것입니다.
curl.exe -X POST -H "Content-Type: application/json" -d "@body.json" https://api.example.com/items
헷갈리면 작은따옴표가 동작해 이 글의 예제를 그대로 쓸 수 있는 WSL이나 Git Bash에서 명령을 실행하세요.
URL에 & 가 있으면 따옴표로 감싼다
파라미터가 여러 개인 URL을 그대로 붙여 넣으면 셸이 & 를 백그라운드 실행으로 해석해 명령이 잘립니다.
# 깨짐: limit=10 까지만 전달됨
curl https://api.example.com/items?limit=10&offset=20
# 올바름
curl 'https://api.example.com/items?limit=10&offset=20'
공백이나 비ASCII 문자가 들어간 값은 퍼센트 인코딩이 필요합니다. URL 인코딩·디코딩 으로 확인하거나, -G 와 --data-urlencode 로 curl에게 맡길 수 있습니다.
curl -G https://api.example.com/search --data-urlencode 'q=서울 타워'
쉽게 붙이면 안 되는 두 가지
-k / --insecure 는 인증서 검증을 끕니다. 로컬에서 자체 서명 인증서를 시험할 때는 필요하지만, 오류를 없애려고 붙였다가 그대로 공유되거나 운영에 들어가는 것이 전형적인 사고입니다. 인증서 문제는 인증서 쪽에서 고치세요.
-L / --location 은 리다이렉트를 따라갑니다. 편리하지만 POST가 리다이렉트될 때 메서드와 본문의 취급이 달라질 수 있습니다. 동작을 고정하려면 --post301 --post302 --post303 으로 명시하세요.
읽은 curl을 그대로 코드로
읽어낸 curl을 애플리케이션 코드로 옮길 때 헤더와 본문을 손으로 옮겨 적는 것은 실수의 원인입니다. cURL 변환기 에 붙여 넣으면 JavaScript·Python·Go 등의 요청 코드로 변환됩니다. 따옴표 대응과 헤더 분해는 도구가 처리합니다.
보낼 JSON의 정렬과 문법 확인은 JSON 포매터, 쿼리 문자열의 내용을 보려면 URL 파라미터 → JSON 변환 이 편리합니다. 모두 브라우저 안에서 처리되므로 인증 토큰이 포함된 명령을 붙여 넣어도 외부로 전송되지 않습니다.
정리
-d를 붙이면 자동으로 POST.-X GET과 함께 쓰면 본문 있는 GET이 되어 다루기 어렵다-d값이@로 시작하면 파일 읽기. 문자열로 보내려면--data-raw-d만으로는 폼 형식. JSON이면 헤더를 명시하거나--json(curl 7.82+)- JSON을 보낼 때 바깥은 작은따옴표, 변수 전개가 필요한 곳만 큰따옴표
- URL에
&가 있으면 따옴표로 감싼다. 값 인코딩은-G --data-urlencode가 안전 -k는 오류를 지우는 도구가 아니며,-L은 POST 동작을 바꿀 수 있다
자주 묻는 질문
curl 옵션을 전부 보려면 어떻게 하나요?
curl --help all을 실행하면 모든 옵션이, curl --help category를 실행하면 카테고리가 나옵니다. 자세한 설명은 man curl에 있습니다. Windows에서는 curl.exe --help all을 쓰세요. 위의 “curl 옵션 목록(목적별)” 표에 가장 많이 쓰는 옵션을 담았습니다.
curl과 curl.exe는 무엇이 다른가요?
Windows PowerShell에서 curl은 옵션이 다른 Invoke-WebRequest의 별칭일 수 있습니다. 진짜 curl을 호출하려면 curl.exe라고 쓰세요. 명령 프롬프트에서는 어느 이름이든 curl.exe가 실행됩니다.
curl이 404에서도 종료 코드 0으로 끝납니다. 실패하게 할 수 있나요?
-f(--fail)를 더하세요. HTTP 400 이상이면 curl이 본문을 출력하지 않고 종료 코드 22로 끝납니다. 스크립트에서 실패를 감지할 때 유용합니다. 멈춰 있지 않도록 --connect-timeout, --max-time과 함께 쓰세요.
-X POST 는 안 써도 되나요?
대개 필요 없습니다. -d 나 -F 를 붙인 시점에 자동으로 POST가 됩니다. 다만 명시해 두면 의도가 전달되므로 공유할 명령에는 써 둘 가치가 있습니다. 피해야 할 것은 -X GET 과 -d 의 조합으로, 본문 있는 GET이 되어 환경에 따라 무시되거나 거부됩니다.
-d 와 --data-raw 의 차이는 무엇인가요?
값이 @ 로 시작할 때의 처리만 다릅니다. -d 는 @ 뒤 문자열을 파일명으로 보고 내용을 읽어 보내지만, --data-raw 는 문자열 그대로 보냅니다. 이메일 주소처럼 @ 를 포함한 데이터를 보낼 때는 --data-raw 를 쓰세요.
JSON을 보냈는데 서버가 파싱하지 못합니다
-d 를 쓰면 기본 Content-Type 이 application/x-www-form-urlencoded 이므로 -H 'Content-Type: application/json' 이 필요합니다. curl 7.82 이후라면 --json 으로 헤더까지 지정할 수 있습니다.
Windows에서 명령이 동작하지 않습니다
명령 프롬프트는 작은따옴표를 해석하지 않고, PowerShell에서는 curl 이 Invoke-WebRequest 의 별칭일 수 있습니다. curl.exe 를 명시하거나 WSL·Git Bash처럼 작은따옴표를 해석하는 셸에서 실행하세요.
인증 토큰이 든 명령을 붙여 넣어도 괜찮나요?
cURL 변환기 는 브라우저 안에서 처리가 끝나며 붙여 넣은 내용이 전송되지 않습니다. 다만 변환된 코드에는 토큰이 그대로 남으므로, 코드를 커밋하기 전에 환경 변수로 분리하는 것을 권합니다.
