Claude Code CLI 파헤치기 —
터미널 명령어와 옵션,
겁내지 않고 익히기

저는 코딩을 늦게 시작한 사람입니다. 그래서 오래도록 '검은 화면'이 무서웠어요. 영화에서 해커들이 뭔가 다다닥 치면 초록 글씨가 좌르륵 올라가던 그 화면 말입니다. 저건 나 같은 사람이 건드리는 물건이 아니라고, 잘못 만졌다가 컴퓨터가 망가질 거라고 진심으로 믿었습니다. 마우스로 아이콘 클릭하는 것도 겨우 하는 사람이었으니까요.

그런데 Claude Code라는 도구를 쓰기 시작하면서 그 검은 화면을 매일 열게 됐습니다. 처음엔 손이 떨렸어요. 근데 며칠 지나니까 알겠더라고요. 이 검은 화면, 사실은 대단히 정중하고 예측 가능한 친구였습니다. 제가 정확한 '한마디'를 하면 정확히 그 일만 합니다. 시키지 않은 일은 절대 안 해요. 오히려 마우스로 여기저기 클릭하는 것보다 훨씬 안전하고 빠르더군요.

이 글은 Claude Code 사용방법 개괄 글의 심화편입니다. 앞 글에서는 "Claude Code가 뭐고 무엇을 해주는가"를 큰 그림으로 다뤘어요. 혹시 안 보셨어도 괜찮습니다. 딱 한 문단으로 요약하면 이렇습니다. Claude Code는 여러분의 컴퓨터 안에 들어와서, 실제 파일을 읽고 고치고, 명령을 실행해주는 AI 코딩 조수입니다. 그리고 이 조수를 부르는 주된 통로가 바로 오늘 파헤칠 CLI(터미널 명령어)예요. 오늘은 그 검은 화면에서 명령어와 옵션으로 이 조수를 자유자재로 부리는 법에 집중합니다.

CLI는 마우스 없이 '말 한마디(명령어)'로 시키는 리모컨입니다. 처음엔 버튼 하나 안 보이는 검은 화면이 막막하지만, 리모컨 버튼 몇 개만 알면 채널을 다 돌릴 수 있듯, 명령어 몇 개만 익히면 Claude Code의 거의 모든 기능을 손끝에서 부릴 수 있어요.

이 리모컨 비유 하나만 챙기고 시작하세요. 오늘 나오는 모든 명령어와 옵션은 결국 "그 리모컨의 버튼들"일 뿐입니다. 겁먹지 마세요. 저도 그랬지만, 한 바퀴 돌고 나면 "이게 왜 무서웠지" 싶으실 거예요.

GUI와 CLI — 버튼을 누르느냐, 말로 시키느냐

먼저 두 세계를 구분해 봅시다. 우리가 평소 쓰는 컴퓨터는 대부분 GUI(그래픽 사용자 인터페이스)입니다. 아이콘이 있고, 버튼이 있고, 마우스로 클릭하죠. 폴더를 열려면 폴더 그림을 더블클릭하고, 파일을 지우려면 휴지통으로 끌어다 놓습니다. 눈에 보이는 걸 손으로 만지는 방식이에요. 직관적이고, 배우기 쉽습니다.

반면 CLI는 Command Line Interface, 우리말로 '명령줄 인터페이스'입니다. 화면에 버튼이 없어요. 대신 글자로 명령을 '적어서' 엔터를 칩니다. 폴더를 열려면 cd 폴더이름이라고 타이핑하고, 파일 목록을 보려면 ls라고 칩니다. 마우스 대신 '글자 명령'으로 컴퓨터에 지시하는 방식이에요.

여기서 많은 분이 궁금해합니다. "버튼 클릭이 더 쉬운데, 왜 개발자들은 굳이 저 불편해 보이는 검은 화면을 쓰나요?" 좋은 질문이에요. 이유는 세 가지입니다.

정리하면, CLI는 빠르고, 반복 자동화가 되고, 여러 도구를 레고처럼 조립할 수 있습니다. 이게 개발자들이 검은 화면을 사랑하는 이유예요. 그리고 Claude Code가 CLI를 주 무대로 삼은 것도 같은 이유입니다. AI 조수를 '자동화의 컨베이어 벨트'에 끼워 넣으려면 명령어로 다룰 수 있어야 하거든요. 이 부분은 뒤에서 아주 재미있게 다룰 예정입니다.

터미널이 대체 뭔가요 — 겁부터 빼드립니다

CLI 명령을 입력하는 그 '검은 화면'의 정식 이름이 터미널(Terminal)입니다. 윈도우에서는 'PowerShell'이나 '터미널', 맥에서는 '터미널(Terminal)'이라는 앱이 그 역할을 해요. 이름은 거창하지만, 하는 일은 단순합니다. 여러분이 글자로 적은 명령을 컴퓨터에 전달하고, 컴퓨터의 대답을 글자로 보여주는 창구일 뿐이에요. 은행 창구 직원 같은 거라고 생각하시면 됩니다. 제가 "잔액 조회요" 하면 창구가 컴퓨터에 물어보고 결과를 알려주는 거죠.

터미널을 처음 열면 보통 이런 게 깜빡이고 있습니다. 사용자 이름과 폴더 위치가 적힌 짧은 글자 뒤에 커서가 반짝이는 모습이에요. 이걸 프롬프트(prompt)라고 부릅니다. "자, 명령을 입력하세요"라고 기다리고 있는 상태예요. 여기에 명령을 타이핑하고 엔터를 치면 실행됩니다. 그게 전부예요. 정말입니다.

제가 초보 시절 가장 도움이 됐던 마음가짐은 "터미널은 대화창이다"라고 생각한 겁니다. 카카오톡에 메시지 치고 엔터 누르면 상대가 답하듯, 터미널에 명령 치고 엔터 누르면 컴퓨터가 답합니다. Claude Code를 쓰면 이 비유가 진짜가 돼요. 터미널 안에서 정말로 AI와 대화하게 되거든요. "이 파일 뭐가 문제야?"라고 한글로 쳐도 알아듣습니다.

설치와 버전 확인 — 첫 단추 끼우기

이제 리모컨을 손에 쥐어봅시다. Claude Code를 설치하는 방법인데요, 여러분의 컴퓨터 종류(운영체제)에 따라 명령 한 줄만 터미널에 붙여넣으면 됩니다. 아래 단계를 따라오세요.

설치 방식에 대해 한 가지만 짚을게요. 위처럼 설치 스크립트(install.sh / install.ps1)로 까는 방식을 '네이티브 설치'라고 부르는데, 이렇게 설치하면 자동 업데이트가 됩니다. 즉 새 기능이 나오면 여러분이 신경 안 써도 알아서 최신으로 유지돼요. 그래도 가끔은 claude --version으로 버전을 확인하는 습관을 들이면 좋습니다.

시작하기 — 폴더로 이동한 뒤 부른다

설치가 끝났으면 이제 Claude Code를 실제로 불러봅시다. 순서가 중요한데요, 먼저 작업할 프로젝트 폴더로 이동한 다음 Claude Code를 실행해야 합니다. 왜냐하면 Claude Code는 "지금 내가 서 있는 폴더"를 작업 공간으로 인식하거든요. 엉뚱한 폴더에서 부르면 엉뚱한 파일들을 보게 됩니다.

순서는 이렇습니다. 먼저 cd 프로젝트경로로 원하는 폴더에 들어갑니다(cd는 change directory, '폴더 바꾸기'예요). 그다음 claude라고만 치고 엔터. 처음 실행하면 로그인 절차를 안내해줍니다. 화면 안내를 따라 계정 인증을 한 번 해두면, 그다음부터는 claude만 쳐도 바로 대화가 시작돼요.

대화형이냐, 한 방이냐 — 세 가지 부르는 법

Claude Code를 부르는 방식은 크게 세 가지입니다. 이 차이를 아는 게 CLI 활용의 절반이에요. 리모컨으로 치면 "TV를 켜고 앉아서 이것저것 돌려보기"와 "리모컨으로 채널 하나 딱 틀고 끄기"의 차이라고 보시면 됩니다.

세 번째 -p가 처음엔 낯설 텐데, 아주 중요합니다. -p는 'print(출력)'의 약자예요. 대화창을 열지 않고 답 한 번만 딱 뱉고 종료합니다. 사람이 앉아서 대화하는 게 아니라, 다른 프로그램이 Claude를 불러 쓰기에 딱 좋은 모드라 '헤드리스(headless, 머리 없는)'라고도 불러요. 사람 얼굴(대화창) 없이 결과만 나온다는 뜻입니다. 이게 왜 강력한지는 뒤의 '파이프·CI' 섹션에서 무릎을 치실 거예요.

정리하면, 곁에 앉아 함께 작업할 땐 claude, 할 일이 정해졌으면 claude "...", 한 번 묻고 끝내거나 자동화에 넣을 땐 claude -p "...". 이 세 개만 구분해도 절반은 온 겁니다.

대화 이어가기 — 어제 하던 얘기 계속하기

작업을 하다 보면 터미널을 껐다가 나중에 다시 켜는 일이 잦습니다. 그때마다 "아까 우리 뭐 하고 있었죠?"를 처음부터 다시 설명하려면 답답하겠죠. 다행히 Claude Code는 대화를 이어서 할 수 있습니다. 카톡 대화방을 다시 여는 것처럼요.

-c는 continue(계속하기)의 c, -r은 resume(재개)의 r입니다. 이렇게 옵션 글자가 단어의 첫 글자인 경우가 많아서, 뜻을 알면 외우기 쉬워요. 대부분은 claude -c 하나로 충분합니다. "방금 하던 거 이어서"가 제일 흔한 상황이니까요. 여러 프로젝트나 여러 대화를 동시에 굴리는 분이라면 -r로 원하는 세션을 콕 집어 돌아가면 됩니다.

자주 쓰는 플래그 총정리

이제 리모컨의 세부 버튼들, 즉 플래그(옵션)를 정리할 차례입니다. 플래그란 명령 뒤에 붙이는 -p, --model 같은 추가 지시예요. "그냥 실행하지 말고, 이런 조건으로 실행해"라고 덧붙이는 겁니다. 짧은 형태(-c)와 긴 형태(--continue)가 같은 뜻인 경우가 많은데, 긴 쪽이 뜻이 잘 보여서 초보에겐 오히려 편할 때도 있어요.

여기 다 나온 걸 지금 외우실 필요는 전혀 없습니다. 리모컨에 버튼이 스무 개 있어도 우리가 매일 쓰는 건 전원, 채널, 볼륨 세 개뿐이잖아요. 플래그도 마찬가지예요. 초보 단계에서 실제로 손이 가는 건 -c, -p, --model 정도입니다. 나머지는 "이런 게 있었지" 하고 필요할 때 이 표로 돌아오면 됩니다.

참고로 이보다 더 나아간 기능도 있어요. 여러 작업을 백그라운드에서 동시에 돌리는 백그라운드 에이전트(--bg)나, 여러 세션을 한눈에 관리하는 claude agents 같은 것들인데요, 이건 어느 정도 손에 익은 다음에 만나도 늦지 않습니다. 지금은 "그런 것도 있구나" 정도로만 알아두세요.

셸 명령 한눈에 정리

지금까지 나온 것들과, 아직 안 나온 관리용 명령들을 한 표에 모아드릴게요. 터미널에서 claude 뒤에 붙여 쓰는 명령들입니다. 이건 대화 안에서 치는 슬래시 커맨드(다음 섹션)와는 다른, 터미널 자체에서 치는 명령이에요.

claude doctor는 이름이 재미있죠. 뭔가 이상하게 안 될 때 이걸 치면 "어디가 아픈지" 진단해줍니다. 설치가 꼬였거나 설정이 잘못됐을 때 제일 먼저 불러볼 의사 선생님이에요.

대화 안에서 쓰는 슬래시 커맨드

여기서 헷갈리기 쉬운 구분 하나. 앞의 claude ... 명령들은 터미널에서 치는 것이었어요. 그런데 일단 claude로 대화가 시작되고 나면, 그 대화창 안에서 쓰는 특별한 명령이 따로 있습니다. 이걸 슬래시 커맨드라고 불러요. 앞에 빗금(/)을 붙여 쓰기 때문입니다. 게임 채팅창에서 /귓속말 치는 것과 똑같은 감각이에요.

이 표를 외우실 필요도 없어요. 왜냐하면 대화창에서 / 한 글자만 쳐보면 쓸 수 있는 명령과 기능(스킬) 목록이 좌르륵 뜨거든요. 거기서 골라 쓰면 됩니다. 그리고 명령 이름을 몇 글자 치다가 Tab 키를 누르면 나머지를 자동으로 완성해줍니다. 오타 걱정도, 다 외워야 하는 부담도 없는 거죠.

몇 가지 더 편한 조작을 알려드릴게요. ↑(위 화살표)를 누르면 방금 전에 쳤던 명령들을 다시 불러올 수 있습니다(히스토리). 같은 명령을 또 칠 때 처음부터 안 쳐도 돼요. 그리고 Shift+Tab을 누르면 권한 모드가 차례로 바뀝니다. 이게 뭔지는 바로 다음 섹션에서 다룹니다.

권한 모드 — Claude에게 얼마나 자유를 줄까

이건 정말 중요한 개념이라 천천히 갑니다. Claude Code는 여러분의 실제 파일을 고치고, 실제로 명령을 실행할 수 있는 힘이 있어요. 그래서 "어디까지 마음대로 하게 둘 것인가"를 정하는 장치가 필요합니다. 그게 권한 모드예요. 회사로 치면 신입 직원에게 결재 권한을 얼마나 줄지 정하는 것과 같습니다.

초보라면 default로 시작하시길 권합니다. Claude가 뭘 하려는지 매번 눈으로 확인하면서, 이 도구가 어떻게 일하는지 감을 익히는 게 먼저예요. 손에 익고 신뢰가 쌓이면 acceptEdits로 넘어가 속도를 높이면 됩니다. 그리고 뭔가 큰 작업을 시키기 전에는 plan 모드로 "계획부터 보여줘"라고 해보세요. 실제로 손대기 전에 청사진을 볼 수 있어서 사고를 크게 줄여줍니다.

모드는 앞서 말한 Shift+Tab으로 대화 도중에 빙글빙글 순환하며 바꿀 수 있고, 처음 시작할 때 --permission-mode 플래그로 지정할 수도 있습니다.

진짜 강력한 곳 — 파이프, 스크립트, 그리고 CI

자, 여기가 오늘의 하이라이트입니다. 앞에서 "CLI는 도구를 레고처럼 조립할 수 있다"고 했죠? 이게 왜 대단한지 이제 보여드릴게요. 유닉스라는 오래된 철학에 이런 게 있습니다. "작은 도구들을 파이프(|)로 이어 붙여 큰일을 하라." 파이프는 앞 명령의 결과를 뒤 명령에게 넘겨주는 관(파이프라인)입니다. 물이 관을 타고 흐르듯, 데이터가 명령에서 명령으로 흘러가요.

그리고 아까 배운 claude -p(헤드리스)를 이 파이프에 끼워 넣으면, Claude가 갑자기 '조립 가능한 부품'이 됩니다. 예시를 볼게요.

서버 로그의 마지막 200줄을 Claude에게 보여주고 이상한 게 있는지 물어보고 싶다면 이렇게 씁니다. tail -200 app.log | claude -p "이상 있으면 알려줘". 여기서 tail -200 app.log가 로그 끝 200줄을 뽑아내고, 파이프(|)가 그걸 claude -p에게 넘기면, Claude가 그 내용을 읽고 답합니다. 사람이 로그를 눈으로 훑을 필요가 없어진 거예요.

또 하나. 어떤 파일들이 바뀌었는지 목록을 뽑아 보안 관점에서 검토받고 싶다면 git diff main --name-only | claude -p "이 파일들 보안 관점에서 리뷰해줘"처럼 씁니다. 바뀐 파일 목록이 Claude에게 흘러 들어가서, Claude가 보안 리뷰를 해주는 거죠.

이걸 자동화 파이프라인에 넣으면 진가가 드러납니다. 아래 흐름을 보세요.

여기서 CI라는 말이 나옵니다. CI는 코드를 자동으로 검사하고 이어주는 자동화 시스템인데요, 여기에 Claude를 끼워 넣을 수 있어요. 예를 들어 CI에서 claude -p "새 문자열을 프랑스어로 번역하고 PR 올려줘" 같은 명령을 돌리면, 코드가 올라올 때마다 Claude가 자동으로 번역해서 수정 제안(PR)까지 올려줍니다. 사람은 자는 동안에도요.

이 자동화 세계가 궁금하시면 GitHub Actions로 자동화 로봇 두는 법과 CI/CD 이야기를 함께 보세요. Claude Code의 -p 모드는 바로 그 자동화 컨베이어 벨트에 얹는 'AI 부품'이라고 보시면 딱 맞습니다. 개념(CI/CD)과 도구(Actions)를 알면, 오늘 배운 claude -p가 어디에 꽂히는지 그림이 완성돼요.

MCP와 플러그인 — 외부 도구 연결하기 한 줄

Claude Code는 자기 혼자 일하지 않고, 외부 도구와 손을 잡을 수 있습니다. 이 연결 규격을 MCP라고 불러요. 쉽게 말하면 "Claude가 다른 앱이나 서비스에 팔을 뻗어 정보를 가져오거나 작업하게 해주는 콘센트"입니다. 예컨대 특정 데이터베이스나 외부 서비스에 Claude를 연결해두면, 대화 중에 그 도구를 활용할 수 있게 돼요.

설정은 터미널에서 claude mcp, 대화 중에는 /mcp로 상태를 보고 관리합니다. 다만 MCP와 플러그인의 자세한 개념과 설정법은 그것만으로 글 한 편 분량이라, 오늘은 "이런 연결 통로가 있고, claude mcp / /mcp로 다룬다"까지만 알고 넘어가겠습니다. 필요해지면 관련 글에서 깊이 다룰게요.

어떤 모델(두뇌)을 고를까 — --model 이야기

플래그 표에서 --model을 보고 "모델이 여러 개야?" 하셨을 수 있어요. 맞습니다. Claude Code는 상황에 따라 서로 다른 성격의 '두뇌'를 골라 쓸 수 있습니다. 흔히 이름으로 sonnet, opus, haiku 같은 것들이 등장하는데요, 아주 거칠게 비유하면 이렇습니다. 급하고 간단한 심부름엔 날쌘 직원, 복잡하고 머리 아픈 일엔 노련한 베테랑, 이런 식으로 일에 맞는 사람을 부르는 거예요.

초보 단계에서 모델을 세세하게 고민할 필요는 없습니다. 기본으로 잡혀 있는 모델로 시작해도 충분해요. 다만 "이 작업은 좀 복잡한데 답이 아쉽다" 싶을 때, 또는 반대로 "이건 아주 단순한 일이라 빨리만 되면 된다" 싶을 때, 모델을 바꿔볼 수 있다는 것만 기억하세요. 바꾸는 방법은 두 가지입니다. 시작할 때 claude --model opus처럼 플래그로 지정하거나, 대화 도중에 /model을 쳐서 갈아 끼우면 됩니다.

첫 실전 5분 — 진짜로 한번 시켜보기

이론은 충분히 봤으니, 이제 상상 속에서라도 한 번 따라 해봅시다. 여러분이 작은 프로젝트 폴더 하나를 갖고 있다고 치고, 처음부터 끝까지 흐름을 그려볼게요. 이 다섯 단계만 해보면 오늘 배운 게 몸에 붙습니다.

어떠세요, 생각보다 무섭지 않죠? 이 다섯 단계 안에 오늘 배운 핵심이 거의 다 들어 있습니다. cd로 이동, plan으로 계획, default로 승인하며 실행, /help로 길찾기, -c로 이어가기. 나머지 플래그와 옵션은 이 뼈대에 살을 붙이는 것뿐이에요.

초보가 흔히 하는 실수 & 해결

제가 직접 겪었거나, 주변에서 자주 본 실수들을 모아봤습니다. 미리 알아두면 같은 함정에 안 빠질 수 있어요.

이 중에서 딱 하나만 새기시라면, 세 번째입니다. AI가 만든 결과를 사람이 검토하는 관문을 없애지 마세요. Claude는 놀랍도록 똑똑하지만, 여러분 프로젝트의 사정을 100% 알지는 못합니다. 특히 -p로 자동화할수록 '사람 눈'이라는 안전장치가 더 소중해져요.

자주 묻는 질문(FAQ)

Q. 터미널(검은 화면) 자체가 무서워요. 꼭 써야 하나요?
A. 저도 그랬습니다. 그런데 터미널은 여러분이 엔터를 누르기 전엔 아무 일도 안 하는, 아주 참을성 많은 창구예요. 명령을 잘못 쳐도 대부분 "그런 명령 없다"는 한 줄로 끝납니다. Claude Code는 오히려 그 안에서 한글로 대화할 수 있으니, 터미널과 친해지는 가장 부드러운 입구가 되어줄 거예요. 며칠이면 익숙해집니다.

Q. 저는 윈도우를 쓰는데, 윈도우도 되나요?
A. 네, 됩니다. 윈도우에서는 PowerShell에서 irm https://claude.ai/install.ps1 | iex로 설치하거나, WinGet을 쓴다면 winget install Anthropic.ClaudeCode로 설치할 수 있어요. 리눅스 환경(WSL)을 쓰는 분은 맥·리눅스와 동일하게 curl 설치 스크립트를 쓰면 됩니다.

Q. 명령과 옵션을 다 외워야 하나요?
A. 전혀요. 대화창에서 / 한 글자만 치면 명령 목록이 뜨고, Tab을 누르면 자동완성됩니다. /help는 언제든 도움말을 보여주고요. 실제로 매일 쓰는 건 claude, claude -c, claude -p 정도예요. 나머지는 필요할 때 이 글로 돌아오시면 됩니다.

Q. claude, claude "작업", claude -p "질문"의 차이가 계속 헷갈려요.
A. 이렇게 기억하세요. claude는 "앉아서 같이 일하자"(대화형), claude "작업"은 "이것부터 하면서 같이 일하자"(첫 지시 던지며 대화형), claude -p "질문"은 "한 번만 답하고 끝"(헤드리스). 앞의 둘은 대화창이 열려 있고, 마지막 하나는 답만 뱉고 바로 종료됩니다.

Q. 대화를 껐는데 아까 하던 작업을 이어서 하고 싶어요.
A. claude -c(또는 claude --continue)를 치면 가장 최근 대화를 그대로 이어갑니다. 여러 작업을 오갔다면 claude -r로 원하는 세션을 골라 돌아갈 수 있어요. 카톡 대화방을 다시 여는 것과 같습니다.

마무리 체크리스트

오늘 검은 화면을 한 바퀴 돌아봤습니다. 처음의 그 막막함이 조금은 걷혔길 바라요. 마지막으로 손에 쥐고 갈 체크리스트를 정리합니다.

• ✅ CLI = 마우스 없이 '명령어 한마디'로 시키는 리모컨. 터미널은 참을성 많은 창구다
• ✅ 설치 후 claude --version으로 확인. 네이티브 설치는 자동 업데이트된다
• ✅ cd 폴더로 이동한 뒤 claude 실행. 폴더를 꼭 확인할 것
• ✅ 부르는 법 셋: claude(대화형) · claude "작업"(첫 지시) · claude -p(한 방·자동화)
• ✅ 이어가기: -c(최근) · -r(세션 지정)
• ✅ 대화창 안에서는 /·Tab·↑·Shift+Tab. 막히면 /help
• ✅ 권한은 default로 시작. --dangerously-skip-permissions는 봉인
• ✅ -p는 파이프·CI에 끼우는 'AI 부품'. 단, 결과는 사람이 검토
• ✅ 이상하면 claude doctor로 진단

저는 코딩을 늦게 시작했고, 그 검은 화면이 진심으로 무서웠던 사람입니다. 그런 제가 지금은 터미널에서 AI 조수에게 한글로 일을 시키고 있어요. 여러분이 못 할 이유가 하나도 없습니다. 오늘 배운 명령 중 딱 세 개, claude, claude -c, /help만 오늘 저녁에 한 번씩 쳐보세요. 그 세 번이면 검은 화면과 악수한 겁니다. 별거 아니에요. 저도 그랬거든요.

더 큰 그림이 궁금하시면 개괄편인 Claude Code 사용방법으로 돌아가 보시고, 오늘 마지막에 다룬 자동화가 당겼다면 GitHub Actions와 CI/CD 이야기로 이어가세요. 다음 글에서는 Claude Code에 외부 도구를 연결하는 MCP를 초보 눈높이로 풀어볼 예정입니다.

(2026년 8월 기준으로 작성했습니다 — 명령과 플래그는 바뀔 수 있으니 code.claude.com 공식 문서와 대화창의 /help를 함께 확인하세요.)

← 기술 블로그 목록으로