부록 A. CLI 명령어·플래그 레퍼런스

이 부록을 어떻게 쓰면 좋은가

이 부록은 처음부터 끝까지 읽는 장이 아니라, 막히는 순간 바로 펼쳐보는 책상 옆 참고서다. 머릿속 지도만 하나 잡아두면 훨씬 덜 헷갈린다.

Codex CLI는 크게 세 가지로 나눠 생각하면 쉽다. 첫째, codex는 대화형 세션을 여는 명령이다. 둘째, codex exec는 한 번 실행하고 끝나는 자동화용 명령이다. 셋째, review, resume, fork, cloud, apply 같은 서브커맨드는 특정 목적에 맞춘 도구들이다.¹

또 하나 기억할 점이 있다. Codex CLI의 기본값 상당수는 ~/.codex/config.toml에서 상속된다. 그래서 같은 명령인데 내 컴퓨터와 동료 컴퓨터의 동작이 다를 수 있다. 그럴 때는 플래그를 명시적으로 붙여서 그 실행만 덮어쓰면 된다.¹

슬래시 명령어와 키보드 단축키는 부록 B에서 따로 정리한다. 여기서는 터미널에서 직접 치는 CLI 명령과 플래그에 집중하자.

가장 많이 쓰는 명령 10개

아래 표만 익혀도 일상 작업의 대부분은 해결된다.

가장 중요한 차이는 이것이다. codex "이 저장소 구조 설명해줘"는 대화형 세션을 연다. 반면 codex exec "이 저장소 구조 설명해줘"는 작업을 끝내고 종료한다. 익숙해지면 둘의 용도가 완전히 다르다는 걸 몸으로 느끼게 된다.¹

기본 사용 패턴

대화형 세션 열기

가장 기본은 아래 한 줄이다.

codex

프로젝트 폴더에서 실행하면 된다. 예를 들어 Next.js + Supabase 프로젝트라면 루트에서 실행한 뒤 이렇게 말하면 시작이 좋다.

codex "이 프로젝트의 인증 흐름을 설명하고 취약한 지점을 찾아줘"

이 방식은 맥락을 쌓아가며 작업할 때 강하다. 버그를 찾고, 수정하고, 테스트하고, 다시 고치는 흐름이 자연스럽다.

비대화형으로 한 번에 끝내기

자동화나 짧은 작업은 exec가 편하다.

codex exec "실패하는 테스트를 실행하고 원인을 요약해줘"

CI나 스크립트에서는 이쪽이 정석에 가깝다. 사람이 중간에 끼어들지 않는 흐름이기 때문이다.¹

표준 입력으로 프롬프트 넣기

로그, 스택 트레이스, 큰 텍스트를 넘길 때는 표준 입력이 편하다.

cat error.log | codex exec -

프롬프트와 표준 입력을 같이 쓰는 패턴도 실전에서 자주 쓴다.

cat test-output.txt | codex exec "이 테스트 로그를 분석해서 원인과 수정 순서를 정리해줘" -

로그 분석, 린트 결과 요약, SQL 실행 계획 설명 같은 작업에서 아주 유용하다.

전역 플래그: 이것만 기억해도 절반은 끝난다

전역 플래그는 대부분의 서브커맨드에 공통으로 붙는다. 자주 쓰는 것부터 익히는 편이 좋다.

--model

가장 단순하면서도 체감 차이가 큰 플래그다. 대충 이렇게 생각하면 편하다.

• 깊은 디버깅, 아키텍처 판단: 더 강한 모델

• 빠른 반복, 작은 수정, 서브태스크: 미니 계열

• 코딩 특화 워크플로: Codex 계열

예를 들면 Express + MongoDB 백엔드에서 인증 리팩터링처럼 범위가 넓은 일은 이렇게 시작할 수 있다.

codex -m gpt-5.4 "JWT 인증 미들웨어 구조를 점검하고 안전한 리팩터링 계획을 세워줘"

--profile

같은 사람도 작업 성격이 다르다. 로컬 실험, 회사 업무, CI 자동화는 원하는 기본값이 다르다. 그럴 때 프로필이 편하다.

codex -p ci exec "CHANGELOG를 업데이트해줘"

프로필을 잘 써두면 매번 긴 플래그를 다시 치지 않아도 된다.

--cd, --add-dir

모노레포에서 특히 중요하다. 예를 들어 프런트는 apps/web, 공용 UI는 packages/ui에 있을 때 이런 식이다.

codex -C apps/web --add-dir ../../packages/ui "로그인 폼과 공용 버튼 컴포넌트를 함께 수정해줘"

danger-full-access로 넓게 열어버리기 전에 --add-dir로 필요한 폴더만 추가하는 습관이 더 안전하다.

--image

스크린샷을 함께 넣으면 프런트엔드 디버깅 속도가 갑자기 올라간다.

codex -i mobile-bug.png "이 결제 화면이 모바일에서 깨지는 이유를 분석해줘"

한국 개발자에게는 디자이너가 카카오톡으로 던져준 화면 캡처를 그대로 붙여 넣고 작업할 수 있다는 점이 꽤 실용적이다.

--config

딱 한 번만 설정을 바꾸고 싶을 때 유용하다. 예를 들어 reasoning effort만 올리고 싶다면 이렇게 쓴다.

codex -c 'model_reasoning_effort="high"' "이 레이스 컨디션의 원인을 찾아줘"

설정 파일을 직접 만지지 않고도 그 실행만 바꿀 수 있어서 실험에 좋다.

샌드박스와 승인 정책

Codex CLI를 잘 쓰는 사람과 무섭게 쓰는 사람의 차이는 사실 프롬프트보다 여기서 갈린다.

샌드박스 모드

승인 정책

가장 많이 쓰는 조합

안전하게 둘러볼 때는 아래 조합이 좋다.

codex -s read-only -a untrusted "이 저장소의 아키텍처와 위험 구간을 설명해줘"

실무에서 가장 무난한 기본값은 이쪽이다.

codex -s workspace-write -a on-request "결제 API 타임아웃 재시도 로직을 수정해줘"

자주 보이는 --full-auto는 사실 이 조합을 빠르게 쓰는 단축키라고 생각하면 된다. 즉, 편한 기본값이지 무방비 모드는 아니다.³

codex --full-auto "실패하는 테스트를 고치고 관련 테스트만 다시 돌려줘"

반대로 제한을 크게 우회하는 위험한 모드는 격리된 러너나 임시 실험 환경이 아니라면 피하는 편이 좋다. 실수 한 번이 레포 전체를 어지럽힐 수 있다.

명령별 자주 쓰는 옵션

codex

대화형 진입점이다. 가장 자주 쓰는 형태는 네 가지다.

codex
codex "레포 구조를 설명해줘"
codex -m gpt-5.4 "이 PR의 리스크를 점검해줘"
codex --full-auto "버그 수정 후 테스트까지 해줘"

처음에는 단순해 보이지만, 실제로는 여기서 시작해서 resume, fork, review로 뻗어나가는 경우가 많다.

codex exec

자동화의 핵심이다. 한 번 실행하고 종료하는 흐름에 최적화되어 있다.¹

자주 쓰는 옵션

대표 패턴

codex exec "README를 업데이트해줘"

codex exec --json "모든 API 엔드포인트를 목록으로 만들어줘"

codex exec -o summary.md "이 브랜치 변경사항을 릴리스 노트 형식으로 정리해줘"

codex exec --output-schema schema.json "에러 로그에서 서비스명과 원인만 추출해줘"

exec가 특히 좋은 순간

• GitHub Actions에서 CHANGELOG 자동 생성

• 린트/테스트 결과 요약 후 슬랙 전송 전처리

• PR 설명문 초안 생성

• 장애 로그에서 원인 후보 정리

사람이 중간에 개입하지 않아도 되는 작업일수록 exec가 빛난다.

codex review

리뷰 전용 명령이다. 같은 작업을 일반 프롬프트로도 할 수 있지만, 변경분을 Git 기준으로 다루기 때문에 습관적으로 쓰기 좋다.¹

자주 쓰는 옵션

대표 패턴

codex review --uncommitted

codex review --base main "보안 리스크와 리그레션 가능성 위주로 봐줘"

codex review --commit abc1234 "이 커밋이 만든 부작용을 찾아줘"

혼자 개발할 때도 좋지만, 팀에서는 커밋 전에 셀프 리뷰 루틴으로 특히 강하다. "고쳤다"와 "괜찮다"는 전혀 다른 말이기 때문이다.

codex resume

이전 세션을 이어갈 때 쓴다. 밤새 고민한 맥락을 다음 날 다시 불러오는 버튼이라고 생각하면 쉽다.

자주 쓰는 옵션

대표 패턴

codex resume --last

codex resume 01HV... "어제 계획한 대로 마이그레이션 코드까지 이어서 진행해줘"

대형 작업은 세션을 이어가는 습관이 생산성을 꽤 올린다. 특히 Supabase 스키마 변경, 결제 로직, 모노레포 정리처럼 문맥이 긴 작업에서 효과가 크다.

codex fork

같은 출발점에서 다른 길을 시험하고 싶을 때 쓴다. 한마디로 "이거 좋은데, 다른 접근도 한 번 보자" 버튼이다.¹

codex fork --last

codex fork 01HV... "이번엔 Zustand 대신 React Query 중심으로 구조를 다시 잡아줘"

버그 수정안 A와 B를 비교하거나, Claude Code에서 하던 습관처럼 한 스레드 한 문제 원칙을 유지하고 싶을 때 특히 좋다.

codex cloud와 codex apply

로컬이 아니라 클라우드 작업 결과를 확인하고, 필요하면 로컬에 반영하는 흐름이다. 노트북을 닫고도 일이 굴러가게 만드는 명령군이라고 생각하면 된다.¹

자주 쓰는 명령

codex cloud list
codex cloud status <TASK_ID>
codex cloud diff <TASK_ID>
codex cloud apply <TASK_ID>
codex apply <TASK_ID>

실전에서는 보통 이렇게 쓴다.

1. 밤에 클라우드에서 작업을 돌린다.

2. 아침에 codex cloud list로 결과를 본다.

3. codex cloud diff <TASK_ID>로 패치를 확인한다.

4. 괜찮으면 codex apply <TASK_ID>로 로컬 워킹트리에 반영한다.

PR 전 diff를 먼저 보는 습관은 여전히 중요하다. AI가 만든 패치라고 해서 검토 없이 바로 들이밀면, 결국 미래의 내가 울게 된다.

codex login, logout

인증이 꼬였을 때 가장 먼저 보는 명령이다.

codex login
codex login status
codex logout

• 브라우저 인증을 다시 시작하고 싶을 때: codex login

• 지금 로그인 상태가 맞는지 확인할 때: codex login status

• 공용 장비에서 흔적을 지울 때: codex logout

Codex는 ChatGPT 계정 로그인과 API 키 흐름을 모두 지원한다. 일반적인 개인 개발 워크플로는 ChatGPT 로그인 쪽이 편하고, CI나 헤드리스 자동화는 API 키가 더 잘 맞는다.²

codex completion

자동완성은 한 번만 해두면 계속 편하다.

codex completion bash
codex completion zsh
codex completion fish

예를 들어 zsh라면 보통 이런 식으로 붙인다.

eval "$(codex completion zsh)"

명령어 기억력이 좋지 않아도 탭 완성이 많이 살려준다. AI 시대에도 손가락 체력은 소중하다.

알아두면 좋은 보조 명령

codex plugin

플러그인과 마켓플레이스 관리용 명령이다. 팀 배포나 워크플로 표준화에서 쓴다.

codex plugin --help
codex plugin marketplace add openai/codex-marketplace

개인 사용자라면 매일 치는 명령은 아니지만, 팀에서 공통 플러그인을 배포할 때 알아둘 가치가 있다.³

codex mcp

MCP 서버를 등록하고 확인하는 관리 명령이다.

codex mcp list
codex mcp get github
codex mcp add github -- npx -y @modelcontextprotocol/server-github
codex mcp remove github

MCP를 적극적으로 쓰는 팀이라면 CLI에서 서버 상태를 점검할 일이 자주 생긴다.

codex sandbox

현재 샌드박스 정책 안에서 명령이 어떻게 도는지 확인할 때 쓴다.

codex sandbox --help

권한 문제를 디버깅할 때 의외로 유용하다.

codex debug

뭔가 이상한데 이유를 모르겠을 때 보는 구조대다.

codex debug --help

인증, 설정, 메모리, 내부 상태가 꼬였을 때 먼저 살펴보면 좋다.

실전 레시피

아래 예시는 한국 개발자가 실제로 자주 만나는 프로젝트를 기준으로 골랐다.

Next.js + Supabase 프로젝트 구조 빠르게 파악하기

codex -C apps/web -s read-only -a untrusted \
  "이 Next.js + Supabase 프로젝트의 인증, DB 접근, 배포 흐름을 요약해줘"

처음 합류한 프로젝트를 파악할 때 좋다. 읽기 전용으로 시작하면 마음이 편하다.

실패하는 테스트 자동 수정

codex --full-auto \
  "pnpm test를 실행하고 실패하는 테스트를 고친 뒤, 수정 이유를 한국어로 정리해줘"

일상적인 유지보수에 잘 맞는다. 다만 결과를 바로 커밋하지는 말자.

Express + MongoDB API 리뷰

codex review --base main \
  "인증 우회, 예외 처리 누락, N+1 쿼리 가능성 위주로 리뷰해줘"

PR 올리기 전에 자기 점검용으로 훌륭하다.

모노레포에서 공용 패키지까지 함께 수정

codex -C apps/admin --add-dir ../../packages/ui --full-auto \
  "관리자 로그인 화면과 공용 버튼 컴포넌트를 함께 정리해줘"

danger-full-access 없이 필요한 디렉터리만 열어주는 안전한 습관이다.

스크린샷 기반 프런트엔드 디버깅

codex -i checkout-bug.png -m gpt-5.4 \
  "이 결제 페이지의 레이아웃 깨짐 원인을 찾고 최소 수정안을 제안해줘"

디자이너와 프런트 개발자 사이에서 말이 엇갈릴 때 특히 좋다. 화면은 거짓말을 덜 한다.

CI에서 구조화된 출력 만들기

codex exec --json --output-schema schema.json \
  "이 PR의 변경 파일, 위험도, 테스트 필요 여부를 JSON으로 출력해줘"

자동화 파이프라인과 연결할 때 매우 강하다.

문제 생길 때 먼저 확인할 명령

잘 안 될수록 더 기본으로 돌아가자. 아래 순서가 의외로 많은 문제를 끝낸다.

codex --version
codex --help
codex exec --help
codex login status
codex debug --help

특히 아래 상황에서는 거의 반사적으로 확인하는 편이 좋다.

• 명령이 예전처럼 안 먹을 때

• 로그인은 된 것 같은데 실행이 실패할 때

• 팀원과 같은 명령인데 결과가 다를 때

• 플러그인, 클라우드, 실험 기능이 갑자기 바뀐 것 같을 때

많은 경우 원인은 생각보다 단순하다. 버전 차이, 프로필 차이, 샌드박스 차이, 승인 정책 차이 가운데 하나다.

빠르게 바뀌는 영역은 따로 기억하자

CLI 세계는 늘 그렇지만, 다 바뀌는 건 아니다. 자주 변하는 부분만 따로 기억하면 된다.

첫째, plugin, cloud, app-server 같은 주변 명령 표면은 비교적 빨리 바뀐다. 둘째, 일부 승인 정책이나 실험 기능 이름은 버전별로 조정될 수 있다. 셋째, 실험 명령은 오늘 되는 게 다음 달에는 다른 위치로 이동할 수 있다.¹³

그래서 실무 팁은 단순하다.

• 기본 작업은 codex, exec, review, resume, fork 중심으로 익힌다.

• 세부 옵션은 로컬 --help를 먼저 믿는다.

• 최신 모델명, 요금제, 실험 기능은 부록 F에서 따로 확인한다.

CLI를 오래 쓸수록 화려한 기능보다 기본 명령의 조합이 더 중요해진다. 결국 잘 쓰는 사람은 명령을 많이 아는 사람이 아니라, 언제 read-only로 시작하고 언제 exec로 넘기고 언제 fork로 갈라야 하는지 아는 사람이다.

참고

¹Command line options - Codex CLI | OpenAI Developers

²GitHub - openai/codex: Lightweight coding agent that runs in your terminal

³Codex CLI Cheat Sheet 2026 — Slash Commands & Shortcuts | Toolsbase