CH3-P2 · 학습 챕터

03. Codex CLI · P2

Cloud · CLI 옵션

Part 2는 Codex Cloud 워크플로와 CLI 실행 옵션(--add-dir, sandbox, approval, config, profile, features, model, local provider)을 다룹니다.

정본: Codex CLI 한국어 매뉴얼 v1.1 (AI 치트키) · _local/Codex_CLI_한국어_매뉴얼_v1.1_Part2.pdf대상: 바이브코더 · Codex CLI 중급 — Cloud·옵션·슬래시 명령

챕터 이동chapter-nav

이전·다음 챕터로 이동합니다. 본문은 아래 학습 블록 카드에서 펼칩니다.

03. Codex CLI · P1 / 시작하기 · 기본 명령

홈

Harness MultiAgent 2.1

Part 3

03. Codex CLI · P1 03. Codex CLI · P2 03. Codex CLI · P3 03. Codex CLI · P4 03. Codex CLI · P5

전체 학습 블록 카드learn-blocks

학습 블록

codex cloud

Cloud · list · diff · apply

Codex CLI 한국어 매뉴얼 v1.1 (AI 치트키) · _local/Codex_CLI_한국어_매뉴얼_v1.1_Part2.pdf · codex cloud는 Codex Cloud task를 터미널에서 조회·검토하는 명령 그룹입니다. codex apply(또는 codex cloud apply)는 그중 Cloud가 만든 diff를 로컬 repo에 반영하는 단계입니다.

문서 코드 본문현재 실습

학습 블록

-C/--cd · --add-dir

작업·추가 디렉터리

Codex CLI 한국어 매뉴얼 v1.1 (AI 치트키) · _local/Codex_CLI_한국어_매뉴얼_v1.1_Part2.pdf · 위 명령은 codex-manual을 primary workspace로 사용하면서, Downloads/ClaudeDir 폴더도 함께 다룰 수 있는 추가 디렉터리로 지정한다.

문서 코드 본문 실습

학습 블록

-s, --sandbox

샌드박스 모드

Codex CLI 한국어 매뉴얼 v1.1 (AI 치트키) · _local/Codex_CLI_한국어_매뉴얼_v1.1_Part2.pdf · codex

문서 코드 본문 실습

학습 블록

-a, --ask-for-approval

승인 정책

Codex CLI 한국어 매뉴얼 v1.1 (AI 치트키) · _local/Codex_CLI_한국어_매뉴얼_v1.1_Part2.pdf · 쉽게 말하면 Codex가 명령을 바로 실행할지, 특정 상황에서 사람에게 물어볼지 정하는 실행 정책이다.

문서 코드 본문 실습

학습 블록

--profile

실행 프로필

Codex CLI 한국어 매뉴얼 v1.1 (AI 치트키) · _local/Codex_CLI_한국어_매뉴얼_v1.1_Part2.pdf · codex --profile readonly -a never

문서 코드 본문 실습

학습 블록

-c, --config

설정 덮어쓰기

Codex CLI 한국어 매뉴얼 v1.1 (AI 치트키) · _local/Codex_CLI_한국어_매뉴얼_v1.1_Part2.pdf · 위 명령은 Codex를 실행할 때 model 설정을 임시로 gpt-5.4-mini로 덮어쓴다. ~/.codex/config.toml 파일 자체를 수정하지는 않는다. 하위 명령에도 같은 방식으로 붙일 수 있다.

문서 코드 본문 실습

학습 블록

codex features

기능 플래그

Codex CLI 한국어 매뉴얼 v1.1 (AI 치트키) · _local/Codex_CLI_한국어_매뉴얼_v1.1_Part2.pdf · 예를 들어 true와 false는 boolean 값이다.

문서 코드 본문 실습

학습 블록

-i, --image

이미지 첨부

Codex CLI 한국어 매뉴얼 v1.1 (AI 치트키) · _local/Codex_CLI_한국어_매뉴얼_v1.1_Part2.pdf · codex -h

문서 코드 본문 실습

학습 블록

--local-provider

OSS 로컬 프로바이더

Codex CLI 한국어 매뉴얼 v1.1 (AI 치트키) · _local/Codex_CLI_한국어_매뉴얼_v1.1_Part2.pdf · codex -h

문서 코드 본문 실습

학습 블록

--oss

오픈소스 모드

Codex CLI 한국어 매뉴얼 v1.1 (AI 치트키) · _local/Codex_CLI_한국어_매뉴얼_v1.1_Part2.pdf · 로컬 모델 실행 환경을 이미 준비한 사용자가 provider를 명확히 지정할 때 쓰는 옵션이다.

문서 코드 본문 실습

학습 블록

-m, --model

모델 지정

Codex CLI 한국어 매뉴얼 v1.1 (AI 치트키) · _local/Codex_CLI_한국어_매뉴얼_v1.1_Part2.pdf · codex exec에서 사용하기

문서 코드 본문 실습

선택 블록 본문block-detail

codex cloud

Cloud · list · diff · apply

codex cloud는 Codex Cloud task를 터미널에서 조회·검토하는 명령 그룹입니다. codex apply(또는 codex cloud apply)는 그중 Cloud가 만든 diff를 로컬 repo에 반영하는 단계입니다.

GitHub 웹에서 직접 고친 뒤 git pull하는 흐름과 다릅니다. Cloud task가 생성한 unified diff를 로컬 working tree에 가져옵니다.

명령 한눈에 보기

명령	역할
`codex cloud list`	task 목록
`codex cloud status <TASK_ID>`	task 상태
`codex cloud diff <TASK_ID>`	적용 전 diff 미리보기
`codex cloud apply <TASK_ID>`	diff를 로컬에 적용
`codex apply <TASK_ID>`	위와 동일 흐름의 단축 형태

여러 attempt가 있으면 codex cloud apply <TASK_ID> --attempt 2처럼 attempt를 맞춰야 합니다. diff로 본 attempt와 apply하는 attempt가 다르면 실수하기 쉽습니다.

권장 워크플로

list → status → diff → (테스트 브랜치) apply → git status · git diff --cached

codex cloud list --limit 5 --json
codex cloud diff <TASK_ID>
git switch -c test-codex-apply
codex apply <TASK_ID>
git status --short
git diff --cached

언제 사용하나

Cloud에서 만든 수정을 로컬에서 검토·테스트할 때
PR을 올리기 전에 로컬 git diff로 한 번 더 확인할 때
반대로 대화형 Codex 세션에서 이미 로컬 파일을 고치고 있다면 apply 없이 git status / git diff로 충분할 수 있습니다

주의사항 — 자주 하는 실수

실수	올바른 처리
task id 없이 apply	`codex cloud list --json`으로 id 확인
diff 없이 바로 apply	`codex cloud diff`로 내용 먼저 확인
apply 후 `git diff`만 봄	결과가 staged일 수 있음 → `git diff --cached`
로컬 dirty tree + apply	충돌·혼선 — 브랜치 분리 또는 working tree 정리 후 적용

codex apply는 commit을 만들지 않습니다. 적용 후 테스트와 staged/unstaged diff를 직접 확인하세요.

help

codex cloud --help
codex cloud list --help
codex cloud diff --help
codex apply --help

CLI 버전마다 옵션이 달라질 수 있으므로, 자동화 스크립트에 넣기 전에 현재 환경의 help를 확인하는 것이 가장 정확합니다.

실습: Part 2 Cloud · 옵션 lab