curl 명령어 사용법

다음은 요청하신 내용을 바탕으로 본문을 더욱 풍부하게 다듬고, "흔히 하는 실수"와 "한 단계 더 — 고급 팁" 섹션을 보강하여 완성한 글입니다.

*

API를 개발하거나 서버를 운영하면서 브라우저만으로는 도저히 확인할 수 없는 통신 문제에 부딪힌 적이 한 번쯤은 있을 것입니다. 요청 헤더를 수정해야 하거나, 특정한 데이터를 POST 방식으로 보내야 하는데 브라우저 개발자 도구는 복잡하기만 하고 원하는 대로 동작하지 않죠. 마치 투명한 유리 너머로 서버를 바라보는 것 같아 답답함을 느낄 때가 많습니다.

함께 보면 좋은 글: 맥에서 SSH 키 만들고 GitHub 연동할 때 놓치는

이러한 불편함은 근본적으로 브라우저가 사용자의 편의를 위해 HTTP 요청의 세부 사항을 추상화하고 숨겨두기 때문에 발생합니다. 하지만 개발자가 되어서는 브라우저의 '간편함' 뒤에 숨겨진 '진실'을 확인해야 할 때가 있습니다. 서버와 직접 대화하듯 명령을 내리고 결과를 확인하려면 별도의 도구가 필수적입니다.

이 글에서는 터미널에서 서버와 통신하는 모든 제어권을 쥐어주는 curl 명령어의 실전 사용법을 상세히 설명합니다. 단순한 요청을 넘어 인증, 데이터 전송, 그리고 까다로운 디버깅까지 개발 현장에서 즉시 적용할 수 있는 구체적인 내용을 다룹니다. 브라우저가 숨겨놓은 서버의 비밀을 파헤쳐 보세요.

curl의 기본 작동 원리와 GET 요청

curl은 URL 구문을 사용하여 데이터를 전송하거나 가져오는 도구입니다. 기본적으로 curl은 HTTP 프로토콜을 지원하며, FTP, SMTP, LDAP 등 다양한 프로토콜도 처리할 수 있는 만능 통신 도구입니다. 가장 단순한 형태는 아무 옵션 없이 URL을 입력하는 것이며, 이 경우 서버로부터 받은 응답 내용을 표준 출력(터미널 화면)에 그대로 출력합니다. 예를 들어, 웹 서버의 응답 속도나 상태를 빠르게 확인하고 싶을 때 유용합니다.

curl 8.7.1 버전 기준으로, 옵션을 지정하지 않으면 기본적으로 HTTP GET 메서드를 사용합니다. 만약 특정 포트 번호를 사용하는 서버에 접속해야 한다면 URL 뒤에 콜론과 함께 포트 번호를 명시해야 합니다. 예컨대 로컬 개발 환경에서 구동 중인 Node.js 서버가 3000번 포트를 사용한다면 http://localhost:3000으로 요청을 보내야 합니다.

웹 서버가 정상적으로 동작하는지 확인할 때는 HTTP 상태 코드가 중요합니다. curl은 요청 완료 후 종료 코드를 반환하는데, 이를 통해 통신 성공 여부를 판단할 수 있습니다. 하지만 화면에 HTML 소스만 쏟아내기 때문에, 상태 코드를 직관적으로 확인하려면 추가적인 옵션이 필요합니다.

curl https://www.example.com
curl http://192.168.1.15:8080/status

실제 운영 환경에서는 단순히 내용을 확인하는 것보다 서버의 헤더 정보나 상태 코드를 확인하는 경우가 많습니다. 이때는 -I 옵션을 사용하여 HEAD 요청을 보낼 수 있습니다. 이 옵션을 사용하면 본문 내용을 제외하고 응답 헤더만 가져오므로, 서버의 버전이나 캐시 정책을 빠르게 파악할 수 있습니다. 예를 들어, 특정 API가 200 OK를 반환하는지 확인할 때 수 메가바이트 이상의 JSON 데이터를 다운로드하는 것보다 헤더만 확인하는 것이 훨씬 효율적입니다.

POST 메서드와 데이터 전송 기법

데이터를 생성하거나 수정할 때는 POST 메서드를 사용해야 합니다. curl에서 POST 요청을 보내기 위해서는 -X POST 옵션을 명시하거나, 데이터를 전송하는 옵션(-d 등)을 사용하면 자동으로 POST 요청으로 변환됩니다. 데이터 전송 방식은 크게 폼 데이터 방식과 JSON 방식으로 나뉘며, 서버의 API 명세에 맞춰 적절한 방식을 선택해야 합니다.

웹 폼처럼 application/x-www-form-urlencoded 타입으로 데이터를 보낼 때는 -d 옵션 뒤에 키와 값을 쌍으로 입력합니다. 여러 개의 데이터를 보낼 때는 -d 옵션을 반복해서 사용하거나 & 기호로 연결할 수 있습니다. 예를 들어, 사용자 로그인을 시도할 때 아이디와 비밀번호를 전송하는 시나리오를 생각해 볼 수 있습니다.

curl -X POST -d "userId=admin&password=secret123" https://api.example.com/login

최근의 REST API는 주로 JSON 형식을 사용합니다. JSON 데이터를 전송할 때는 -H 옵션으로 Content-Type 헤더를 application/json으로 설정하고, -d 옵션 뒤에 JSON 문자열을 입력해야 합니다. 이때 데이터에 공백이 포함되어 있으므로 전체 인자를 따옴표로 감싸는 것이 중요합니다. 만약 데이터가 매우 크다면 파일에서 읽어오는 -d @filename.json 방식을 사용하는 것이 좋습니다.

헤더와 인증 정보를 다루는 방법

API를 호출할 때 가장 많이 발생하는 에러는 인증 실패입니다. 대부분의 최신 API는 요청 헤더에 인증 토큰이나 API 키를 포함하도록 요구합니다. curl에서는 -H 또는 --header 옵션을 사용하여 커스텀 헤더를 추가할 수 있습니다. 예를 들어, JWT(JSON Web Token)를 사용하는 서비스에 접근할 때는 Authorization: Bearer [토큰값] 형식의 헤더를 반드시 포함해야 합니다.

기본 인증(Basic Authentication)을 사용하는 레거시 시스템의 경우, 사용자 이름과 비밀번호를 Base64로 인코딩하여 헤더에 넣어야 합니다. curl은 이 과정을 -u 옵션 하나로 자동 처리해 줍니다. -u username:password 형식으로 입력하면 curl이 자동으로 Authorization 헤더를 생성하여 요청을 보냅니다. 보안상 비밀번호가 터미널 히스토리에 남지 않도록 주의해야 하며, 가능하다면 환경 변수를 활용하는 것이 좋습니다.

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." https://api.service.com/v1/users
curl -u admin:secretpass https://secure.example.com/admin

특정 상황에서는 웹 브라우저인 척 가장해야 하는 경우도 있습니다. 서버가 봇이나 스크립트의 접근을 차단할 때 User-Agent 헤더를 변경하면 이를 우회할 수 있습니다. 일반적인 크롬 브라우저의 User-Agent 문자열을 헤더에 포함하여 보내면 서버가 정상적인 브라우저 요청으로 인식할 확률이 높습니다. 한 사용자는 이 방법을 사용하여 서버의 403 Forbidden 에러를 해결하고 데이터를 정상적으로 크롤링했다고 보고한 바 있습니다.

응답 데이터 처리 및 디버깅 전략

서버에서 반환하는 데이터의 양이 많거나, JSON 형식으로 예쁘게 출력하고 싶을 때가 있습니다. curl의 기본 출력은 압축된 한 줄의 문자열이라 가독성이 떨어집니다. 이때는 jq 같은 도구와 파이프라인(|)를 연결하면 JSON 데이터를 계층 구조로 보기 좋게 정렬할 수 있습니다. 만약 jq가 설치되어 있지 않다면 curl 자체의 기능만으로도 충분히 디버깅이 가능합니다.

디버깅을 위해서는 -v (verbose) 옵션이 필수적입니다. 이 옵션을 사용하면 curl이 서버로 보내는 요청 라인, 헤더, 그리고 서버로부터 받는 응답 헤더까지 모두 화면에 출력합니다. 요청 헤더 앞에는 > 기호가, 응답 헤더 앞에는 < 기호가 붙어 구분할 수 있습니다. 이를 통해 내가 의도한 헤더가 정확히 나갔는지, 서버가 어떤 상태 코드(예: 401 Unauthorized, 500 Internal Server Error)를 돌려주었는지 명확히 알 수 있습니다.

curl -v https://api.test.com/debug
curl https://api.test.com/data | jq .

또한, 응답 데이터를 파일로 저장해야 하는 경우가 많습니다. -o 옵션은 저장할 파일 이름을 직접 지정할 때 사용하고, -O (대문자) 옵션은 서버의 파일 이름을 그대로 사용하여 저장합니다. 예를 들어, 대규모 로그 파일이나 이미지를 다운로드받을 때 -o를 활용하면 진행률을 시각적으로 확인하면서 저장할 수 있습니다.

흔히 하는 실수와 주의점

curl 사용법은 간단해 보이지만, 명령어의 특성상 쉘이 파라미터를 해석하는 방식 때문에 의도치 않은 오류가 발생하기 쉽습니다. 특히 초보 개발자들이 가장 많이 겪는 세 가지 함정을 피하는 방법을 알아보겠습니다.

1. 따옴표(Quote)를 생략하여 발생하는 데이터 파괴
JSON 데이터를 전송할 때 가장 많이 하는 실수는 따옴표를 빼먹는 것입니다. 쉘 환경에서 공백은 인자를 구분하는 구분자로 인식됩니다. 아래와 같이 따옴표 없이 JSON을 보내면, 공백을 기준으로 데이터가 쪼개져 서버는 완전히 다른 엉뚱한 데이터를 받게 됩니다.

# 잘못된 예: 데이터가 쪼개져서 전송됨
curl -d {name: John Doe} https://api.example.com/users

# 올바른 예: 전체 데이터를 하나의 문자열로 처리
curl -d '{"name": "John Doe"}' https://api.example.com/users

2. 리다이렉트(Redirect)를 따라가지 못하는