Флаг Codex CLI —cd (-C): как выбрать рабочий каталог

Флаг Codex CLI --cd применяется для запуска Codex CLI из указанного рабочего каталога. Его короткий аналог — -C. Благодаря этому не нужно заранее выполнять cd в терминале: Codex сразу получает нужную папку как основной контекст работы, видит её файлы, конфигурацию и Git-репозиторий.

--cd меняет рабочий каталог Codex CLI, но не переключает каталог вашего родительского терминала. После завершения команды оболочка останется там, откуда вы запускали Codex.

На практике это особенно удобно, когда на компьютере несколько проектов, когда команда запускается из скрипта или когда нужно явно зафиксировать область работы. Понимание этого флага помогает избежать распространённой путаницы: каталог, в котором находится ваш терминал, и каталог, в котором работает Codex, могут быть разными. Ниже разберём синтаксис, сценарии применения, отличия от похожих команд, реальные примеры и типичные ошибки.

Как использовать

Флаг --cd указывается при запуске Codex CLI и принимает путь к каталогу. После этого Codex использует указанную директорию как текущую рабочую папку. Короткая форма -C делает то же самое и удобна для частого использования в терминале или скриптах.

Главная идея проста: путь после --cd — это каталог, из которого Codex должен рассматривать проект, а не обязательно каталог, где физически лежит исполняемый файл Codex CLI.

Базовые формы выглядят так:

Форма	Назначение	Пример
codex --cd ПУТЬ	Запустить Codex в указанном каталоге	codex --cd ./backend
codex -C ПУТЬ	Короткий вариант той же команды	codex -C ./backend
codex --cd ПУТЬ "ЗАПРОС"	Запустить Codex в каталоге и сразу передать задачу	codex --cd ./backend "Проверь тесты"
codex -C ПУТЬ exec "ЗАПРОС"	Использовать заданный каталог в режиме выполнения задачи	codex -C ./backend exec "Исправь ошибку"

Путь может быть относительным или абсолютным. Относительный путь вычисляется относительно текущего каталога shell в момент запуска команды. Абсолютный путь не зависит от того, где вы находитесь в терминале, поэтому он надёжнее в автоматизации, но менее переносим между компьютерами.

Тип пути	Пример	Относительно чего считается	Когда удобен
Относительный	./project	Текущего каталога терминала	Локальная ручная работа
Относительный с переходом вверх	../api	Текущего каталога и его родителя	Монорепозитории и соседние проекты
Абсолютный Unix-путь	/home/user/app	Корня файловой системы	Скрипты и CI в Linux/macOS
Абсолютный путь Windows	C:workapp	Диска Windows	Ручной запуск в Windows
Домашний путь с ~	~/projects/app	Домашнего каталога shell	Короткие команды в Unix-подобных системах

Если в пути есть пробелы, путь нужно заключить в кавычки. Это правило относится не к Codex CLI как таковому, а к командной оболочке: без кавычек shell может разделить один путь на несколько аргументов.

codex --cd "/home/alex/Рабочие проекты/shop" "Изучи структуру проекта"

В Windows аналогичная команда может выглядеть так:

codex --cd "C:UsersAlexDocumentsРабочие проектыshop" "Проверь конфигурацию сборки"

Важно различать изменение рабочего каталога Codex и изменение каталога оболочки. Команда с --cd действует только внутри запущенного процесса Codex CLI. Она не является заменой команде cd в shell.

Действие	Что меняется	Что остаётся прежним
cd project	Каталог текущего shell	Сам Codex ещё не запущен
codex --cd project	Рабочий каталог процесса Codex	Каталог родительского shell
cd project && codex	И shell, и обычно рабочий каталог Codex	После выхода shell останется в project
codex -C project	То же, что и codex --cd project	Ничего не переключается в родительском shell

Когда применять

Флаг --cd нужен не только для экономии одного нажатия клавиши. Он делает запуск явным: из самой команды видно, с каким проектом должен работать Codex. Это особенно ценно в монорепозиториях, автоматических сценариях и ситуациях, когда один терминал используется для нескольких задач.

Если команда должна быть понятной через неделю другому человеку или автоматическому процессу, явно указанный рабочий каталог обычно лучше неявной зависимости от текущего положения терминала.

Один из самых удобных сценариев — запуск из родительской папки. Например, вы находитесь в каталоге ~/projects, а нужный проект лежит в ~/projects/catalog. Вместо двух действий можно сразу выполнить:

codex --cd ./catalog "Разбери архитектуру приложения и предложи точки улучшения"

Флаг также полезен в монорепозиториях. В такой структуре рядом могут находиться каталоги frontend, backend, infra и десятки внутренних пакетов. Если открыть Codex на верхнем уровне, он может видеть слишком большой объём файлов. Указание конкретного подкаталога помогает сузить область внимания.

Ситуация	Рекомендуемый каталог	Почему
Исправление API	backend	Меньше нерелевантных файлов
Изменение интерфейса	frontend	Проще ориентироваться в компонентах и сборке
Работа с Docker	Корень репозитория	Видны Dockerfile, compose-файлы и настройки проекта
Работа с инфраструктурой	infra или корень репозитория	Зависит от того, где находятся Terraform-модули и конфигурация
Документация отдельного пакета	Каталог пакета	Контекст не смешивается с остальными компонентами

При этом слишком узкий каталог иногда мешает. Если задача требует сравнить несколько пакетов, прочитать общий файл конфигурации или понять связи между сервисами, запуск из глубокой вложенной папки может дать неполный контекст. В таких случаях лучше выбрать корень репозитория или явно указать дополнительные доступные каталоги, если это поддерживается вашей конфигурацией и версией Codex CLI.

Задача	Лучший стартовый каталог	Риск неправильного выбора
Исправить один компонент	Каталог компонента	Незначительный
Понять архитектуру всего проекта	Корень репозитория	Если выбрать подкаталог, часть связей может быть скрыта
Обновить общий CI-процесс	Корень репозитория	Из подкаталога можно не увидеть workflow и общие скрипты
Проверить отдельный пакет	Каталог пакета	Запуск из корня создаёт лишний шум

В автоматизации --cd помогает не зависеть от того, какой каталог выбран runner-ом, IDE или вызывающим скриптом. Но для CI лучше использовать путь, который гарантированно существует в конкретной среде. Домашние каталоги, буквы дисков и локальные имена пользователей в CI обычно непредсказуемы.

Примеры использования

Ниже приведены практические сценарии — от простого запуска в соседнем проекте до использования флага в проверках, монорепозитории и автоматических скриптах. Каждый пример показывает не только синтаксис, но и смысл выбора каталога.

Запуск в соседнем проекте

Если текущий каталог содержит несколько проектов, можно направить Codex в нужную папку относительным путём. Это удобно, когда вы уже находитесь в общем каталоге вроде ~/projects.

codex --cd ./online-store "Найди главные модули приложения и опиши их назначение"

Codex начнёт работу в online-store, а терминал после завершения останется в исходном каталоге.

Использование короткого аналога -C

Короткая форма подходит для интерактивной работы, когда команда запускается часто и длинный флаг только занимает место. По поведению она эквивалентна --cd.

codex -C ./online-store "Проверь, где реализована авторизация пользователей"

Не следует воспринимать -C как отдельный режим. Это всего лишь сокращённая запись параметра выбора рабочего каталога.

Запуск из родительской папки через ..

Предположим, терминал уже открыт внутри каталога frontend/src, но задача относится ко всему frontend-проекту. Можно подняться на два уровня только для Codex, не меняя положение текущего shell.

codex --cd ../.. "Проверь структуру frontend-проекта и найди дублирование компонентов"

Такой приём особенно полезен, если вы не хотите менять каталог терминала из-за других выполняемых команд.

Работа с путём, содержащим пробелы

Пробелы в имени каталога требуют кавычек. Без них shell воспримет части пути как разные аргументы, и Codex получит некорректное значение.

codex --cd "/home/alex/Рабочие проекты/CRM" "Изучи настройки подключения к базе данных"

Кавычки должны охватывать весь путь, а не только отдельное слово внутри него.

Запуск в конкретном подкаталоге монорепозитория

В монорепозитории можно ограничить исходную рабочую область каталогом нужного сервиса. Это снижает количество файлов, которые приходится просматривать при локальной задаче.

codex --cd ./services/payments "Найди обработчик возврата платежа и предложи безопасное исправление"

Если для решения задачи нужны общие файлы монорепозитория, стоит запускать Codex из его корня или заранее убедиться, что необходимый контекст доступен.

Проверка проекта без предварительного cd

Комбинация --cd и режима exec удобна для разовых проверок: команда сразу указывает проект и действие.

codex --cd ./backend exec "Запусти доступные тесты и объясни причины возможных ошибок"

Преимущество такого запуска — воспроизводимость. В команде явно зафиксировано, где искать проект и какую задачу выполнять.

Использование абсолютного пути в скрипте

Абсолютный путь может быть полезен в локальном скрипте, если скрипт запускается из разных каталогов. Однако такой вариант следует применять только там, где путь стабилен.

codex --cd "/opt/workspace/inventory" exec "Проверь изменения и подготовь краткий отчёт"

Для команды, которую будут запускать разные пользователи или машины, лучше формировать путь переменной окружения, а не зашивать его в текст.

Передача каталога через переменную окружения

В shell можно хранить путь в переменной и передавать его Codex. Это делает скрипт переносимее и избавляет от повторения длинных путей.

PROJECT_DIR="$HOME/projects/inventory"
codex --cd "$PROJECT_DIR" "Проверь конфигурацию сборки"

Здесь кавычки вокруг переменной также важны: домашний каталог или имя проекта могут содержать пробелы.

Запуск из корня репозитория для архитектурного анализа

Когда нужно понять связи между несколькими сервисами, слишком узкий каталог может скрыть важные файлы. В таком случае лучше явно указать корень репозитория.

codex --cd "/home/alex/projects/platform" "Опиши взаимодействие frontend, backend и очереди сообщений"

Для архитектурного анализа широкий контекст обычно полезнее, чем максимальное сокращение количества файлов.

Работа в Windows с короткой формой

В Windows путь часто начинается с буквы диска и содержит обратные слеши. Кавычки особенно важны, если в пути есть пробелы.

codex -C "C:UsersAlexsourcereposbilling" "Проверь проект и найди устаревшие зависимости"

Если команда вводится в PowerShell, учитывайте правила PowerShell для кавычек и переменных. Сам флаг -C при этом остаётся тем же.

Запуск из автоматического сценария

В скрипте можно сначала проверить существование каталога, а затем передать его Codex. Это позволяет завершить сценарий с понятной ошибкой, а не получить малополезное сообщение о ненайденном пути.

PROJECT_DIR="./backend"

if [ ! -d "$PROJECT_DIR" ]; then
  echo "Каталог проекта не найден: $PROJECT_DIR"
  exit 1
fi

codex --cd "$PROJECT_DIR" exec "Проверь изменения и составь список замечаний"

Такой шаблон особенно полезен в локальных инструментах команды и CI-подобных сценариях.

Чем отличается от похожих команд

--cd часто сравнивают с обычным cd, коротким -C, режимом exec и параметрами, которые расширяют доступные каталоги. Эти элементы могут использоваться вместе, но отвечают за разные вещи.

От обычной команды cd

Команда cd относится к вашей командной оболочке. Она меняет текущий каталог shell, после чего следующие команды обычно запускаются уже из нового места. Флаг --cd передаёт каталог только процессу Codex.

Команда	Объект изменения	Состояние после завершения Codex
cd project	Текущая оболочка	Shell остаётся в project
codex --cd project	Процесс Codex	Shell возвращается в прежний каталог
cd project && codex	Сначала shell, затем Codex	Shell остаётся в project

От короткой формы -C

-C — это не другой режим и не отдельный способ доступа к проекту. Это краткий псевдоним флага --cd. Выбор между ними зависит только от читаемости и привычки.

Критерий	--cd	-C
Назначение	Рабочий каталог Codex	То же назначение
Читаемость	Выше, особенно в документации	Ниже, но команда короче
Удобство в интерактивном вводе	Хорошее	Очень хорошее
Подходит для обучающих примеров	Обычно да	Да, если объяснено значение

От режима exec

exec определяет способ выполнения задачи, а --cd определяет рабочий каталог. Эти параметры не заменяют друг друга и могут применяться совместно.

Элемент	На какой вопрос отвечает	Пример
--cd ./app	Где работать?	codex --cd ./app
exec	В каком режиме выполнить задачу?	codex exec "Проверь тесты"
Совместное использование	Где и как работать?	codex --cd ./app exec "Проверь тесты"

От --add-dir и похожих параметров доступа

Выбор рабочего каталога и разрешение доступа к дополнительным каталогам — разные понятия. --cd задаёт основную рабочую папку. Параметр вроде --add-dir, если он доступен в используемой версии CLI, предназначен для добавления других директорий в область разрешённого доступа, а не для замены основного каталога.

Параметр	Основная роль	Типичный вопрос
--cd DIR	Выбрать рабочий каталог	«В каком проекте работать?»
-C DIR	Коротко выбрать рабочий каталог	«Как указать то же самое короче?»
--add-dir DIR	Добавить каталог к доступным областям	«К каким дополнительным файлам нужен доступ?»
exec	Выбрать режим выполнения	«Как выполнить поставленную задачу?»

Типичные ошибки

Большинство проблем с --cd связано не с самим флагом, а с путями, кавычками и неверным представлением о рабочем каталоге. Ниже — ситуации, которые чаще всего приводят к неожиданному результату.

Перепутан каталог shell и каталог Codex

Пользователь запускает codex --cd ./app, а затем выполняет pwd и удивляется, что терминал всё ещё находится в старой папке. Это нормальное поведение: дочерний процесс не может изменить каталог родительской оболочки.

--cd не является «постоянным переключателем» терминала. Он действует только во время работы конкретного запуска Codex.

Если нужно действительно сменить каталог shell, используйте отдельную команду:

cd ./app
codex "Проверь проект"

Если менять положение shell не нужно, оставляйте запуск через --cd.

Указан путь относительно не того каталога

Относительный путь считается от места, где находится терминал в момент запуска, а не от расположения файла сценария и не от корня Git-репозитория автоматически.

pwd
ls
codex --cd ./backend "Проверь API"

Если команда запущена из /home/alex, путь ./backend означает /home/alex/backend. Если проект расположен в /home/alex/projects/backend, нужно указать правильный относительный путь:

codex --cd ./projects/backend "Проверь API"

Забыты кавычки в пути с пробелами

Без кавычек путь вроде /home/alex/My Projects/app будет разобран на несколько частей. В результате Codex может получить только часть пути или воспринять остаток как дополнительный аргумент.

Неправильный вариант	Правильный вариант	Причина
codex --cd /home/alex/My Projects/app	codex --cd "/home/alex/My Projects/app"	Весь путь передаётся одним аргументом
codex -C C:Work FilesApp	codex -C "C:Work FilesApp"	Пробелы не разделяют путь

Выбран слишком глубокий каталог

Иногда пользователь указывает папку отдельного файла или небольшого модуля, хотя задача относится ко всему проекту. В таком случае Codex может не увидеть корневые конфигурации, общие библиотеки или связанные сервисы.

Перед запуском полезно спросить себя:

• Нужен ли для задачи только один пакет?
• Есть ли важные настройки в корне репозитория?
• Нужно ли сравнивать несколько соседних компонентов?
• Должен ли Codex видеть общие тесты, CI-файлы или документацию?

Если ответ касается нескольких частей проекта, лучше выбрать более высокий уровень каталога.

Каталог не существует или недоступен

Опечатка в имени, неправильная буква диска, отсутствующий смонтированный том или недостаточные права доступа приводят к ошибке ещё до полноценной работы Codex. Особенно часто это случается в скриптах, где путь жёстко прописан.

PROJECT_DIR="./backend"

if [ ! -d "$PROJECT_DIR" ]; then
  echo "Ошибка: каталог не существует"
  exit 1
fi

codex --cd "$PROJECT_DIR" "Проверь проект"

Для диагностики сначала проверьте путь средствами операционной системы, а затем уже разбирайтесь с поведением Codex. Так вы отделите проблему файловой системы от проблемы аргументов CLI.

Краткая памятка

Флаг --cd отвечает за одно конкретное действие: задаёт рабочий каталог для запуска Codex CLI. Его короткая форма — -C. Остальные вопросы — режим работы, доступ к дополнительным каталогам и изменение каталога терминала — решаются другими командами или параметрами.

Что нужно сделать	Команда или правило
Запустить Codex в каталоге	codex --cd ./project
Использовать короткую запись	codex -C ./project
Передать задачу сразу	codex --cd ./project "Проверь код"
Запустить задачу в режиме выполнения	codex --cd ./project exec "Запусти тесты"
Указать путь с пробелами	Заключить путь в кавычки
Сохранить каталог терминала без изменений	Использовать --cd, а не отдельный cd
Изменить каталог самого терминала	Использовать cd
Работать со всем репозиторием	Указать его корень, а не случайный подкаталог
Сузить область задачи	Указать нужный сервис или пакет
Использовать команду в скрипте	Проверить существование каталога до запуска

Перед запуском достаточно проверить три вещи: правильно ли выбран каталог, верно ли сформирован путь и нужны ли кавычки. Если задача относится к одному сервису, выбирайте его каталог; если требует архитектурного контекста — корень репозитория. Для ручной работы можно использовать короткий -C, а в документации и командных сценариях чаще понятнее писать полный --cd.

# Полная и короткая формы эквивалентны
codex --cd ./project "Проанализируй проект"
codex -C ./project "Проанализируй проект"

# Путь с пробелами нужно заключать в кавычки
codex --cd "/home/user/Рабочие проекты/project" "Проверь тесты"

# Рабочий каталог shell не меняется
pwd
codex --cd ./project "Проверь структуру"
pwd

Иными словами, --cd — небольшой, но важный флаг для точного управления контекстом Codex CLI. Он делает команды предсказуемее, помогает работать с несколькими проектами и избавляет от лишних переходов между каталогами, не меняя состояние вашего терминала.