curl 명령어 기초 완벽 가이드 - 개발자가 매일 쓰는 HTTP 요청 테스트 도구 사용법
API 테스트부터 파일 다운로드까지 터미널 하나로 해결하는 curl 사용법을 정리했습니다. 매일 쓰는 핵심 옵션 9가지와 GET, POST 실습 예제, 자주 겪는 오류 해결법까지 초보자 눈높이에서 설명합니다.
API 문서에 나온 curl 예제를 그대로 복사해서 터미널에 붙여넣었는데 알 수 없는 오류만 뜨고 멈춰버린 경험, 한 번쯤 있으실 겁니다. 서버가 제대로 응답하는지, 토큰이 유효한지 브라우저 없이 빠르게 확인해야 하는 순간은 생각보다 자주 찾아옵니다. 이럴 때 전 세계 개발자가 가장 먼저 꺼내는 도구가 curl입니다. curl 명령어 기초만 제대로 잡아두면 API 테스트, 파일 다운로드, 서버 상태 점검까지 터미널 하나로 끝낼 수 있습니다.
curl이란 무엇인가
curl은 Client URL의 줄임말로, 명령줄에서 서버와 데이터를 주고받는 오픈소스 도구입니다. 1998년 스웨덴 개발자 다니엘 스텐베리가 처음 공개했고, 현재 HTTP와 HTTPS를 포함해 20가지가 넘는 프로토콜을 지원합니다. 리눅스 서버부터 스마트TV까지 수많은 기기에 탑재되어 있어 사실상 표준에 가까운 도구입니다.
따로 설치할 필요가 없는 경우가 대부분입니다. macOS와 주요 리눅스 배포판에는 기본 탑재되어 있고, Windows 10 빌드 1803 이후 버전에도 기본 포함되어 있습니다. 터미널에 curl --version을 입력했을 때 버전 정보가 출력되면 바로 사용할 수 있는 상태입니다.
curl로 할 수 있는 대표적인 작업은 다음과 같습니다.
- REST API에 요청을 보내고 JSON 응답을 확인하는 테스트
- 웹 서버의 상태 코드와 응답 헤더 점검
- 파일 다운로드와 업로드
- 셸 스크립트, 크론(cron)과 결합한 모니터링 자동화
가장 많이 쓰는 기본 옵션 9가지
curl 옵션은 200개가 넘지만 실무에서 매일 쓰는 것은 10개 안팎입니다. 아래 표의 옵션만 익혀도 대부분의 상황을 해결할 수 있습니다. 옵션은 대소문자를 구분하기 때문에 -o와 -O가 서로 다른 옵션이라는 점에 주의하세요.
| 옵션 | 의미 | 사용 예 |
|---|---|---|
| -X | 요청 메서드 지정 | curl -X POST 주소 |
| -H | 요청 헤더 추가 | curl -H "Accept: application/json" 주소 |
| -d | 본문(body) 데이터 전송 | curl -d "name=kim" 주소 |
| -o | 응답을 지정한 파일명으로 저장 | curl -o result.html 주소 |
| -O | 원본 파일명 그대로 저장 | curl -O 파일주소 |
| -I | 응답 헤더만 확인 | curl -I 주소 |
| -L | 리다이렉트 자동 추적 | curl -L 주소 |
| -v | 요청과 응답 전 과정 출력 | curl -v 주소 |
| -s | 진행 표시 숨김(스크립트용) | curl -s 주소 |
GET과 POST 요청 실습
GET 요청으로 데이터 조회하기
가장 단순한 형태는 주소만 넘기는 것입니다. 옵션 없이 실행하면 curl은 기본으로 GET 요청을 보냅니다.
curl https://api.example.com/users?page=2
주의할 점이 하나 있습니다. 쿼리 파라미터에 한글이나 공백이 들어가면 서버가 요청을 거부하거나 400 오류를 돌려주는 경우가 많습니다. URL에는 아스키 문자만 허용되기 때문에 한글은 퍼센트 인코딩으로 변환해서 넣어야 하는데, URL 인코더 같은 웹 도구에 검색어를 넣으면 변환된 문자열을 바로 복사해서 쓸 수 있습니다. 예를 들어 서울이라는 단어는 %EC%84%9C%EC%9A%B8로 변환됩니다.
POST 요청으로 데이터 전송하기
POST는 -X POST와 -d 옵션을 함께 사용합니다. JSON을 보낼 때는 Content-Type 헤더를 반드시 지정해야 서버가 본문을 올바르게 해석합니다.
curl -X POST https://api.example.com/login -H "Content-Type: application/json" -d '{"id":"tester","pw":"1234"}'
사실 -d 옵션을 쓰면 curl이 자동으로 POST 방식으로 요청하기 때문에 -X POST는 생략해도 됩니다. 다만 처음에는 의도를 명확하게 드러내기 위해 붙여 쓰는 습관을 추천합니다.
헤더와 인증 다루기
실무 API는 대부분 인증을 요구합니다. 가장 흔한 방식은 Authorization 헤더에 토큰을 담는 것입니다.
curl -H "Authorization: Bearer 토큰값" https://api.example.com/me
-H 옵션은 여러 번 반복해서 쓸 수 있어 헤더가 몇 개든 추가할 수 있습니다. 아이디와 비밀번호를 쓰는 기본 인증(Basic Auth)은 curl -u 아이디:비밀번호 주소 형태로 -u 옵션 하나면 끝납니다.
응답이 어떻게 오는지 뜯어보고 싶다면 -v 옵션을 붙이세요. 요청 헤더, 응답 헤더, TLS 연결 과정까지 모두 출력되기 때문에 문제가 생겼을 때 원인을 찾는 속도가 크게 빨라집니다.
curl을 잘 쓴다는 것은 옵션을 많이 외우는 것이 아니라, 문제가 생겼을 때 -v와 -I로 요청과 응답을 직접 눈으로 확인하는 습관을 갖는 것입니다. 브라우저가 숨기는 통신 과정을 그대로 볼 수 있다는 점이 curl의 진짜 가치입니다.
자주 겪는 오류와 해결법
초보자가 curl을 쓰면서 가장 자주 만나는 오류 네 가지를 정리했습니다.
- Could not resolve host: 주소 오타가 원인인 경우가 대부분입니다. 프로토콜(https://)까지 포함해 주소를 다시 확인하세요.
- SSL certificate problem: 인증서 검증 실패입니다. 사내 테스트 서버라면 -k 옵션으로 검증을 건너뛸 수 있지만, 운영 환경에서는 인증서 자체를 고치는 것이 맞습니다.
- 400 Bad Request: 본문 형식이나 URL 인코딩 문제일 가능성이 큽니다. Content-Type 헤더와 특수문자 인코딩을 점검하세요.
- 응답이 비어 있음: 리다이렉트 때문일 수 있습니다. -L 옵션을 붙여 이동한 주소까지 따라가게 하세요.
실무에서 바로 쓰는 활용 팁
기초 문법에 익숙해졌다면 아래 습관을 더해보세요. 같은 명령어라도 활용도가 완전히 달라집니다.
- 응답 시간 측정: -w "%{time_total}" 옵션을 붙이면 요청에 걸린 총 시간이 초 단위로 출력됩니다. 간단한 성능 점검에 유용합니다.
- 서버 생존 확인: curl -I -s 주소로 상태 코드만 빠르게 확인하면 서버 점검 스크립트를 만들 수 있습니다.
- JSON 보기 좋게 출력: 명령어 뒤에 | python3 -m json.tool을 붙이면 들여쓰기된 JSON으로 볼 수 있습니다.
오늘 바로 해볼 액션은 두 가지입니다. 터미널을 열어 curl -I https://www.google.com으로 응답 헤더를 직접 확인해보고, 평소 쓰는 API 하나를 골라 -v 옵션으로 요청 전 과정을 살펴보세요. curl 명령어 기초는 손으로 한 번 쳐보는 순간 절반은 끝난 것입니다.
