붙여 넣은 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 변환기 는 브라우저 안에서 처리가 끝나며 붙여 넣은 내용이 전송되지 않습니다. 다만 변환된 코드에는 토큰이 그대로 남으므로, 코드를 커밋하기 전에 환경 변수로 분리하는 것을 권합니다.