curl(Client URL)은 서버와 통신할 때 사용하는 가장 강력하고 대중적인 커맨드라인 툴입니다. REST API 테스트, 파일 다운로드, 서버 디버깅 등 다양한 환경에서 필수적으로 사용됩니다.

초보자부터 중급자까지 실무에서 가장 많이 사용하는 옵션과 코드 예시를 정리해 드립니다.

🟢 초급: 기본 요청 및 파일 다운로드

1. 웹페이지 내용 확인 (기본 GET 요청)

가장 기본적인 형태로, URL을 입력하면 해당 서버의 응답(주로 HTML 문서나 JSON 데이터)을 화면에 출력합니다.

curl https://example.com

2. 결과를 파일로 저장 (`-o`, `-O`)

화면에 출력하는 대신 파일로 저장하고 싶을 때 사용합니다.

-o (소문자): 사용자가 지정한 이름으로 저장합니다.
-O (대문자): URL의 원본 파일 이름 그대로 저장합니다.

# custom_name.html 이라는 이름으로 저장
curl -o custom_name.html https://example.com

# 원본 이름인 ubuntu.iso 그대로 저장
curl -O https://releases.ubuntu.com/ubuntu.iso

3. 리다이렉트 따라가기 (`-L`)

요청한 주소가 다른 주소로 이동(Redirect)되었을 때, 변경된 주소로 자동으로 다시 요청을 보냅니다. (예: http -> https 자동 전환)

curl -L http://google.com

🟡 중급: API 통신 및 데이터 전송

4. HTTP 메서드 지정 (`-X`)

curl은 기본적으로 GET 메서드를 사용합니다. POST, PUT, DELETE 등으로 변경하려면 -X 옵션을 사용합니다.

curl -X DELETE https://api.example.com/users/123

5. 데이터 전송 (`-d`) 및 헤더 설정 (`-H`) - JSON POST 요청

REST API를 테스트할 때 가장 많이 사용하는 패턴입니다. -H로 전송하는 데이터의 타입을 알려주고, -d로 실제 데이터를 보냅니다.

curl -X POST https://api.example.com/users \
     -H "Content-Type: application/json" \
     -d '{"name": "홍길동", "email": "hong@example.com"}'

6. 폼(Form) 데이터 전송

웹 브라우저에서 HTML 폼을 제출하는 것과 같은 방식으로 데이터를 보냅니다.

curl -X POST https://api.example.com/login \
     -d "username=admin&password=1234"

7. 인증 토큰 전달 (`-H`)

JWT 토큰이나 API 키가 필요한 보안 엔드포인트에 접근할 때 HTTP 헤더에 Authorization 값을 추가합니다.

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     https://api.example.com/protected-data

🔴 중급+: 디버깅 및 서버 설정 우회

8. 통신 과정 상세 보기 (`-v`)

요청(Request) 헤더와 응답(Response) 헤더, 연결 과정을 모두 화면에 출력합니다. API 통신이 실패할 때 원인을 파악하기 매우 좋습니다.

curl -v https://example.com

9. SSL/TLS 인증서 무시 (`-k`)

개발 환경이나 사설 인증서를 사용하는 서버에 요청을 보낼 때 발생하는 'SSL 인증서 에러'를 무시하고 강제로 연결합니다.

curl -k https://localhost:8443/api

10. 기본 인증 (Basic Authentication) (`-u`)

ID와 비밀번호를 요구하는 페이지에 접근할 때 사용합니다.

curl -u username:password https://api.example.com/admin

💡 요약 치트시트

옵션	기능 설명
`-X`	HTTP 메서드 지정 (GET, POST, PUT, DELETE 등)
`-H`	HTTP 헤더 추가 (Content-Type, Authorization 등)
`-d`	HTTP 본문(Body) 데이터 전송
`-v`	통신 과정을 상세하게 출력 (디버깅용)
`-L`	HTTP 3xx 리다이렉트를 끝까지 추적
`-o` / `-O`	응답 결과를 파일로 다운로드
`-k`	안전하지 않은(유효하지 않은) SSL 인증서 허용
`-i`	응답 본문과 함께 응답 헤더도 출력

실제 사용 시나리오와 옵션 조합

1. 완벽한 REST API POST 요청 (인증 + JSON 데이터 + 타임아웃)

API 서버에 데이터를 생성할 때 가장 표준적으로 사용하는 조합입니다. 서버가 응답하지 않아 무한정 대기하는 것을 막기 위해 타임아웃(-m)을 함께 걸어주는 것이 좋습니다.

조합: -X POST + -H(인증) + -H(데이터 타입) + -d(데이터) + -m(타임아웃)

curl -X POST "https://api.example.com/v1/users" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name": "김개발", "role": "admin"}' \
     -m 10

Tip: -m 10은 10초 안에 응답이 오지 않으면 강제로 연결을 종료하라는 뜻입니다. 스크립트 작성 시 필수입니다.

2. 대용량 파일의 안정적인 다운로드 (리다이렉트 + 이어받기 + 진행률 바)

용량이 큰 설치 파일이나 압축 파일을 받을 때, 네트워크가 끊겨도 처음부터 다시 받지 않도록 설정하는 실무용 조합입니다.

조합: -L(이동된 주소 추적) + -C -(끊긴 곳부터 이어받기) + -#(진행률 바 표시) + -O(원본 이름 저장)

curl -L -C - -# -O "https://releases.ubuntu.com/ubuntu-22.04.iso"

3. 개발 서버 접속 및 딥(Deep) 디버깅 (SSL 무시 + 상세 로그 + 헤더 포함)

사내망이나 로컬 개발 서버를 띄웠을 때 HTTPS 인증서 에러가 나거나, 통신이 왜 실패하는지 원인을 밑바닥부터 파헤쳐야 할 때 씁니다.

조합: -k(인증서 에러 무시) + -v(요청/응답 상세 과정 출력) + -i(응답 본문 위에 헤더도 같이 출력)

curl -k -v -i "https://dev-server.local:8443/api/test"

4. 파일과 텍스트를 함께 업로드 (Multipart Form-data + 인증)

게시판에 글을 쓰면서 첨부파일을 같이 올리거나, 프로필 이미지를 업데이트하는 API를 테스트할 때 사용하는 조합입니다.

조합: -X POST + -H(인증) + -F(파일 첨부) + -F(일반 텍스트 폼)

curl -X POST "https://api.example.com/upload" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -F "profile_image=@/Users/kim/Documents/photo.jpg" \
     -F "description=새로운 프로필 사진입니다"

Tip: -F 옵션에서 파일 경로 앞에는 반드시 @를 붙여야 curl이 이를 텍스트가 아닌 파일로 인식합니다.

5. 자동화 스크립트용 깔끔한 출력 (Silent + 파이프라인 연동)

bash 스크립트나 CI/CD 파이프라인에서 curl을 쓸 때는 지저분한 다운로드 진행률 같은 부가 정보는 숨기고, 결과물(주로 JSON)만 깔끔하게 받아서 다른 툴로 넘겨야 합니다.

조합: -s(진행률 등 숨김) + 파이프(|) + jq(JSON 파싱 툴)

curl -s -H "Accept: application/json" "https://api.github.com/users/octocat" | jq '.name'

Tip: -s (silent) 옵션을 쓰면 에러 메시지까지 숨겨질 수 있습니다. 에러만 보고 싶다면 -sS로 조합하면 됩니다.

Curl