Claude Code CLI 터미널 코딩 에이전트 설치 및 실행하기

Claude Code CLI, 터미널로 들어온 AI 코딩 에이전트

요즘 터미널 창을 열고 Claude Code CLI를 바로 실행하는 개발자들이 눈에 띄게 늘었습니다. Anthropic이 공식적으로 내놓은 이 도구는 브라우저나 무거운 IDE를 거치지 않고 로컬 컴퓨터의 파일과 직접 연동하는 코딩 에이전트입니다. 직접 써보면 코드 수정은 물론이고 깃 커밋이나 에러 분석까지 쉘 위에서 한 번에 이어지는 느낌이 꽤 새롭습니다. 매달 나가는 API 비용은 부담될 수 있지만, 작업 흐름이 빨라지는 만큼 환경을 한 번 구축해 볼 가치는 충분하다고 봅니다.

가장 큰 매력은 컨텍스트를 알아서 파악하고 움직인다는 점입니다. 폴더 안의 수많은 코드를 일일이 프롬프트창에 복사해서 붙여넣을 필요가 없습니다. 그저 터미널에서 명령 한 줄만 입력하면 로컬 프로젝트 구조를 바로 짚어냅니다. 이런 매끄러운 사용성이 이 도구를 계속 켜두게 만드는 이유입니다.

Claude Code CLI 설치부터 연동까지의 5단계

이 에이전트를 내 로컬 환경에 올리고 첫 명령을 실행하기까지는 생각보다 간단합니다. Node.js 환경만 준비되어 있으면 NPM 명령어로 빠르게 세팅할 수 있습니다.

Step 1: Node.js 버전 확인과 설치

우선 컴퓨터에 설치된 Node.js 버전을 확인해야 합니다. Claude Code CLI는 최신 기능을 많이 쓰기 때문에 Node 18 버전 이상이 필요합니다. 터미널을 열고 아래 명령어를 입력해 보세요.

만약 출력이 v18 미만이거나 명령어를 찾을 수 없다고 나오면 공식 홈페이지에서 최신 LTS 버전을 내려받아 다시 설치해야 합니다. 20 버전 이상으로 맞춰 두면 나중에 패키지 오류를 줄이는 데 도움이 됩니다.

Step 2: 글로벌 패키지 설치

Node 준비가 끝났다면 NPM으로 에이전트를 전역 설치할 차례입니다. 터미널에 아래 명령어를 입력하면 수 초 안에 로컬 패키지가 설치됩니다.

설치 중 권한 오류가 나면서 진행이 멈추는 경우가 있습니다. 맥이나 리눅스에서는 앞에 sudo를 붙여 관리자 권한으로 실행하면 되고, 윈도우에서는 PowerShell을 관리자 권한으로 열고 다시 시도하면 됩니다.

Step 3: Anthropic API 계정 인증하기

설치가 끝났다고 바로 사용이 되는 것은 아닙니다. 에이전트가 내 계정의 Claude 모델과 통신할 수 있도록 API 인증을 거쳐야 합니다. 아래 명령어를 실행해 보세요.

처음 실행하면 브라우저 창이 열리면서 로그인이나 API 키 확인 절차가 진행됩니다. 화면에 나오는 인증 코드를 터미널에 그대로 입력하면 세션이 연결됩니다. 기존처럼 환경 변수를 길게 맞춰 넣는 과정이 줄어들어서 훨씬 편하게 시작할 수 있습니다.

Step 4: 프로젝트 폴더에서 활성화하기

인증이 끝났다면 작업 중인 코드 디렉토리로 이동합니다. 터미널에서 cd 명령어로 원하는 폴더에 들어간 뒤 다시 claude를 실행하면 프로젝트 구조를 분석하기 시작합니다.

에이전트가 로컬 디렉토리를 훑고 준비를 마치면 프롬프트 입력창이 나타납니다. 여기서부터는 실제 작업을 요청하는 단계로 넘어갑니다.

Step 5: 첫 질문으로 기능 테스트하기

입력창에 가볍게 프로젝트 분석을 요청해 보세요. 소스코드의 구조가 어떻게 잡혀 있는지 묻는 방식이 가장 직관적입니다.

파일을 읽고 각 함수와 모듈의 관계를 정리해 줄 겁니다. 답변의 형태와 속도를 보면서 앞으로 어떤 식으로 업무에 활용할지 감을 잡으면 됩니다.

자주 막히는 설치 및 실행 오류

설치 과정 자체는 단순하지만, 터미널 환경이 제각각이라 몇 가지 문제에 부딪히는 경우가 있습니다. 특히 API 계정의 결제 상태나 Node 경로 꼬임이 대표적입니다.

가장 빈번하게 나타나는 문제는 API 키에 크레딧이 부족해서 요청이 거부되는 오류입니다. Claude Code CLI는 우리가 흔히 쓰는 월 20달러의 Claude Pro 구독과는 별개로 동작하며, API 계정의 결제 카드에 선불 크레딧이 들어 있어야 합니다. 사용량이 갑자기 늘 수 있으니 한도(Usage Limit)를 타이트하게 걸어 두는 편이 안전합니다. 충전이 안 되어 있으면 통신 요청 단계에서 API Key 오류가 뜬다는 점을 기억해 두면 좋습니다.

설치 명령어 자체를 찾지 못한다면 npm의 글로벌 bin 경로가 시스템 환경 변수 Path에 잡혀 있는지 확인해 보세요. 윈도우에서는 AppData 아래 npm 폴더 주소를 환경 변수에 추가해야 작동하는 경우가 있습니다.

Cursor 대신 언제 쓰면 좋을까

저는 자잘한 버그를 고치거나 파일 여러 개를 동시에 정리할 때 굳이 에디터를 열지 않고 씁니다. 터미널에서 바로 코드 리뷰와 git commit 메시지 작성까지 이어지니 작업 흐름이 끊기지 않는 점이 가장 큽니다. 반면에 한 화면에서 UI 레이아웃을 보면서 긴 프롬프트를 짜거나 정교하게 편집할 때는 Cursor가 더 편할 수 있습니다.

결국 한쪽만 고집하기보다 개발 흐름에 맞춰 도구를 섞어 쓰는 편이 자연스럽습니다. 이번에 세팅을 마쳤다면 매일 하는 커밋이나 간단한 리팩토링 테스트 용도로 먼저 가볍게 써 보는 게 좋습니다.

Claude Code CLI는 설치만 해 두면 터미널 안에서 작업 흐름을 꽤 단순하게 만들어 줍니다. Node 버전 확인, 글로벌 설치, API 인증, 프로젝트 활성화, 첫 질문까지 순서대로만 따라가면 초보자도 바로 시작할 수 있습니다. 터미널 중심으로 코딩하는 습관이 있다면 Claude Code CLI는 충분히 실용적인 선택입니다.