터미널에서 효과적으로 사용하기

들어가며

이전 차시에서 Claude Code의 권한 시스템을 살펴봤다. --permission-mode 플래그로 시작 모드를 지정하고, Shift+Tab으로 모드를 전환하는 방법을 다뤘다. 이런 플래그와 단축키는 Claude Code 터미널 사용법의 일부다.

Claude Code는 터미널 네이티브 도구다. GUI가 아니라 CLI로 동작한다. 그래서 터미널의 기본 기능인 파이프, 리다이렉션, 스크립팅과 자연스럽게 결합된다. 터미널에 익숙하다면 Claude Code를 Unix 도구처럼 다른 명령과 조합해서 사용할 수 있다.

이번 차시에서는 세 가지를 다룬다. 먼저 CLI 명령어와 플래그 전체를 정리한다. 그 다음 세션 안에서 사용하는 슬래시 명령어와 키보드 단축키를 살펴본다. 마지막으로 파이프와 리다이렉션을 활용한 자동화 패턴을 알아본다.

CLI 명령어

Claude Code를 시작할 때 사용하는 명령어다. 터미널에서 claude를 입력하는 것부터 시작한다.

기본 실행

# 인터랙티브 모드 시작
claude

# 초기 프롬프트와 함께 시작
claude "이 프로젝트를 설명해줘"

# 한 번 질문하고 종료 (비대화형)
claude -p "이 함수를 설명해줘"

# 파이프로 내용 전달
cat logs.txt | claude -p "이 로그를 분석해줘"

claude만 입력하면 인터랙티브 모드로 시작한다. 대화형으로 계속 질문하고 답변을 받을 수 있다. claude "질문" 형식으로 초기 프롬프트를 전달하면 해당 질문으로 인터랙티브 세션이 시작된다.

-p 플래그(또는 --print)는 비대화형 모드다. 질문에 대한 답변을 출력하고 바로 종료한다. 스크립트나 CI/CD 파이프라인에서 사용할 때 필수적인 옵션이다.

세션 관리

# 가장 최근 세션 이어서
claude -c

# 특정 세션 재개 (ID 또는 이름)
claude -r "auth-refactor" "이 PR을 마무리해줘"

# 세션에 이름 붙이기
claude -n "auth-refactor"

# 특정 PR에 연결된 세션 재개
claude --from-pr 123

-c(또는 --continue)는 현재 디렉토리에서 가장 최근 대화를 이어간다. -r(또는 --resume)은 세션 ID나 이름으로 특정 세션을 재개한다. 인수 없이 claude --resume을 실행하면 세션 목록 피커가 열린다.

-n(또는 --name)으로 세션에 이름을 붙이면 나중에 이름으로 찾을 수 있다. 여러 작업을 동시에 진행할 때 세션을 구분하는 데 유용하다.

인증과 업데이트

# 로그인
claude auth login

# API 콘솔 계정으로 로그인
claude auth login --console

# SSO 인증
claude auth login --sso

# 로그아웃
claude auth logout

# 인증 상태 확인
claude auth status

# 최신 버전으로 업데이트
claude update

기타 명령어

# 서브에이전트 목록 확인
claude agents

# auto 모드 기본 규칙 확인
claude auto-mode defaults

# MCP 서버 설정
claude mcp

# 플러그인 관리
claude plugin install code-review@claude-plugins-official

# CI용 장기 토큰 생성
claude setup-token

CLI 플래그

claude --help에 모든 플래그가 표시되지는 않는다. --help에 없더라도 사용 가능한 플래그가 있다. 주요 플래그를 용도별로 정리한다.

모델과 성능

--model에는 sonnet, opus, haiku 같은 별칭이나 claude-sonnet-4-6 같은 전체 모델 이름을 전달할 수 있다. --effort는 low, medium, high, max(Opus 4.6 전용) 중에서 선택한다.

권한과 보안

--allowedTools와 --tools의 차이를 알아야 한다. --allowedTools는 특정 도구의 승인 프롬프트를 건너뛰게 한다. --tools는 Claude가 사용할 수 있는 도구 자체를 제한한다.

출력 형식

--output-format은 -p 모드에서 사용한다. text가 기본값이고, json은 세션 ID와 메타데이터를 포함한 구조화된 JSON을 반환한다. stream-json은 실시간으로 각 턴을 JSON 객체로 스트리밍한다.

시스템 프롬프트

--system-prompt과 --system-prompt-file은 상호 배타적이다. 대부분의 경우 --append-system-prompt를 사용하는 것이 좋다. 기본 시스템 프롬프트를 유지하면서 추가 지시만 붙이기 때문이다. --system-prompt은 Claude Code의 기본 기능(도구 사용, 파일 접근 등)을 유지할 필요가 없을 때만 사용한다.

세션 관리 플래그

스크립팅 전용 플래그

--bare는 스크립트와 CI에서 특히 유용하다. Hooks, Skills, 플러그인, MCP 서버, auto memory, CLAUDE.md 로딩을 모두 건너뛰어 시작 시간을 줄인다. --bare는 -p와 함께 사용하는 것이 권장되며, 향후 -p의 기본값이 될 예정이다.

기타 유용한 플래그

세션 내 명령어

인터랙티브 모드에서 /로 시작하는 슬래시 명령어를 사용할 수 있다. /를 입력하면 사용 가능한 모든 명령어 목록이 표시되고, 글자를 추가하면 필터링된다.

필수 명령어

/clear는 대화 기록을 삭제하고 새 세션을 시작한다. 이전 세션의 대화는 보존되어 나중에 재개할 수 있다. /compact는 컨텍스트 윈도우가 가득 찰 때 유용하다. 선택적으로 초점을 지정할 수 있다: /compact 인증 관련 내용에 초점을 맞춰.

모델과 설정

/model 명령을 실행하면 모델 선택 UI가 열린다. 왼쪽/오른쪽 화살표로 노력 수준도 조절할 수 있다. 변경은 현재 응답이 완료되기를 기다리지 않고 즉시 적용된다.

세션 관리

/resume에 인수 없이 실행하면 세션 피커가 열린다. 피커에서 사용할 수 있는 키보드 단축키가 있다.

코드 작업

/diff는 인터랙티브 diff 뷰어를 연다. 왼쪽/오른쪽 화살표로 현재 git diff와 개별 Claude 턴 사이를 전환하고, 위/아래로 파일을 탐색한다.

권한과 보안

Git 관련

기타 유용한 명령어

빠른 접두사

슬래시 명령어 외에 특수 접두사도 있다.

!를 앞에 붙이면 Claude를 거치지 않고 직접 셸 명령을 실행한다. 명령과 출력이 대화 컨텍스트에 추가되어 Claude가 결과를 참조할 수 있다. Tab을 누르면 이전 ! 명령에서 자동완성된다.

@는 파일 경로 자동완성을 트리거한다. @src/App.tsx 이 파일을 설명해줘처럼 파일 내용을 직접 대화에 포함할 수 있다. 디렉토리를 참조하면 파일 목록이 표시된다.

키보드 단축키

인터랙티브 모드에서 사용하는 단축키다.

일반 제어

모델과 기능 토글

macOS에서 Option 키 단축키를 사용하려면 터미널 설정이 필요하다.

• iTerm2: Settings → Profiles → Keys → Left/Right Option key를 “Esc+“로 설정
• Terminal.app: Settings → Profiles → Keyboard → “Use Option as Meta Key” 체크
• VS Code: "terminal.integrated.macOptionIsMeta": true 설정

텍스트 편집

여러 줄 입력

Shift+Enter가 기본적으로 동작하지 않는 터미널(VS Code, Alacritty, Zed, Warp)에서는 /terminal-setup을 실행해서 바인딩을 설치할 수 있다.

역방향 검색 (Ctrl+R)

Ctrl+R을 누르면 이전 입력을 검색할 수 있다.

1. Ctrl+R로 검색 시작
2. 검색어 입력 → 매칭 결과가 하이라이트 표시
3. Ctrl+R을 다시 누르면 이전 매칭으로 이동
4. Tab 또는 Esc로 선택 후 편집 계속, Enter로 바로 실행
5. Ctrl+C로 검색 취소

Vim 모드

/config → Editor mode에서 Vim 스타일 편집을 활성화할 수 있다. Esc로 NORMAL 모드 진입, i/a/o 등으로 INSERT 모드 진입. h/j/k/l 이동, dd 줄 삭제, yy 줄 복사, p 붙여넣기 등 일반적인 Vim 명령을 지원한다.

파이프와 리다이렉션

Claude Code는 Unix 철학을 따르는 도구다. 표준 입력(stdin)에서 데이터를 받고, 표준 출력(stdout)으로 결과를 내보낸다. 이 특성 덕분에 다른 CLI 도구와 자연스럽게 조합된다.

파이프 입력

다른 명령의 출력을 Claude에 전달할 수 있다.

# 에러 로그 분석
cat error.log | claude -p "이 에러의 근본 원인을 설명해줘"

# Git diff 리뷰
git diff | claude -p "이 변경사항을 리뷰해줘"

# 빌드 에러 분석
npm run build 2>&1 | claude -p "이 빌드 에러를 수정하는 방법을 알려줘"

# 최근 커밋 요약
git log --oneline -10 | claude -p "이 커밋들을 요약해줘"

# 변경된 파일 보안 검토
git diff main --name-only | claude -p "이 변경 파일들의 보안 이슈를 검토해줘"

파이프로 전달된 내용은 Claude의 입력에 포함된다. -p 플래그와 함께 사용해야 한다.

출력 리다이렉션

Claude의 응답을 파일로 저장할 수 있다.

# 분석 결과 저장
claude -p "이 프로젝트의 구조를 분석해줘" > analysis.md

# 에러 분석 후 저장
cat build-error.txt | claude -p "이 빌드 에러의 근본 원인을 설명해줘" > output.txt

# 표준 에러만 따로 저장
claude -p "테스트를 분석해줘" 2> errors.log

출력 형식 제어

스크립트에서 Claude의 출력을 가공해야 할 때 --output-format을 사용한다.

# 텍스트 출력 (기본값)
claude -p "프로젝트 요약" --output-format text > summary.txt

# JSON 출력 (세션 ID, 메타데이터 포함)
claude -p "코드 분석" --output-format json > analysis.json

# 스트리밍 JSON (실시간)
claude -p "로그 파싱" --output-format stream-json

JSON 출력에서 특정 필드를 추출하려면 jq를 사용한다.

# 텍스트 결과만 추출
claude -p "프로젝트 요약" --output-format json | jq -r '.result'

# 세션 ID 추출
claude -p "리뷰 시작" --output-format json | jq -r '.session_id'

구조화된 출력

--json-schema를 사용하면 JSON 스키마에 맞는 구조화된 출력을 받을 수 있다.

claude -p "auth.py에서 함수 이름을 추출해줘" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

응답의 structured_output 필드에 스키마를 따르는 데이터가 담긴다.

파이프 조합 패턴

파이프를 활용한 실전 패턴을 정리한다.

코드 리뷰 자동화:

# PR diff를 보안 관점에서 리뷰
gh pr diff "$1" | claude -p \
  --append-system-prompt "보안 엔지니어 관점에서 검토해줘" \
  --output-format json

빌드 스크립트 통합:

{
  "scripts": {
    "lint:claude": "claude -p 'main 대비 변경사항을 검토하고 오타 관련 이슈를 보고해줘'"
  }
}

커밋 자동 생성:

claude -p "스테이지된 변경사항을 확인하고 적절한 커밋을 만들어줘" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

--allowedTools의 와일드카드에서 * 앞의 공백이 중요하다. Bash(git diff *)는 git diff로 시작하는 명령에 매칭되지만, Bash(git diff*)는 git diff-index에도 매칭된다.

연속 대화 스크립트:

# 첫 번째 요청
claude -p "코드베이스의 성능 이슈를 검토해줘"

# 이전 대화 이어서
claude -p "데이터베이스 쿼리에 집중해줘" --continue

# 결과 요약
claude -p "발견된 모든 이슈를 요약해줘" --continue

여러 대화를 병렬로 관리할 때는 세션 ID를 캡처한다.

session_id=$(claude -p "리뷰 시작" --output-format json | jq -r '.session_id')
claude -p "리뷰 계속" --resume "$session_id"

환경 변수

환경 변수로 Claude Code의 기본 동작을 설정할 수 있다. 자주 사용하는 것만 정리한다.

인증

# API 키 설정
export ANTHROPIC_API_KEY="sk-..."

# 커스텀 API 엔드포인트
export ANTHROPIC_BASE_URL="https://proxy.example.com"

모델

# 기본 모델 설정
export ANTHROPIC_MODEL="claude-opus-4-6"

# 노력 수준 설정
export CLAUDE_CODE_EFFORT_LEVEL="high"

터미널 동작

# 프롬프트 제안 비활성화
export CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false

# 디버그 로그 경로
export CLAUDE_CODE_DEBUG_LOGS_DIR="/tmp/claude-debug"

# 텔레메트리 비활성화
export DISABLE_TELEMETRY=1

# 자동 업데이트 비활성화
export DISABLE_AUTOUPDATER=1

Bash 도구

# 기본 타임아웃 (밀리초)
export BASH_DEFAULT_TIMEOUT_MS=120000

# 최대 타임아웃
export BASH_MAX_TIMEOUT_MS=600000

# 셸 지정
export CLAUDE_CODE_SHELL="/bin/zsh"

컨텍스트 관리

# 자동 압축 트리거 비율 (1-100)
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=90

# 자동 압축 비활성화
export DISABLE_AUTO_COMPACT=1

백그라운드 작업

Claude Code는 Bash 명령을 백그라운드에서 실행하는 기능을 지원한다. 긴 빌드나 테스트를 실행하면서 동시에 다른 질문을 할 수 있다.

사용 방법

두 가지 방법으로 백그라운드 실행이 가능하다.

1. Claude에게 “백그라운드에서 실행해줘”라고 요청한다
2. 실행 중인 Bash 명령에서 Ctrl+B를 눌러 백그라운드로 전환한다 (tmux 사용자는 두 번 누른다)

백그라운드 작업의 출력은 파일에 기록되어 Claude가 Read 도구로 결과를 읽을 수 있다. 작업 목록은 /tasks로 확인한다.

적합한 작업

• 빌드 도구 (webpack, vite, make)
• 패키지 관리자 (npm, yarn, pnpm)
• 테스트 러너 (jest, pytest)
• 개발 서버
• 장기 실행 프로세스 (docker, terraform)

별칭 설정

자주 사용하는 명령 조합을 셸 별칭으로 등록하면 편리하다.

# ~/.zshrc 또는 ~/.bashrc

# 빠른 실행
alias cc='claude'
alias ccp='claude -p'

# 모드별 실행
alias ccplan='claude --permission-mode plan'
alias ccauto='claude --permission-mode acceptEdits'

# Git 통합
alias gcr='git diff | claude -p "이 변경사항을 리뷰해줘"'
alias gcs='git diff --staged | claude -p "이 스테이지된 변경사항을 요약해줘"'

배치 처리

여러 파일을 일괄 처리할 수 있다.

# 여러 파일에 문서 추가
for file in src/**/*.ts; do
  claude -p "이 파일에 JSDoc을 추가해줘: $file" --bare --allowedTools "Read,Edit"
done

배치 처리 시 --bare를 사용하면 각 호출의 시작 시간을 줄일 수 있다. 대규모 배치 작업은 세션 내에서 /batch 명령을 사용하는 것이 더 효율적이다. /batch는 작업을 5~30개 단위로 분해하고 각각을 독립된 Git worktree에서 병렬로 실행한다.

프롬프트 제안

세션을 시작하면 프롬프트 입력란에 회색 글씨로 예시 명령이 표시된다. 이 제안은 프로젝트의 Git 히스토리를 기반으로 최근 작업한 파일과 관련된 내용이다.

Claude가 응답한 후에도 대화 흐름에 맞는 후속 제안이 나타난다. Tab이나 오른쪽 화살표로 수락하고, Enter로 수락 후 바로 제출한다. 타이핑을 시작하면 제안이 사라진다.

제안이 필요 없다면 비활성화할 수 있다.

export CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false

정리

핵심 요점

1. 두 가지 실행 모드: claude는 인터랙티브 모드, claude -p는 비대화형 모드다. 인터랙티브 모드는 대화형 작업에, 비대화형 모드는 스크립팅과 자동화에 사용한다

2. 세션 관리: -c로 최근 세션 이어가기, -r로 특정 세션 재개, -n으로 세션에 이름 붙이기를 지원한다. 이름을 붙여두면 나중에 쉽게 찾을 수 있다

3. 슬래시 명령어: /를 입력하면 사용 가능한 모든 명령어가 표시된다. /compact, /diff, /model, /permissions 같은 명령으로 세션을 제어한다

4. 키보드 단축키: Ctrl+C(취소), Ctrl+O(트랜스크립트), Ctrl+R(역방향 검색), Ctrl+B(백그라운드), Shift+Tab(권한 모드 전환) 등이 있다

5. 파이프와 리다이렉션: cat error.log | claude -p "분석해줘"처럼 파이프 입력, claude -p "분석" > result.md처럼 출력 리다이렉션, --output-format json으로 구조화된 출력을 활용한다

6. 스크립팅: --bare로 빠른 시작, --allowedTools로 도구 자동 승인, --max-turns와 --max-budget-usd로 실행 제한을 설정한다. 이 플래그들을 조합하면 CI/CD에서 안전하게 자동화할 수 있다

확인해볼 링크

• CLI reference - Claude Code
• Interactive mode - Claude Code
• Commands - Claude Code
• Run Claude Code programmatically - Claude Code
• Environment variables - Claude Code
• Common workflows - Claude Code

다음 단계

다음 차시에서는 VS Code 확장 프로그램을 다룬다. VS Code에서 Claude Code를 설치하고 설정하는 방법, IDE 안에서 활용하는 기능, 에디터와 연동하는 워크플로우를 살펴본다.

참고 자료

• CLI reference - Claude Code
• Interactive mode - Claude Code
• Commands - Claude Code
• Run Claude Code programmatically - Claude Code
• Environment variables - Claude Code
• Common workflows - Claude Code