cURL 명령어 생성기 & 빌더

curl 명령어란?

# Plain GET — curl defaults to GET
curl https://api.example.com/users

# GET with a Bearer token (auth is just a header)
curl https://api.example.com/me \
  -H 'Authorization: Bearer YOUR_TOKEN'

# POST a JSON body — note the Content-Type header
curl -X POST https://api.example.com/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada","role":"admin"}'

# Multipart file upload — '@' reads the file from disk
curl -X POST https://api.example.com/upload \
  -F 'file=@report.pdf' \
  -F 'title=Q3 report'

주요 기능

curl 대안 & HTTP 클라이언트

curl 명령어 예제

curl https://api.example.com/users

curl https://api.example.com/me \
  -H 'Authorization: Bearer YOUR_TOKEN'

curl -X POST https://api.example.com/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada","role":"admin"}'

curl -X POST https://api.example.com/login \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=ada&password=s3cret'

curl -X POST https://api.example.com/upload \
  -F 'file=@report.pdf' \
  -F 'title=Q3 report'

curl -L -o archive.zip \
  https://example.com/files/archive.zip

curl -u ada:s3cret \
  https://api.example.com/private

curl -v -i https://api.example.com/health

curl 명령어 만드는 방법

1. 1

   HTTP 메서드 선택

   GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS 중에서 선택하세요. curl은 기본적으로 GET을 사용하며, POST나 다른 동사를 선택하면 생성된 명령어에 `-X METHOD`가 추가됩니다. 또는 프리셋 버튼을 탭하면 메서드와 매칭 바디가 한 번에 설정됩니다.

2. 2

   URL과 쿼리 파라미터 입력

   요청 URL을 입력하세요(예: `https://api.example.com/users`). 쿼리 파라미터를 키/값 쌍으로 추가하면 도구가 URL 인코딩하여 `?key=value&…`를 URL에 자동으로 추가합니다. 수동 인코딩이 필요 없습니다.

3. 3

   헤더와 인증 추가

   요청 헤더를 키/값 쌍으로 추가하고 인증 방식을 선택하세요: 없음, Bearer 토큰, Basic(아이디/비밀번호), 커스텀 API 키 헤더. 서버가 요구하는 정확한 형식으로 올바른 `Authorization` 또는 커스텀 헤더가 생성됩니다.

4. 4

   요청 바디 설정

   POST/PUT/PATCH의 경우 바디 유형을 선택하세요. 원시 JSON을 붙여넣거나(`Content-Type` 헤더가 자동 추가됨), URL 인코딩 폼 필드를 만들거나, 멀티파트 업로드를 구성하고 `@` 접두어로 임의 필드를 파일로 전환하세요.

5. 5

   옵션 토글

   필요한 플래그를 켜세요. 리다이렉트 따르기(`-L`), TLS 무시(`-k`), 상세 출력(`-v`), 헤더 포함(`-i`), 압축(`--compressed`), 파일 출력(`-o`), 연결 타임아웃, 프록시(`-x`). 각 토글이 명령어를 실시간으로 업데이트합니다.

6. 6

   복사, 내보내기, 초기화

   완성된 명령어를 복사하거나 Export .sh로 스크립트로 다운로드하거나 초기화로 폼을 지우세요. 복사 전에 멀티라인 토글로 한 줄과 백슬래시 이어쓰기 출력 사이를 전환하세요.

흔한 curl 실수

# PATCH를 의도했지만 -d만으로는 POST가 됨
curl -d '{"role":"admin"}' \
  https://api.example.com/users/7

# 동사를 명시적으로 설정
curl -X PATCH -d '{"role":"admin"}' \
  -H 'Content-Type: application/json' \
  https://api.example.com/users/7

# 서버는 URL 인코딩으로 인식 — 400/415
curl -X POST https://api.example.com/users \
  -d '{"name":"Ada"}'

# JSON 콘텐츠 타입 선언
curl -X POST https://api.example.com/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada"}'

# $name이 셸에 의해 빈 문자열로 확장됨
curl -d "{\"user\":\"$name\"}" \
  https://api.example.com/users

# 작은따옴표는 바디를 리터럴로 전달
curl -d '{"user":"$name"}' \
  https://api.example.com/users

# -d가 이것을 POST로 변환
curl -d 'page=2&limit=50' \
  https://api.example.com/users

# URL에 쿼리 문자열을 사용하면 GET 유지
curl 'https://api.example.com/users?page=2&limit=50'

:: cmd.exe — 백슬래시는 이어쓰기 문자가 아님
curl -X POST https://api.example.com/users \
  -d '{"name":"Ada"}'

:: cmd.exe — 한 줄로 사용하거나 ^로 이어쓰기
curl -X POST https://api.example.com/users -d "{\"name\":\"Ada\"}"

# 공백이 인수를 분리 — curl이 두 개의 인수를 받음
curl https://api.example.com/search?q=hello world

# 공백 인코딩 (또는 전체 URL을 따옴표로 감싸기)
curl 'https://api.example.com/search?q=hello%20world'

주요 활용 사례

REST API 테스트

터미널을 떠나지 않고 REST 엔드포인트에 요청을 만들어 전송하세요. 메서드를 설정하고 Bearer 토큰을 붙여넣고 JSON 바디를 전송하고 응답을 읽습니다. 클라이언트 코드를 작성하기 전에 API 동작을 확인하는 가장 빠른 방법입니다.

문서에서 요청 재현

API 문서는 엔드포인트와 파라미터를 보여주지만 즉시 실행 가능한 완전한 명령어는 거의 제공하지 않습니다. 메서드, URL, 헤더, 인증을 입력하면 따옴표나 누락된 `Content-Type` 헤더와 씨름 없이 바로 실행 가능한 curl 명령어를 얻을 수 있습니다.

CI/CD 스모크 테스트 스크립트

상태 확인이나 배포 후 스모크 테스트용 curl 명령어를 생성한 다음 Export .sh로 파이프라인에 추가하세요. `--connect-timeout`과 `--max-time`을 추가하여 응답 없는 엔드포인트가 빌드를 차단하지 않도록 하고, `-w`로 상태 코드를 확인하세요.

파일 업로드 & 다운로드

`-F field=@file`을 사용한 `multipart/form-data` 업로드나, CDN으로의 리다이렉트를 따르는 `-L -o filename` 다운로드를 구성하세요. 까다로운 파일 이름이나 쿼리 값은 저희 URL 인코더로 먼저 인코딩하세요.

웹훅 디버깅

제공자가 전송하는 것과 동일한 JSON 바디를 올바른 서명 및 `Content-Type` 헤더와 함께 POST하여 웹훅 페이로드를 재현하세요. 핸들러가 요청을 거부한 이유를 디버깅하기 위해 동일한 요청을 로컬에서 재현합니다.

재현 가능한 버그 리포트

메서드, 헤더, 인증 플레이스홀더, 바디를 포함하는 자기 완결적인 curl 명령어 하나를 버그 리포트나 PR에 붙여넣어 누구나 정확한 요청을 재현할 수 있게 하세요. 요청을 글로 설명하는 것보다 훨씬 명확합니다.

curl 플래그 학습

각 폼 선택이 어떤 플래그에 매핑되는지 확인하세요. Basic 인증을 선택하면 `-u`가 나타나고, JSON 바디를 추가하면 `Content-Type` 헤더가 붙는 것을 볼 수 있습니다. 저희 curl 치트 시트와 함께 문법을 실습으로 배우는 방법입니다.

코드 변환을 위한 요청 준비

먼저 curl로 요청을 만들고 검증한 다음 앱의 HTTP 클라이언트 코드로 변환하세요. 곧 출시될 Convert 탭에서 붙여넣은 curl 명령어를 fetch, requests, Go, PHP, Ruby, Node.js로 변환할 수 있습니다. 작동하는 curl 명령어에서 시작하세요.

curl 플래그 & 문법 레퍼런스

셸 따옴표 & 이스케이프

도구는 값을 작은따옴표로 감싸는데, POSIX 셸에서 작은따옴표 문자열 내부는 아무것도 확장되지 않아 가장 안전합니다. 값 내부의 리터럴 작은따옴표는 `'\''` 시퀀스(따옴표 닫기, 이스케이프된 따옴표, 따옴표 다시 열기)로 처리됩니다. `cmd.exe`에서는 큰따옴표로 전환하세요. Git Bash와 WSL은 생성된 작은따옴표 명령어를 변경 없이 실행합니다.

-d vs --data-raw vs --data-binary

`-d`/`--data`는 바디에서 줄바꿈과 캐리지 리턴을 제거합니다. `key=value` 쌍에는 문제없지만 멀티라인 콘텐츠에는 손실이 발생합니다. `--data-raw`는 동일하지만 앞에 오는 `@`를 파일 이름으로 처리하지 않습니다. `--data-binary`는 바이트를 그대로 전송합니다(`@file`로 원시 파일 내용 업로드에 사용). 세 가지 모두 메서드를 직접 지정하지 않으면 POST를 의미합니다.

멀티파트 (-F) vs URL 인코딩 (-d)

`-F field=value`는 생성된 경계와 함께 `multipart/form-data`를 생성합니다. 파일 업로드(`-F file=@path`)와 파일/텍스트 혼합 폼에 필요합니다. `-d field=value`는 `&`로 연결된 단일 문자열인 `application/x-www-form-urlencoded`를 생성합니다. 멀티파트에는 `Content-Type`을 직접 설정하지 마세요. curl이 경계를 계산하고 헤더를 자동으로 설정합니다.

인증 헤더 인코딩

Bearer 인증은 `Authorization: Bearer `을 그대로 전송합니다(RFC 6750). `-u user:pass`를 사용한 Basic 인증은 Base64로 인코딩되어 `Authorization: Basic `로 전송됩니다. 인코딩이지 암호화가 아니므로 HTTPS를 사용하세요. API 키는 서비스가 요구하는 커스텀 헤더입니다. 예: `X-API-Key: `.

쿼리 문자열 인코딩

빌더에서 추가한 쿼리 파라미터는 퍼센트 인코딩되어 `?key=value&key2=value2`로 추가됩니다. 예약 문자(공백, `&`, `=`, `#`)가 이스케이프되어 URL이 유효하게 유지됩니다. 인코딩이 필요한 바디 필드의 경우 curl의 `--data-urlencode`가 요청 시 인코딩을 처리합니다.

리다이렉트 동작 (-L)

`-L` 없이는 curl이 301/302 응답을 출력하고 중지합니다. `-L`을 사용하면 `Location` 헤더를 따라 최종 URL로 이동합니다. 참고로 다른 호스트로 리다이렉트될 경우 curl은 `Authorization` 헤더를 제거합니다(보안 기본값). `--location-trusted`는 의미를 이해한 경우에만 사용하세요.

압축 응답

`--compressed`는 gzip/deflate/brotli 지원을 알리는 `Accept-Encoding` 헤더를 추가하고 응답을 투명하게 압축 해제하여 대역폭을 절약합니다. 디코딩된 바디는 비압축 요청과 동일합니다. 순수한 전송 최적화로, 대부분의 API 호출에서 안전하게 활성화할 수 있습니다.

출력: -o vs -O

`-o filename`은 응답 바디를 지정한 파일에 저장합니다. `-O`는 URL 경로에서 서버 파일 이름으로 저장합니다. 둘 다 일반적인 표준 출력 덤프를 생략합니다. `-L`과 함께 사용하면 파일이 저장되기 전에 리다이렉트가 실제 자산으로 해결됩니다.

curl 요청 모범 사례

공유 명령어에 시크릿을 하드코딩하지 마세요

PR, 티켓, 채팅에 붙여넣는 curl 명령어는 다른 사람이 읽고 도구가 인덱싱합니다. 토큰과 비밀번호는 플레이스홀더(`YOUR_TOKEN`)로 교체하거나 환경 변수를 참조하세요(`-H "Authorization: Bearer $API_TOKEN"`). 긴 인증 정보의 경우 curl이 파일에서 헤더를 읽을 수 있어(`-H @headerfile`) 시크릿이 셸 히스토리에 나타나지 않습니다.

바이너리 페이로드에는 --data-binary @file을 사용하세요

바디가 바이트가 중요한 파일(이미지, 서명된 페이로드, 공백이 의미 있는 JSON)인 경우 `-d @file` 대신 `--data-binary @file`을 사용하세요. 일반 `-d`는 줄바꿈과 캐리지 리턴을 제거하여 바이너리 및 멀티라인 콘텐츠를 손상시킵니다. `--data-binary`는 디스크에 있는 그대로 파일을 전송합니다.

헤더 값을 따옴표로 감싸세요

항상 `-H` 값을 따옴표로 감싸세요: `-H 'Content-Type: application/json'`. 따옴표 없이는 콜론 뒤의 공백이 인수를 분리하여 curl이 잘못된 헤더를 인식합니다. 작은따옴표는 또한 셸이 값 내부의 `$`, `*`, 기타 특수 문자를 확장하는 것을 방지합니다. 이 도구는 기본적으로 작은따옴표로 출력합니다.

대역폭 절약을 위해 --compressed를 사용하세요

API 호출과 다운로드에 `--compressed`를 추가하여 gzip/brotli 인코딩을 요청하고 curl이 투명하게 압축 해제하게 하세요. JSON이 많은 API의 경우 응답에는 변화 없이 전송 크기를 70~90% 줄일 수 있습니다. 엔드포인트를 반복적으로 폴링하는 스크립트에서 무료로 얻는 이점입니다.

스크립트에서 타임아웃을 고정하세요

자동화된 환경에서는 `--connect-timeout`과 `--max-time`을 추가하여 느리거나 응답 없는 엔드포인트가 파이프라인을 영원히 차단하지 않도록 하세요. `--max-time 10`을 사용한 상태 확인은 빠르게 실패하여 CI가 계속 진행할 수 있게 합니다. 즉시 포기하지 않고 일시적인 네트워크 문제를 흡수하려면 `--retry N`과 함께 사용하세요.

자동화 전에 -v로 검증하세요

curl 명령어를 스크립트나 크론 작업에 넣기 전에 `-v`로 한 번 실행하여 정확한 요청 라인, 헤더, TLS 핸드셰이크를 확인하세요. 잘못된 메서드, 누락된 `Content-Type`, 또는 인증 헤더가 추가되지 않은 것을 가장 빠르게 발견하는 방법입니다. 대화식으로 디버깅한 다음 프로덕션에서는 `-v`를 제거하세요.

자주 묻는 질문