Команда codex archive в Codex CLI: назначение, синтаксис и практические примеры

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

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

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

Обзор команды codex archive

Команда codex archive по смыслу относится к управлению сохранёнными рабочими сессиями Codex CLI. Сессия может включать историю диалога, поставленные задачи, результаты действий модели, сведения о рабочем каталоге, а иногда и дополнительные метаданные. Архивирование позволяет перевести такую сессию из активного состояния в менее заметное или отдельное хранилище.

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

В зависимости от версии и конкретной реализации слово «архивировать» может обозначать разные операции:

• изменение статуса сессии с активного на архивный;
• перемещение файла или каталога с историей в другой каталог;
• создание отдельной копии журнала работы;
• исключение завершённой сессии из стандартного списка;
• упаковку данных в архивный файл вроде .jsonl, .tar или другого формата;
• пометку, после которой сессию можно найти только через специальный фильтр или идентификатор.

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

codex --help
codex archive --help

Что проверяется	Зачем это нужно	Как проверить
Наличие подкоманды	В официальной или старой сборке её может не быть	codex --help
Поддерживаемые параметры	Нельзя переносить флаги из другой версии	codex archive --help
Тип объекта	Архивироваться может сессия, задача или проект	Описание в справке и документации сборки
Место хранения	Нужно понимать, что именно попадёт в резервное копирование	Настройки Codex и документация
Возможность восстановления	Архив без обратной операции может быть только долгосрочным хранилищем	Проверка команд resume, restore или аналогов

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

Синтаксис codex archive

Синтаксис зависит от версии Codex CLI. Ниже приведена не безусловная гарантия конкретных флагов, а практическая схема, по которой следует читать справку команды. Обязательное правило простое: используйте только те параметры, которые показывает команда codex archive --help в вашей установке.

Базовая команда codex archive

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

codex archive

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

Часть команды	Назначение	Возможный вопрос CLI
codex	Запуск Codex CLI	Установлена ли программа и доступна ли она в PATH
archive	Операция архивирования	Поддерживается ли такая подкоманда
Аргумент сессии	Выбор конкретного объекта	Какой идентификатор архивировать
Флаг подтверждения	Отключение дополнительного вопроса	Действительно ли пользователь согласен
Путь или фильтр	Выбор каталога, проекта или группы сессий	Где искать данные

Аргумент идентификатора сессии

Если CLI позволяет архивировать конкретную сессию, обычно используется её идентификатор. Точное написание аргумента нужно брать из справки: это может быть позиционный параметр, --session, --id или другой вариант.

codex archive SESSION_ID

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

Идентификатор	Преимущество	Риск
Полный ID	Минимальная вероятность ошибки выбора	Его неудобно вводить вручную
Короткий ID	Удобен в терминале	Может совпасть с другим объектом
Имя задачи	Понятно человеку	Имя может быть неуникальным
Текущая сессия	Не требует поиска ID	Можно случайно архивировать не ту работу

Фильтр по проекту или рабочему каталогу

При наличии большого количества сессий полезен фильтр по проекту, рабочей директории или группе. Однако имена параметров вроде --project, --workspace или --directory не являются универсальными. Не следует подставлять их наугад.

codex archive --project PROJECT_NAME

Такой пример показывает общий принцип, а не гарантированный флаг каждой версии. Если команда не принимает --project, сначала выполните codex archive --help и найдите официальное название параметра.

Параметр предварительного просмотра

Безопасная реализация может поддерживать режим предварительного просмотра — аналог «покажи, что будет сделано, но ничего не меняй». В разных программах он называется --dry-run, --preview или иначе.

codex archive --dry-run SESSION_ID

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

Режим	Изменяет данные	Когда применять
Просмотр справки	Нет	Перед первым использованием
Предварительный просмотр	Обычно нет	Перед массовым архивированием
Обычное архивирование	Да, меняет статус или расположение	После проверки объекта
Принудительное подтверждение	Да	Только в автоматизированном процессе

Флаг подтверждения операции

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

codex archive SESSION_ID --yes

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

Комбинация параметров

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

codex archive SESSION_ID --project PROJECT_NAME --yes

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

Как работает архивирование сессии

Чтобы правильно оценить результат, полезно разделять несколько уровней данных. Сессия Codex может быть представлена историей сообщений, служебным индексом, сведениями о рабочей папке и отдельными файлами проекта. Архивирование сессии обычно воздействует на историю и метаданные, но не обязательно меняет исходный код, созданный во время работы.

Архив сессии и архив проекта — не одно и то же. Первый сохраняет контекст взаимодействия с Codex, а второй обычно включает файлы, настройки, зависимости и историю изменений проекта.

Например, после архивирования сессии файл app.js в рабочем каталоге, скорее всего, останется на месте. Архив может сохранить сведения о том, что модель предлагала изменить этот файл, но не заменить собой Git, резервную копию или систему хранения артефактов.

Объект	Что может произойти при архивировании сессии	Что обычно не происходит автоматически
История диалога	Перемещается или получает архивный статус	Не превращается в полноценную документацию
Идентификатор сессии	Сохраняется для поиска	Не меняется на имя проекта
Рабочие файлы	Могут остаться без изменений	Не упаковываются автоматически в резервную копию
Git-изменения	Могут остаться в рабочем дереве	Не коммитятся сами по себе
Секреты в истории	Могут остаться в архиве	Не удаляются автоматически

Если Codex запускался в репозитории, архив сессии не заменяет коммит. Коммит фиксирует состояние файлов и автора изменения, а история Codex описывает процесс постановки задачи и взаимодействия с моделью. Для воспроизводимости часто нужны оба слоя: Git — для исходного кода, архив сессии — для контекста и решений.

Практические примеры работы с codex archive

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

Пример 1. Проверка, существует ли команда

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

codex --help
codex archive --help

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

Пример 2. Архивирование текущей сессии

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

codex archive

Перед выполнением убедитесь, что текущая сессия действительно завершена. Если в ней осталась незаписанная задача или незаконченная проверка, удобнее сначала сохранить результат в Git или текстовый отчёт.

Пример 3. Архивирование сессии по ID

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

codex archive ses_2025_04_18_fix_login

Само имя в примере условное. Надёжный ID следует копировать из списка сессий или из вывода команды статуса, а не составлять вручную.

Пример 4. Предварительная проверка перед изменением

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

codex archive --dry-run ses_2025_04_18_fix_login

Ожидаемый результат — информация о выбранной сессии без фактического изменения её статуса или расположения. Если программа не знает флаг --dry-run, не заменяйте его бездумно на другой: смотрите справку.

Пример 5. Архивирование завершённой задачи после коммита

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

git status
git diff
git add src/
git commit -m "Fix login validation"

codex archive SESSION_ID

Так разделяются две операции: Git сохраняет состояние проекта, а codex archive — историю работы с моделью. Если архивирование впоследствии станет недоступным, коммит всё равно останется полезным.

Пример 6. Архивирование перед началом новой задачи

Иногда текущая сессия не сломана и не завершена формально, но её контекст уже не нужен в ежедневной работе. Перед переходом к новой теме можно сохранить старую сессию в архиве.

codex archive old_api_migration_session
codex

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

Пример 7. Проверка, что архивирование не удалило файлы проекта

После операции полезно проверить рабочий каталог. Такой тест показывает различие между архивированием сессии и удалением файлов проекта.

pwd
git status
ls -la

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

Пример 8. Сохранение идентификатора в журнале проекта

Архивная сессия полезнее, если через несколько месяцев понятно, к какому изменению она относилась. Можно записать ID и краткое описание в журнал проекта.

printf "Codex session: SESSION_IDnPurpose: login validationnCommit: COMMIT_IDn" >> docs/codex-sessions.log

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

Пример 9. Архивирование только после проверки конфиденциальности

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

git diff --check
grep -R "API_KEY|TOKEN|PASSWORD" docs/ .codex/ 2>/dev/null

codex archive SESSION_ID

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

Пример 10. Проверка возможности продолжения архивной сессии

Если цель архива — не просто хранение, а возможность вернуться к работе, заранее проверьте предусмотренный механизм восстановления. В некоторых версиях это может быть codex resume, а в других — пункт интерфейса или отдельная команда.

codex resume SESSION_ID

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

Пример 11. Что делать, если codex archive не поддерживается

Если локальная версия не знает подкоманду, безопасная альтернатива — использовать штатное управление сессиями и внешнее архивирование только после изучения формата хранения.

codex --help
codex resume --help
codex status --help

Не перемещайте вручную внутренний каталог Codex, пока не выяснили, как программа индексирует сессии. Простое копирование файла может сделать историю недоступной для CLI.

Пример 12. Архивирование нескольких сессий в скрипте

Массовую обработку следует выполнять только после подтверждения, что команда поддерживает неинтерактивный режим и нужные параметры. Иначе скрипт может остановиться на вопросе подтверждения или архивировать не те объекты.

for session in ses_001 ses_002 ses_003
do
  codex archive "$session" --yes
done

Перед таким запуском протестируйте цикл на одной неважной сессии. В рабочей среде полезно вести журнал успешных и неуспешных операций.

Сценарий	Подход	Главная проверка
Одна завершённая задача	Архивировать по ID	Правильность идентификатора
Переход между проектами	Сохранить старую сессию	Закоммичены ли изменения
Большой список сессий	Использовать фильтр или скрипт	Поддерживает ли CLI массовую обработку
Долгосрочное хранение	Архив плюс резервная копия	Что именно копируется
Продолжение работы позже	Архив плюс механизм resume	Доступен ли обратный путь

Архивирование и удаление: в чём разница

Самая частая ошибка — считать, что архивирование автоматически очищает данные. Обычно архивирование лишь меняет доступность, расположение или статус объекта. Удаление же предназначено для уничтожения или исключения данных из рабочего хранилища, хотя и оно не всегда гарантирует физическое стирание каждого следа.

Скрытое из списка не значит уничтоженное. Архивная сессия может продолжать занимать место, попадать в резервные копии и содержать чувствительную информацию.

Признак	Архивирование	Удаление
Основная цель	Убрать завершённое из активной работы	Избавиться от данных
Восстановление	Часто предполагается	Может быть невозможно
Место на диске	Может сохраниться занятое пространство	Обычно освобождается частично или полностью
История диалога	Обычно сохраняется	Может быть уничтожена
Риск утечки	Остаётся, пока архив существует	Снижается, но не исчезает мгновенно
Роль в резервном копировании	Может попасть в backup	Удаление не всегда удаляет старые backup

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

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

Ограничения и подводные камни

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

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

• Версионная несовместимость. Сессия, созданная новой версией CLI, может не полностью открываться старой.
• Зависимость от каталога. Архивная история может ссылаться на файлы, которых уже нет или которые перемещены.
• Права доступа. Пользователь может иметь право читать сессию, но не иметь доступа к каталогу архива.
• Незавершённые процессы. Архивирование активной сессии может привести к неполному журналу.
• Секреты. Архив сохраняет не только полезный контекст, но и всё, что попало в историю.
• Отсутствие гарантии резервного копирования. Архив может находиться на том же диске и погибнуть вместе с исходными данными.
• Неясный статус операции. Успешный выход процесса не всегда означает, что внешний backup уже создан.

Проблема	Симптом	Что сделать
Неверный ID	Сессия не найдена или выбрана другая	Скопировать идентификатор из штатного списка
Старая версия CLI	Unknown command или unknown option	Проверить документацию именно этой версии
Активная сессия	Неполный журнал	Дождаться завершения процесса
Нет прав	Permission denied	Проверить владельца и права каталога
Изменённый проект	Сессия открывается, но файлы отличаются	Свериться с Git и зафиксировать состояние
Секрет в истории	Чувствительная строка найдена в архиве	Удалить данные по политике и заменить секрет

Как организовать надёжный архив сессий

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

Минимальная политика может включать следующие правила:

1. Архивировать только завершённые или сознательно приостановленные сессии.
2. Перед архивированием проверять состояние Git и сохранять важные изменения.
3. Фиксировать идентификатор сессии, проект, дату и связанный коммит.
4. Не хранить секреты в истории; при утечке сразу отзывать или менять ключ.
5. Проверять, что архив доступен после обновления Codex CLI.
6. Разделять рабочие, тестовые и конфиденциальные проекты.
7. Периодически удалять архивы по утверждённому сроку хранения, если это разрешено политикой.

Поле журнала	Пример значения	Зачем нужно
Дата	2025-04-18	Понимание возраста данных
Проект	billing-service	Поиск по рабочему контексту
ID сессии	ses_abc123	Возврат к исходной истории
Коммит	8f31a2c	Связь с состоянием кода
Статус	archived	Понимание текущего состояния
Владелец	team-backend	Контроль доступа и ответственности

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

Диагностика ошибок

Ошибки при работе с codex archive обычно делятся на три группы: команда отсутствует, параметры указаны неверно или операция не может получить доступ к данным. Диагностика должна начинаться не с переустановки программы, а с чтения полного сообщения об ошибке и проверки справки.

Сообщение или ситуация	Вероятная причина	Первое действие
unknown command: archive	Функция отсутствует в версии	Проверить документацию и команды управления сессиями
unknown option	Флаг взят из другой версии	Выполнить codex archive --help
Session not found	Неверный ID или другой профиль	Получить список сессий штатным способом
Permission denied	Нет доступа к хранилищу	Проверить права и владельца каталога
Operation in progress	Сессия ещё используется	Дождаться завершения процесса
Архив создан, но не открывается	Несовместимая версия или повреждение	Проверить версию и резервную копию

Не стоит скрывать ошибки перенаправлением вывода вроде 2>/dev/null, пока операция не отлажена. Сообщение об ошибке часто содержит единственную подсказку о том, какой объект был выбран и на каком этапе произошёл сбой.

При подозрении на повреждение не запускайте сразу массовое перемещение или очистку. Сначала сделайте копию исходного каталога сессий, сохраните вывод справки и зафиксируйте версию Codex CLI.

Безопасность и конфиденциальность

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

Не архивируйте автоматически всё подряд. Сначала решите, какие сессии имеют ценность для восстановления, а какие содержат только временный или конфиденциальный материал.

• Ограничьте права чтения каталога архива.
• Не помещайте архивы в публичный репозиторий.
• Проверяйте правила корпоративного хранения и удаления.
• Не передавайте архив сторонним сервисам без оценки политики конфиденциальности.
• Если секрет попал в сессию, меняйте сам секрет, а не только имя файла.
• Учитывайте резервные копии: удаление локального архива не удаляет его копии автоматически.

Тип данных	Риск	Рекомендация
Публичный учебный проект	Низкий	Можно хранить после обычной проверки
Закрытый исходный код	Средний	Ограничить доступ и контролировать backup
API-ключи и пароли	Высокий	Не хранить; при утечке немедленно заменить
Данные клиентов	Высокий	Соблюдать требования законодательства и политики компании
Внутренняя инфраструктура	Средний или высокий	Минимизировать срок хранения и круг пользователей

Чем заменить codex archive, если команды нет

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

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

Цель	Подходящая технология	Почему
Сохранить состояние кода	Git commit	Фиксирует изменения и позволяет сравнивать версии
Продолжить разговор	Штатная команда resume или интерфейс сессий	Сохраняет связь с внутренним форматом CLI
Сохранить отчёт	Markdown или корпоративная база знаний	Удобно читать без Codex CLI
Создать резервную копию	Backup-система с контролем доступа	Защищает от потери диска
Удалить чувствительные данные	Политика удаления и ротация секретов	Одного архивирования или перемещения недостаточно

Практическое правило такое: если задача связана с исходным кодом, сначала сохраните код средствами Git; если нужна история общения с Codex, используйте штатный механизм сессий; если требуется защита от потери, настройте отдельный backup. Команда codex archive, если она доступна в вашей сборке, занимает только один слой этой схемы.

Итоги

codex archive следует воспринимать как операцию перевода сессии или задачи в архивное состояние, а не как универсальную команду резервного копирования и тем более не как гарантированное удаление данных. Конкретное поведение, параметры и формат хранения зависят от версии Codex CLI, поэтому начинать нужно с codex --help и codex archive --help.

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

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