Codex CLI 필수 사용법

Codex CLI는 터미널 속 페어 프로그래머다

Codex App이 프로젝트와 작업을 화면으로 정리해 주는 도구라면, Codex CLI는 개발자의 손끝에서 바로 움직이는 작업 도구입니다. 앱에서는 여러 스레드와 변경 사항을 관리하기 좋고, CLI에서는 "지금 이 폴더의 코드를 읽고 바로 분석해 줘", "테스트를 실행하고 실패 원인을 좁혀 줘"처럼 빠르게 지시하기 좋습니다.

터미널이 낯선 독자도 너무 걱정하지 않아도 됩니다. 이 장에서 다루는 흐름은 생각보다 단순합니다. 프로젝트 폴더로 이동하고, codex를 실행하고, 자연어로 요청하고, 변경 사항을 확인합니다. 여기에 일회성 작업을 위한 codex exec, 멈췄던 작업을 이어 가는 세션 재개, 이미지 입력, 코드 리뷰 요청까지 익히면 CLI의 핵심은 거의 잡은 셈입니다.

다만 한 가지를 먼저 기억하세요. Codex CLI는 빠르게 발전하는 도구입니다. 슬래시 명령, 옵션 이름, 하위 명령은 설치된 버전에 따라 조금씩 다를 수 있습니다. 이 책의 예시는 "어떤 흐름으로 쓰는가"를 익히기 위한 기준으로 보고, 실제 작업 전에는 반드시 codex --help와 현재 버전의 공식 문서를 확인하는 습관을 들이세요.¹

먼저 설치 상태부터 확인하기

CLI를 쓰기 전에 가장 먼저 확인할 것은 "지금 터미널에서 Codex 명령이 제대로 잡히는가"입니다.

codex --version
codex --help

codex --version은 현재 설치된 Codex CLI 버전을 보여 줍니다. 기능 이름이나 옵션은 버전에 따라 바뀔 수 있으므로, 책이나 블로그에서 본 명령이 동작하지 않을 때는 먼저 버전을 확인해야 합니다. codex --help는 현재 내 환경에서 사용할 수 있는 하위 명령과 옵션을 보여 줍니다.

인증 상태를 확인하는 명령도 버전별로 차이가 있을 수 있습니다. 지원되는 버전에서는 다음처럼 확인할 수 있습니다.

codex login status

만약 이 명령이 동작하지 않으면 codex login --help 또는 codex --help를 먼저 확인하세요. 원격 서버처럼 브라우저를 열기 어려운 환경에서는 장치 코드 로그인 같은 별도 인증 흐름을 지원하는 버전도 있습니다.

초보자가 특히 자주 겪는 문제는 "분명 설치했는데 codex 명령을 찾을 수 없다"는 상황입니다. 이때는 터미널이 Codex 실행 파일의 위치를 모르는 것입니다. macOS나 Linux에서는 다음 명령으로 위치를 확인할 수 있습니다.

which codex

Windows PowerShell에서는 다음처럼 확인합니다.

Get-Command codex

명령이 나오지 않는다면 터미널을 완전히 닫았다가 다시 열어 보세요. 그래도 안 되면 설치 방식에 따라 npm 전역 설치 경로, Homebrew 경로, 또는 Windows/WSL 경로가 PATH에 포함되어 있는지 확인해야 합니다.

프로젝트 폴더에서 실행하기

Codex CLI의 가장 중요한 습관은 작업할 프로젝트 루트에서 실행하는 것입니다. Codex는 현재 작업 디렉터리를 기준으로 코드를 읽고 수정합니다. 엉뚱한 폴더에서 실행하면 Codex도 엉뚱한 프로젝트를 분석합니다.

예를 들어 my-todo-app이라는 프로젝트에서 작업한다면 다음 순서로 시작합니다.

cd ~/projects/my-todo-app
pwd
git status
codex

pwd는 현재 위치를 보여 줍니다. git status는 Git 기준으로 현재 변경된 파일이 있는지 보여 줍니다. 초보자에게 이 두 명령은 안전벨트와 같습니다. "내가 어디에 있는지"와 "이미 바뀐 파일이 있는지"를 확인한 다음 Codex에게 일을 맡기면 훨씬 덜 불안합니다.

처음 입력해 볼 만한 요청은 프로젝트 분석입니다.

이 프로젝트 구조를 초보자도 이해할 수 있게 설명해줘.
주요 폴더, 실행 진입점, 테스트 방법을 찾아서 정리해줘.
아직 파일은 수정하지 마.

이 요청은 안전합니다. 파일을 바꾸기보다 읽고 설명하는 일이기 때문입니다. Codex가 package.json, README.md, src 폴더 등을 읽고 프로젝트의 뼈대를 설명해 줄 것입니다. 설명을 들은 뒤에는 조금 더 구체적인 작업으로 넘어갈 수 있습니다.

로그인 버튼을 누르면 아무 반응이 없는 버그가 있어.
관련 파일을 찾아 원인을 설명하고,
수정 전에는 어떤 파일을 바꿀지 먼저 계획을 말해줘.

여기서 중요한 표현은 "수정 전에는 계획을 말해줘"입니다. Codex가 바로 파일을 수정할 수도 있지만, 초보 단계에서는 먼저 계획을 듣는 편이 좋습니다. 계획을 보고 "그 파일은 건드리지 말아줘", "테스트부터 실행해줘"처럼 방향을 조정할 수 있습니다.

대화형 모드에서 자주 쓰는 요청 패턴

대화형 CLI에서는 자연어로 말하면 됩니다. 다만 요청을 너무 짧게 쓰면 Codex가 추측해야 하는 부분이 늘어납니다. 목표, 맥락, 제약, 완료 기준을 넣으면 결과가 안정적입니다.

버그 분석을 맡길 때는 이렇게 말할 수 있습니다.

목표: 회원가입 폼에서 이메일을 입력해도 validation error가 사라지지 않는 문제를 고쳐줘.
맥락: 관련 화면은 src/pages/signup.tsx이고, 검증 로직은 src/lib/validation.ts에 있을 가능성이 높아.
제약: API 응답 형식은 바꾸지 말고, UI 문구도 기존 스타일을 유지해줘.
완료 기준: 관련 테스트를 실행하고, 실패하던 케이스가 통과하는지 확인해줘.

리팩터링을 맡길 때는 범위를 더 좁혀야 합니다.

src/components/TodoList.tsx만 대상으로 리팩터링해줘.
동작은 바꾸지 말고, 중복된 렌더링 로직만 작은 컴포넌트로 분리해줘.
수정 후 변경 요약과 테스트 방법을 알려줘.

문서 작업도 CLI와 잘 맞습니다.

이 프로젝트의 실행 방법을 README.md에 초보자 기준으로 추가해줘.
package.json을 확인해서 실제 명령어만 써줘.
없는 스크립트는 만들어 내지 말고, 없다고 알려줘.

명령 실행이 필요한 작업은 승인 내용을 잘 읽어야 합니다.

현재 프로젝트의 테스트 명령을 찾아 실행해줘.
실패하면 실패 원인을 요약하고,
바로 수정하지 말고 가능한 해결 방향을 2가지 제안해줘.

Codex가 터미널 명령을 제안하면 npm test처럼 예상 가능한 명령인지, rm -rf처럼 위험한 명령은 아닌지 확인하세요. 모르는 명령이면 승인하지 말고 먼저 설명을 요구합니다.

방금 실행하려는 명령이 무엇을 하는지 초보자 기준으로 설명해줘.
파일을 삭제하거나 네트워크에 접근하는지도 알려줘.

슬래시 명령은 현재 버전 기준으로 확인한다

대화형 화면 안에서는 /로 시작하는 슬래시 명령을 사용할 수 있습니다. 슬래시 명령은 코드 작업 요청이라기보다 현재 세션의 상태를 확인하거나 설정을 바꾸는 조종 버튼에 가깝습니다. 다만 명령 이름은 버전에 따라 달라질 수 있으므로 /help 또는 codex --help로 현재 환경에서 지원되는 목록을 확인하세요.²

초보자가 먼저 익히면 좋은 종류는 다음입니다.

• 상태 확인: 현재 작업 디렉터리, 모델, 권한 설정, 컨텍스트 사용량을 확인합니다.

• 모델/추론 설정: 작업 난이도에 맞게 모델이나 추론 강도를 조정합니다.

• 권한/승인 설정: 파일 수정이나 명령 실행을 어느 정도 자동으로 허용할지 확인합니다.

• diff 확인: Codex가 만든 변경 사항을 Git diff 형태로 확인합니다.

• 리뷰 요청: 현재 변경 사항을 리뷰 관점으로 다시 점검합니다.

• 프로젝트 초기화: AGENTS.md 같은 프로젝트 지침 초안을 만들 수 있습니다.

• 대화 압축: 긴 대화의 핵심 내용을 요약해 이어 가기 쉽게 만듭니다.

예를 들어 Codex가 여러 파일을 수정한 뒤에는 diff 확인 명령을 사용하거나, 터미널에서 직접 다음 명령을 실행합니다.

git diff

변경 내용을 읽고 마음에 들지 않는 부분이 있으면 이어서 말합니다.

TodoItem 컴포넌트의 props 이름은 기존 이름을 유지해줘.
불필요한 이름 변경은 되돌리고,
버그 수정에 필요한 최소 변경만 남겨줘.

긴 작업을 하다 보면 대화가 길어져 Codex가 앞부분을 덜 정확하게 기억하는 느낌이 들 수 있습니다. 이때는 세션 상태를 확인하고, 지원되는 경우 대화 압축 기능을 사용합니다. 압축 후에는 요약 내용을 반드시 읽고, 틀린 결정이 섞여 있으면 바로 고쳐 주세요.

일회성 작업은 codex exec로 처리하기

대화형 모드는 Codex와 주고받으며 작업하기 좋습니다. 반면 "한 번만 실행하고 결과만 받고 싶다"면 codex exec가 더 어울립니다. exec 모드는 비대화형 실행 방식입니다. 즉, 터미널 UI를 열어 계속 대화하는 대신 프롬프트 하나를 전달하고 작업 결과를 받습니다.³

가장 단순한 예시는 프로젝트 요약입니다.

codex exec "이 프로젝트의 주요 폴더와 실행 방법을 10줄 이내로 요약해줘"

짧은 별칭을 지원하는 버전에서는 다음처럼 쓸 수도 있습니다.

codex e "package.json을 읽고 사용 가능한 npm scripts를 설명해줘"

테스트 명령을 찾되 실행하지 않게 할 수도 있습니다.

codex exec "테스트 명령을 찾아 실행하지는 말고, package.json 기준으로 어떤 테스트 명령이 있는지 설명해줘"

파일 수정까지 맡기려면 더 조심해야 합니다. 비대화형 모드는 중간에 사용자가 맥락을 바로잡기 어렵기 때문입니다. 자동 수정 옵션을 쓰기 전에는 항상 Git 상태를 깨끗하게 만듭니다.

git status
git add -A
git commit -m "checkpoint before codex exec"

작업 후에는 반드시 diff를 확인합니다.

git diff

자동화에 쓰고 싶다면 출력 형식도 중요합니다. 일부 버전은 JSON 출력, 결과 파일 저장, 출력 스키마 같은 옵션을 지원합니다. 스크립트에서 쓰기 전에는 현재 버전의 codex exec --help를 확인하세요. 대화형 TUI를 억지로 스크립트에서 조작하기보다는, 비대화형 실행을 위해 제공되는 명령과 옵션을 사용하는 편이 안정적입니다.³

세션 재개로 긴 작업 이어 가기

CLI 작업을 하다 보면 버그 원인을 거의 찾았는데 회의 시간이 되었거나, 리팩터링 계획을 세워 놓고 다음 날 이어서 구현해야 할 때가 있습니다. 이때 지원되는 버전에서는 이전 세션을 재개할 수 있습니다.

codex resume

최근 세션을 바로 여는 옵션이나 세션 목록 선택 방식은 버전에 따라 다를 수 있습니다. 따라서 실제 사용 전에는 다음처럼 확인하세요.

codex resume --help

긴 작업에서는 세션을 잘 남기는 것도 기술입니다. 종료하기 전에 Codex에게 이렇게 요청해 보세요.

지금까지 한 일, 바꾼 파일, 아직 남은 작업, 다음에 이어서 할 첫 명령을 요약해줘.

다음에 재개한 뒤에는 이렇게 시작합니다.

이전 요약의 남은 작업부터 이어서 진행해줘.
먼저 현재 git status와 diff를 확인하고 계획을 말해줘.

세션 맥락이 이어진다고 해서 현재 파일 상태까지 마법처럼 되돌아가는 것은 아닙니다. 중간에 내가 파일을 수정했거나 브랜치를 바꿨다면 Codex가 보는 실제 파일도 달라집니다. 그래서 재개 직후에는 git status를 확인하는 습관이 좋습니다.

이미지 입력으로 화면 문제 설명하기

코딩 문제 중에는 말로 설명하기 어려운 것이 많습니다. 버튼이 이상한 위치에 붙어 있다거나, 모바일 화면에서 카드가 깨진다거나, 터미널 에러가 너무 길어 어디가 핵심인지 모르겠는 경우입니다. 이럴 때 Codex CLI의 이미지 입력이 도움이 됩니다. 공식 CLI 안내에서도 스크린샷이나 디자인 사양을 첨부해 프롬프트와 함께 읽게 할 수 있다고 설명합니다.¹

명령줄에서 이미지를 붙이는 기본 형태는 버전별 도움말을 확인해야 하지만, 일반적으로 다음과 같은 흐름을 생각할 수 있습니다.

codex --image screenshot.png "이 화면에서 레이아웃이 깨진 원인을 추정하고, 관련 CSS 파일을 찾아 수정 계획을 세워줘"

짧은 옵션을 지원하는 버전에서는 다음처럼 쓸 수 있습니다.

codex -i error.png "이 터미널 에러 화면을 읽고, 어떤 명령이 실패했는지 설명해줘"

실전에서는 이미지와 텍스트를 함께 주는 편이 좋습니다.

첨부한 이미지는 모바일 Safari에서 본 상품 상세 페이지야.
가격 영역이 오른쪽으로 삐져나가.
관련 컴포넌트는 src/components/ProductCard.tsx일 가능성이 높아.
CSS 수정은 최소화하고, 데스크톱 레이아웃은 유지해줘.

이미지만 던져 놓고 "고쳐줘"라고 하면 Codex가 추측해야 할 범위가 넓습니다. 화면이 어떤 브라우저에서 찍혔는지, 어떤 파일이 관련 있어 보이는지, 무엇은 바꾸면 안 되는지 함께 알려 주세요.

코드 리뷰를 CLI에서 바로 요청하기

Codex CLI는 코드를 쓰는 도구이기도 하지만, 읽고 검토하는 도구로도 유용합니다. 특히 초보자는 "코드가 돌아가긴 하는데 괜찮은 코드인지 모르겠다"는 순간이 많습니다. 이때 리뷰 기능이나 일반 프롬프트를 사용할 수 있습니다.

대화형 세션 안에서는 지원되는 리뷰 명령을 쓰거나, 다음처럼 직접 요청합니다.

현재 git diff를 리뷰해줘.
보안, 예외 처리, 초보자가 놓치기 쉬운 비동기 버그를 중심으로 봐줘.
스타일 취향보다 실제 문제 가능성이 높은 부분을 우선해줘.
수정은 아직 하지 말고 리뷰 결과만 보여줘.

명령줄에서 리뷰 하위 명령을 지원하는 버전도 있습니다. 예시는 다음과 같습니다.

codex review --uncommitted
codex review --base main

하지만 실제 옵션 이름은 버전에 따라 다를 수 있으므로 codex review --help를 확인하세요.

리뷰 결과를 받을 때는 "모든 문제를 다 고쳐줘"라고 바로 맡기기보다, 먼저 문제를 분류하게 하세요.

리뷰 결과를 치명도별로 나눠줘.
반드시 고쳐야 하는 버그, 개선하면 좋은 구조, 취향에 가까운 스타일 제안을 구분해줘.

리뷰는 Codex가 만든 코드를 다시 점검하는 용도로도 쓸 수 있습니다. 단, 최종 책임은 항상 사람에게 있습니다. 특히 인증, 결제, 개인정보, 파일 삭제, 배포 스크립트와 관련된 변경은 직접 읽고 테스트해야 합니다.

CLI를 빠른 분석 도구로 쓰는 실전 예제

CLI의 장점은 속도입니다. 에디터를 열지 않아도 터미널에서 바로 분석을 시작할 수 있습니다.

새 프로젝트를 처음 받았을 때는 이렇게 시작합니다.

codex exec "이 저장소의 기술 스택, 실행 방법, 테스트 방법, 주요 진입점을 초보자 기준으로 요약해줘"

오래된 코드를 만났을 때는 위험한 수정 전에 읽기 중심으로 요청합니다.

codex --sandbox read-only

대화형 화면이 열리면 다음처럼 말합니다.

결제 관련 코드 흐름을 설명해줘.
파일을 수정하지 말고, 어떤 함수가 어떤 순서로 호출되는지만 추적해줘.

테스트 실패를 만났을 때는 로그를 붙여 넣고 범위를 좁힙니다.

아래 테스트 실패 로그를 분석해줘.
바로 수정하지 말고, 가장 가능성 높은 원인 3개와 확인할 파일을 알려줘.

[여기에 로그 붙여넣기]

반복 작업에는 exec가 잘 맞습니다.

codex exec "src 폴더에서 TODO 주석을 찾아 파일 경로와 내용을 표로 정리해줘"

릴리스 전에 점검할 때는 리뷰 관점으로 요청합니다.

codex exec "최근 변경된 파일을 기준으로 배포 전 위험 요소를 점검해줘. 환경변수, 마이그레이션, API 응답 변경 가능성을 중점적으로 봐줘"

이런 요청들은 꼭 파일을 수정하지 않아도 가치가 있습니다. Codex CLI를 "자동 코딩 기계"로만 생각하지 말고, 빠른 분석가이자 꼼꼼한 동료 리뷰어로 활용해 보세요.

초보자를 위한 문제 해결 체크리스트

CLI를 쓰다 막히면 당황하지 말고 순서대로 확인하면 됩니다. 대부분의 문제는 설치, 인증, 위치, 권한, Git 상태 중 하나입니다.

• 설치 확인: codex --version이 동작하는지 확인합니다.

• 도움말 확인: codex --help로 현재 버전에서 지원하는 명령과 옵션 이름을 확인합니다.

• 인증 확인: 지원되는 경우 codex login status 또는 로그인 관련 도움말을 확인합니다.

• 위치 확인: pwd와 git status로 프로젝트 루트에서 실행 중인지 확인합니다.

• 권한 확인: 대화형 세션에서 현재 샌드박스와 승인 설정을 확인합니다.

• 변경 확인: Codex 작업 후에는 CLI의 diff 기능 또는 git diff로 바뀐 파일을 읽습니다.

• 세션 확인: 이어서 작업하려면 세션 재개 기능이 있는지 도움말을 확인합니다.

• 이미지 확인: 화면 분석이 필요하면 이미지 파일을 명시적으로 첨부합니다.

• 자동화 확인: 스크립트에서는 대화형 codex를 억지로 조작하지 말고 codex exec를 우선 검토합니다.

인증 실패가 반복되면 브라우저 로그인 세션이 꼬였거나, 회사 네트워크의 프록시와 인증서 정책이 영향을 줄 수 있습니다. 권한 승인 때문에 작업이 멈추는 것은 오류가 아니라 안전장치일 수 있습니다. 모르는 명령이면 승인하지 말고 Codex에게 먼저 설명을 요구하세요.

방금 실행하려는 명령이 무엇을 하는지 초보자 기준으로 설명해줘.
파일을 삭제하거나 네트워크에 접근하는지 알려줘.

샌드박스 제한 때문에 패키지 설치나 외부 API 호출이 실패할 수도 있습니다. 이때 무작정 권한을 크게 열기보다, 왜 네트워크가 필요한지, 대체 방법은 없는지, 임시 브랜치나 컨테이너에서 실행할 수 있는지 먼저 확인하는 편이 안전합니다.

CLI 사용 습관: 작게 맡기고, 자주 확인하기

Codex CLI를 잘 쓰는 사람은 거대한 요청 하나로 모든 것을 맡기지 않습니다. 작은 분석, 작은 수정, 작은 검증을 빠르게 반복합니다.

처음에는 다음 리듬을 추천합니다.

git status
codex

대화형 화면에서 요청합니다.

이 버그의 원인을 먼저 분석해줘.
수정 계획만 말하고 아직 파일은 바꾸지 마.

계획이 괜찮으면 이어서 말합니다.

좋아. 말한 계획대로 최소 변경으로 수정해줘.
수정 후 어떤 파일을 바꿨는지 요약해줘.

수정이 끝나면 diff를 확인합니다.

git diff

그리고 필요하면 리뷰합니다.

이번 변경에서 버그 가능성이 있는 부분만 찾아줘.
수정은 하지 말고 리뷰 결과만 보여줘.

이 흐름이 몸에 익으면 Codex CLI는 단순한 명령어 도구가 아니라, 터미널 안의 페어 프로그래머가 됩니다. 빠르게 묻고, 빠르게 고치고, 빠르게 검토할 수 있습니다. 다음 장에서는 이 CLI 경험을 IDE 안으로 가져가 보겠습니다. 에디터에서 열어 둔 파일, 선택한 코드, 터미널의 실행 결과를 함께 보며 Codex와 더 자연스럽게 페어 프로그래밍하는 방법을 익힐 것입니다.

참고

¹CLI - Codex | OpenAI Developers

²Features - Codex CLI | OpenAI Developers

³Non-interactive mode · Codex Docs