[Network] cURL이란? 개념부터 자주 쓰는 핵심 명령어까지 완벽 정리

백엔드 개발자나 API 통신을 다루는 사람이라면 터미널에서 자주 사용하는 도구 cURL(Client URL)에 대해 정리했다.

1. cURL이란?

cURL은 서버와 네트워크를 통해 데이터를 전송하거나 받을 때 사용하는 커맨드 라인(Command Line) 도구이다.
웹 브라우저가 없어도 터미널에서 HTTP, HTTPS, FTP 등 다양한 프로토콜을 이용해 통신할 수 있어, API 서버 개발 후 테스트를 하거나 스크립트를 작성할 때 필수적으로 사용된다.

2. 왜 cURL을 사용할까?

CLI 환경 최적화: GUI 도구(Postman 등)를 무겁게 띄우지 않아도 터미널만으로 빠르게 API 요청을 테스트할 수 있다.
스크립트 자동화: 쉘 스크립트에 포함하여 주기적인 데이터 수집이나 서버 헬스체크를 자동화하기에 매우 좋다.
높은 호환성: 대부분의 Mac이나 Linux 환경에 기본적으로 설치되어 있어 별도의 설정 없이 바로 사용할 수 있다.

3. 기본 구조 및 핵심 옵션 요약

가장 많이 활용하는 HTTP 요청을 기준으로, 기본 구조는 다음과 같다.

기본 구조: curl [옵션] [URL]

옵션	설명	예시
`-X`	요청 메소드 지정 (GET, POST, PUT, DELETE 등)	`-X POST`
`-H`	헤더(Header) 추가 (인증, Content-Type 등)	`-H "Content-Type: application/json"`
`-d`	데이터(Body) 전송	`-d '{"key":"value"}'`
`-i`	응답 헤더(Response Header)를 포함하여 출력	`-i`
`-v`	상세 과정(Request/Response 전체) 디버깅 출력	`-v`
`-O`	URL의 원본 파일명 그대로 다운로드	`-O`
`-o`	지정한 파일명으로 다운로드	`-o filename.ext`

4. 실전! 자주 사용하는 명령어 패턴

앞서 살펴본 옵션들을 조합하여 실무에서 가장 자주 쓰는 패턴 5가지를 정리했다.

① 기본 GET & DELETE 요청 (조회/삭제)

-X 옵션으로 HTTP 메서드를 지정한다. 옵션을 생략하면 기본값인 GET으로 동작한다.

# GET 요청 (웹페이지 또는 API 단순 조회)
curl https://api.example.com/users

# DELETE 요청 (특정 리소스 삭제)
curl -X DELETE https://api.example.com/users/1

② POST 요청 (JSON 데이터 전송)

API 개발 시 가장 많이 테스트하는 패턴이다. -H로 데이터 타입을 명시하고, -d로 본문(Body)을 보낸다.

💡 Mac 터미널 팁: JSON 데이터를 감쌀 때는 바깥쪽에 작은따옴표(‘)를 사용하는 것이 내부 큰따옴표와의 충돌(파싱 에러)을 방지해 주어 훨씬 편리하다!

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

③ 인증 토큰(Authorization) 포함 요청

JWT나 API Key와 같은 인증 정보가 필요할 때 -H 옵션을 추가하여 전송한다.

# JSON 타입 명시 및 Bearer 토큰 포함
curl -X GET https://api.example.com/secure-data \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

④ 파일 다운로드

-O(대문자)와 -o(소문자)를 상황에 맞게 활용하여 파일을 터미널에서 바로 다운로드할 수 있다.

# 대문자 O: 원본 이름(sample-image.png) 그대로 현재 폴더에 저장
curl -O https://example.com/sample-image.png

# 소문자 o: 내가 원하는 이름(my_image.png)으로 변경하여 저장
curl -o my_image.png https://example.com/sample-image.png

⑤ 디버깅 (요청/응답 상세 확인)

통신이 실패하거나 어떤 헤더가 오고 가는지 세밀하게 확인해야 할 때 필수적인 옵션입니다.

# -v (verbose): 요청(Request)과 응답(Response)의 모든 통신 과정을 출력
curl -v https://api.example.com

처음에는 터미널 환경이 낯설지만, 익숙해지면 키보드만으로 모든 API 통신을 제어할 수 있다.
직접 터미널을 열고 실행해보자!