클로드 코드는 터미널 환경에서 바로 코드를 작성하고 수정할 수 있게 해주는 앤트로픽의 커맨드라인 도구예요. 별도의 무거운 IDE 설치 없이도 터미널에서 자연어로 지시를 내려 코드를 만들거나 고칠 수 있다는 점 때문에 개발자들 사이에서 관심이 커지고 있어요. 설치 전에 확인해야 할 사전 조건부터 설치, 로그인, 기본 사용법까지 순서대로 정리해볼게요.
설치 전 확인해야 할 사전 조건
클로드 코드 CLI는 Node.js 환경 위에서 동작하는 도구예요. 그래서 설치에 앞서 컴퓨터에 Node.js가 설치돼 있어야 하고, 너무 오래된 버전이면 정상적으로 동작하지 않을 수 있어요. 터미널에서 node –version 명령어로 현재 설치된 버전을 먼저 확인하는 게 첫 단계예요.
운영체제는 macOS, Linux, Windows(WSL 환경 포함)에서 모두 사용할 수 있어요. Windows에서 네이티브 터미널을 그대로 쓰기보다는 WSL(리눅스 서브시스템)을 활용하는 방식이 호환성 면에서 더 안정적이라는 이야기가 많아요.
npm을 이용한 설치 방법
Node.js 환경이 준비됐다면 npm 패키지 매니저를 이용해 전역으로 설치하면 돼요. 터미널을 열고 다음 명령어를 입력하는 방식이 가장 일반적이에요.
- 전역 설치 명령어: npm install -g @anthropic-ai/claude-code 명령어를 실행하면 시스템 전역에 클로드 코드 CLI가 설치돼요.
- 설치 확인: 설치가 끝난 뒤 claude –version 명령어로 정상적으로 설치됐는지 확인할 수 있어요.
- 권한 문제 대응: 전역 설치 과정에서 권한 오류가 발생하면 npm의 전역 설치 경로 권한을 조정하거나, 별도의 버전 관리 도구를 활용하는 방법을 고려해볼 수 있어요.
실행과 계정 로그인
설치가 끝나면 터미널에서 claude 명령어를 입력해 프로그램을 실행할 수 있어요. 처음 실행하면 계정 인증 절차가 나오는데, 이 과정에서 앤트로픽 계정으로 로그인하거나 API 키를 통해 인증하는 방식 중 하나를 선택하게 돼요.
구독 플랜을 통해 로그인하면 별도로 API 키를 발급받아 관리할 필요 없이 웹 브라우저 인증 방식으로 간편하게 연결할 수 있어요. 반대로 API 사용량 기반 과금을 원한다면 콘솔에서 발급한 API 키를 환경변수나 설정 파일에 등록하는 방식을 쓸 수 있어요.
작업 디렉터리에서 시작하기
클로드 코드는 특정 프로젝트 폴더 안에서 실행했을 때 그 폴더의 코드 구조를 인식하고 작업하는 방식으로 동작해요. 그래서 사용하려는 프로젝트 디렉터리로 이동한 뒤 claude 명령어를 실행하는 게 일반적인 사용 흐름이에요.
처음 실행하면 현재 디렉터리를 작업 공간으로 인식하겠냐는 확인 절차가 나오는 경우가 많고, 이후부터는 자연어로 “이 함수를 리팩터링해줘”처럼 지시를 내리면 코드베이스를 분석해서 수정 작업을 진행해요.
기본 명령어와 자주 쓰는 옵션
- claude: 대화형 세션을 시작해서 자연어로 코드 작업을 요청할 수 있어요.
- claude –help: 사용 가능한 전체 옵션과 플래그 목록을 확인할 수 있어요.
- claude –version: 현재 설치된 클로드 코드 CLI의 버전을 확인할 수 있어요.
세션 도중에는 파일을 직접 읽고 수정하거나, 터미널 명령어를 대신 실행해달라고 요청하는 것도 가능해요. 다만 파일 수정이나 명령어 실행처럼 실제 시스템에 영향을 주는 작업은 대부분 실행 전에 사용자 확인을 거치도록 설계돼 있어서, 의도치 않은 변경이 발생할 위험을 줄여줘요.
설치 후 자주 겪는 문제와 해결 방법
가장 흔한 문제는 Node.js 버전이 너무 낮아서 설치 자체가 실패하는 경우예요. 이럴 때는 Node.js를 최신 LTS 버전으로 업데이트한 뒤 다시 설치를 시도하면 대부분 해결돼요. 전역 설치 시 권한 오류가 발생한다면 관리자 권한으로 터미널을 실행하거나, npm의 전역 디렉터리 경로를 사용자 홈 디렉터리 하위로 재설정하는 방법도 자주 쓰이는 해결책이에요.
클로드 코드 CLI는 Node.js 환경만 준비되면 npm 명령어 한 줄로 설치할 수 있는 도구예요. 설치 후 계정 인증을 마치고, 작업하려는 프로젝트 폴더에서 claude 명령어로 세션을 시작하면 바로 자연어 기반 코딩 작업을 경험할 수 있어요.