CLI

Терминальные команды openspec.

Команды

Настройка

Команда	Описание
openspec init	Инициализирует OpenSpec в проекте.
openspec update	Обновляет установленные файлы инструкций OpenSpec.
openspec config	Просмотр и изменение глобальной конфигурации.

Изменения и спецификации

Команда	Описание
openspec list	Выводит список изменений или спецификаций (с --specs).
openspec show	Выводит изменение или спецификацию в формате markdown или JSON.
openspec view	Одноэкранная сводка по спецификациям и изменениям.
openspec validate	Проверяет изменения и спецификации на структурные проблемы.
openspec archive	Перемещает завершённое изменение в архив и обновляет основные спецификации.

Рабочие процессы и схемы

Большинство из этих команд ваш агент выполняет в ходе рабочего процесса.

Команда	Описание
openspec new	Создаёт новый каталог изменения.
openspec status	Статус готовности артефактов для одного или всех активных изменений.
openspec instructions	Инструкции по созданию артефакта, применению или архивированию.
openspec templates	Итоговые пути к шаблонам для артефактов схемы.
openspec schemas	Выводит список доступных схем рабочего процесса.
openspec schema	Просмотр, форкирование или создание схемы (экспериментальная функция).

Мультирепозиторий (бета)

Команда	Описание
openspec store	Создание и управление хранилищами: отдельные репозитории OpenSpec, зарегистрированные на вашей машине.
openspec doctor	Проверяет состояние связей для определённого корня OpenSpec.
openspec context	Выводит рабочий контекст для определённого корня OpenSpec.
openspec workset	Создание, сохранение и открытие личных рабочих представлений.

Утилиты

Команда	Описание
openspec version	Сообщает установленную версию и при необходимости проверяет наличие обновлений.
openspec install	Устанавливает автономный openspec, работающий без Node.js.
openspec feedback	Отправляет отзыв об OpenSpec.
openspec completion	Устанавливает или генерирует автодополнение для оболочки.

Устаревшие

Команда	Описание
openspec change	Существительная форма команд show, list и validate для изменений. CLI выводит предупреждение и отсылает к командам с глагольной формой.
openspec spec	Существительная форма команд show, list и validate для спецификаций, с тем же предупреждением.

Каждая команда принимает -h, --help. Команда openspec без аргументов также принимает:

• -V, --version: выводит версию CLI.
• --no-color: отключает цветной вывод.

openspec init

Инициализирует OpenSpec в проекте.

openspec init                        # текущий каталог, интерактивный выбор инструментов
openspec init --tools claude,cursor  # настроить конкретные инструменты, без запросов
openspec init --tools none           # только структура openspec/, без файлов инструментов

Без --tools команда init предлагает выбрать инструменты в интерактивном терминале. Вне интерактивного терминала она настраивает инструменты, обнаруженные в проекте. Если не обнаружено ни одного, команда завершается с кодом 1 и выводит список допустимых идентификаторов.

Репозитории только с хранилищем

Когда openspec/config.yaml содержит строку store: и в репозитории нет локальных спецификаций или изменений, запускайте init из корня репозитория:

# установить файлы интеграции Claude Code в репозитории кода
openspec init --tools claude

• Файлы интеграции: записываются в репозитории кода.
• openspec/config.yaml: сохраняется побайтово без изменений.
• openspec/specs/ и openspec/changes/: не создаются в репозитории кода.

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

Аргументы

Аргумент	Что это
path	Каталог проекта для инициализации. По умолчанию: текущий каталог. Создаётся, если отсутствует.

Опции

Флаг	Действие
--tools <tools>	Идентификаторы инструментов через запятую, all или none. Пропускает интерактивный выбор инструментов. Идентификаторы перечислены в разделе Поддерживаемые инструменты.
--language <language>	Добавляет инструкцию по языку в новую конфигурацию проекта. Отклоняется, если строка store: в репозитории указывает на внешнее хранилище.
--force	Удаляет файлы из старых структур OpenSpec без запроса. В интерактивном режиме иначе сначала запрашивается подтверждение очистки.
--profile <profile>	Переопределяет профиль глобальной конфигурации для этого запуска: core (стандартный набор рабочих процессов) или custom (рабочие процессы, сохранённые в глобальной конфигурации).
--no-animation	Показывает статический экран приветствия вместо анимированного.

Вывод

Каждый выбранный инструмент получает навыки и команды OpenSpec в собственном каталоге:

▌ OpenSpec structure created
✔ Setup complete for Claude Code

OpenSpec Setup Complete

Created: Claude Code
6 skills and 6 commands in .claude/
Config: openspec/config.yaml (schema: spec-driven)

Getting started:
  Start your first change: /opsx:propose "your idea"

Restart your IDE for the new commands to take effect.

--tools none создаёт только openspec/config.yaml. В уже инициализированном проекте init перезаписывает установленные файлы на месте, а сводка содержит Refreshed: Claude Code и Config: openspec/config.yaml (exists).

Коды выхода

• 0: настройка завершена.
• 1: недопустимое значение --tools или --profile, неинтерактивный запуск без обнаруженных инструментов и без --tools, либо недопустимый вызов для репозитория только с хранилищем.

openspec update

Обновляет установленные файлы инструкций OpenSpec.

openspec update             # обновить инструменты, файлы которых старше CLI
openspec update --force     # перезаписать файлы, даже если они актуальны
openspec update --dry-run   # показать, что изменило бы обновление, ничего не меняя

Команда update находит инструменты, настроенные init, и сравнивает их сгенерированные файлы с версией CLI. Если существует более новый выпуск OpenSpec, она сначала предлагает обновить CLI, а затем повторно запускается с обновлённой версией. Установите OPENSPEC_NO_UPDATE_CHECK=1, чтобы пропустить проверку.

Аргументы

Аргумент	Что это
path	Каталог проекта для обновления. По умолчанию: текущий каталог.

Опции

Флаг	Действие
--force	Перезаписывает файлы каждого настроенного инструмента, даже если они актуальны.
--dry-run	Сообщает о каждом файле, который обновление добавило бы, изменило или удалило, и ничего не записывает. Без проверки обновления CLI и без запросов. Комбинируйте с --force, чтобы предварительно просмотреть принудительное обновление.
--json	С --dry-run выводит план в формате JSON. Без --dry-run команда завершается с кодом 1.

Предварительный просмотр обновления

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

• перемещение файлов OpenSpec из прежнего каталога инструмента (.kimi/ в .kimi-code/, .windsurf/ в .devin/, .codex/ и .agent/ в .agents/);
• сохранение глобальной конфигурации, когда установка, созданная до появления профилей, получает её;
• синхронизация файлов облачного агента GitHub Copilot;
• с --force — настройка инструментов, найденных только в устаревших артефактах, и очистка этих артефактов, включая устаревшие глобальные промпты Codex.

openspec update --dry-run

2 file(s) would change:
  update  .claude/skills/openspec-propose/SKILL.md  (claude)
  add     ~/.config/openspec/config.json  (openspec)

--dry-run --json выводит тот же план в виде одного JSON-документа:

{
  "changes": [
    { "path": ".claude/skills/openspec-propose/SKILL.md", "action": "update", "tool": "claude" },
    { "path": "~/.config/openspec/config.json", "action": "add", "tool": "openspec" }
  ],
  "notes": [],
  "failures": []
}

Поле	Что содержит
changes[].path	Путь относительно проекта. Файл вне проекта, например глобальный навык или глобальная конфигурация, показывается от вашего домашнего каталога как ~/... или как абсолютный путь, если он находится и вне домашнего каталога.
changes[].action	add, update или delete. Файл, новые байты которого совпадают со старыми, не перечисляется.
changes[].tool	Настроенный инструмент, которому принадлежит файл, например claude. Файлы, которые принадлежат самому OpenSpec, а не отдельному инструменту (глобальная конфигурация и очистка устаревших артефактов), обозначаются как openspec.
notes[]	{ code, message } для шага, о котором спросили бы пользователя терминала. legacy-tool-directories: перемещение, о котором интерактивный запуск сначала спрашивает; changes перечисляет его как выполненное. legacy-artifacts: найдены файлы из старой структуры OpenSpec, например slash-команды openspec-proposal.md или маркерные блоки OpenSpec в AGENTS.md. Без --force неинтерактивное обновление их не трогает, поэтому changes тоже; --dry-run --force перечисляет их очистку. Пусто при обычном обновлении.
failures[]	{ tool, error } для каждого инструмента, на котором завершилось бы с ошибкой реальное обновление, включая запись, которую оно не может выполнить: каталог там, где должен быть файл; файл там, где должен быть каталог; или файл или папка без разрешения на запись. Для этого инструмента changes останавливается там же, где останавливается реальное обновление; остальные инструменты всё равно планируются. Сбои, о которых диск сообщает только во время записи, например нехватка места, невозможно предвидеть.

Сбой до планирования, например отсутствие каталога OpenSpec, всё равно выводит ровно один JSON-документ: пустой план плюс массив status с severity, code (update_error) и message. Код выхода — 1.

Вывод

Когда файлы каждого инструмента соответствуют версии CLI:

✓ All 1 tool(s) up to date (v1.7.0)
  Tools: claude

Use --force to refresh files anyway.

Когда файлы инструмента происходят из более старой версии CLI (или при --force, которая вместо этого выводит Force updating 1 tool(s): claude):

Updating 1 tool(s): claude (1.6.0 → 1.7.0)

✔ Updated Claude Code

✓ Updated: Claude Code (v1.7.0)
Tools: Claude Code

Restart your IDE for changes to take effect.

В каталоге без OpenSpec команда update отказывается работать:

✖ Error: No OpenSpec directory found. Run 'openspec init' first.

Коды выхода

• 0: файлы обновлены или всё уже актуально.
• 1: по указанному пути нет каталога OpenSpec или обновление завершилось ошибкой.

openspec config

Просматривает и изменяет глобальную конфигурацию.

openspec config list                  # посмотреть текущие настройки
openspec config set delivery skills   # изменить одно значение
openspec config profile               # интерактивный выбор рабочих процессов

Подкоманда	Что делает
path	Выводит расположение файла конфигурации.
list	Показывает все текущие настройки.
get <key>	Выводит одно значение в исходном виде, пригодном для скриптов.
set <key> <value>	Задаёт значение, приводя его тип.
unset <key>	Удаляет ключ, чтобы применялось значение по умолчанию.
reset	Сбрасывает всю конфигурацию к значениям по умолчанию.
edit	Открывает файл конфигурации в $EDITOR.
profile [preset]	Настраивает режим доставки и рабочие процессы.

Конфигурация является глобальной для вашей машины и хранится в формате JSON по пути, который выводит config path: $XDG_CONFIG_HOME/openspec/config.json, если переменная задана, иначе ~/.config/openspec/config.json (macOS, Linux) или %APPDATA%\openspec\config.json (Windows). Каждая подкоманда принимает --scope <scope>, но сегодня работает только global. Любое другое значение scope завершается с кодом 1 с сообщением Error: Project-local config is not yet implemented.

openspec config path

openspec config path

/Users/you/.config/openspec/config.json

openspec config list

openspec config list          # читаемые настройки плюс сводка профиля
openspec config list --json   # исходная конфигурация в формате JSON

Опции

Флаг	Действие
--json	Выводит объект конфигурации в формате JSON.

Вывод

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

featureFlags: {}
profile: core
delivery: both

Profile settings:
  profile: core (default)
  delivery: both (default)
  workflows: propose, explore, apply, update, sync, archive (from core profile)

openspec config get

openspec config get delivery

Аргументы

Аргумент	Что это
key	Ключ для чтения. Точки позволяют обращаться к вложенным значениям (featureFlags.workspaces).

Вывод

Само значение в чистом виде, готовое для скриптов. Объекты выводятся как компактный JSON:

both

Коды выхода

• 0: значение выведено.
• 1: у ключа нет значения, и ничего не выводится.

openspec config set

openspec config set delivery skills
openspec config set featureFlags.workspaces true

Аргументы

Аргумент	Что это
key	Ключ для записи; для вложенных значений используется точечная нотация.
value	Новое значение. true/false преобразуются в булевы значения, числовые строки — в числа.

Опции

Флаг	Действие
--string	Сохраняет значение как строку, пропуская приведение типа.
--allow-unknown	Разрешает ключи, неизвестные схеме.

Вывод

Set featureFlags.workspaces = true

Неизвестные ключи и недопустимые значения приводят к завершению с кодом 1 до сохранения чего-либо:

Error: Invalid configuration key "bogus.key". Unknown top-level key "bogus".
Use "openspec config list" to see available keys.
Pass --allow-unknown to bypass this check.

Error: Invalid configuration - delivery: Invalid option: expected one of "both"|"skills"|"commands"

Если файл конфигурации существует, но не содержит JSON-объект — потому что это вообще не валидный JSON или потому что его корень является чем-то другим, например null или массивом, — config set, config unset и config profile завершаются с кодом 1 и оставляют файл без изменений. Исправьте его с помощью openspec config edit или замените с помощью openspec config reset --all:

Error: /home/you/.config/openspec/config.json could not be parsed, so it was left unchanged.
Fix it with "openspec config edit", or reset it with "openspec config reset --all".

Пока это не исправлено, телеметрия и проверка обновлений остаются отключёнными.

openspec config unset

openspec config unset delivery

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

Unset delivery (reverted to default)

Ключ, у которого вообще нет значения, выводит Key "featureFlags.nothere" was not set. В обоих случаях код выхода — 0. При наличии файла конфигурации, который не удаётся разобрать, команда вместо этого завершается с кодом 1, как и в случае config set.

openspec config reset

openspec config reset --all      # запрашивает подтверждение
openspec config reset --all -y   # без запроса

Опции

Флаг	Действие
--all	Обязательный. Сбрасывает всё.
-y, --yes	Пропускает запрос подтверждения.

Вывод

Configuration reset to defaults

Без --all команда завершается с кодом 1 и выводит строку использования.

Коды выхода

• 0: сброс выполнен или вы ответили «нет» на запрос.
• 1: отсутствует --all.
• 130: запрос отменён с помощью Ctrl-C.

openspec config edit

openspec config edit

Открывает файл конфигурации в $EDITOR (с запасным вариантом $VISUAL), создавая его со значениями по умолчанию, если он отсутствует. После закрытия редактора файл проверяется. Невалидный JSON или недопустимая конфигурация приводят к завершению с кодом 1.

Значение редактора может содержать аргументы и пути в кавычках, например code --wait или "/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl" -w. Оно разбивается на слова без оболочки, поэтому $VAR, ~ и ; передаются буквально. Редактор, который не может запуститься или завершается с ненулевым кодом, выводит однострочную ошибку, после чего команда завершается с кодом 1.

Если редактор не настроен, команда завершается с кодом 1:

Error: No editor configured
Set the EDITOR or VISUAL environment variable to your preferred editor
Example: export EDITOR=vim

openspec config profile

openspec config profile        # интерактивный выбор (требуется терминал)
openspec config profile core   # применить пресет core напрямую

Аргументы

Аргумент	Что это
preset	Необязательное имя пресета. Существует только core. Он выбирает основные рабочие процессы и сохраняет вашу настройку доставки.

Без пресета интерактивный выбор показывает текущий режим доставки и рабочие процессы, позволяет изменить один или оба (режим доставки: both, только skills или только commands; рабочие процессы: список с флажками), выводит различия и внутри проекта OpenSpec предлагает запустить openspec update за вас. Вне терминала команда завершается с кодом 1:

Interactive mode required. Use `openspec config profile core` or set config via environment/flags.

Вывод

Изменённая конфигурация не попадает в проекты, пока они не обновятся:

Config updated. Run `openspec update` in your projects to apply.

Коды выхода

• 0: профиль сохранён или вы оставили текущие настройки.
• 1: неизвестный пресет, отсутствие терминала или сбой предложенного openspec update.
• 130: выбор отменён с помощью Ctrl-C.

openspec list

Перечисляет изменения или спецификации с помощью --specs.

openspec list                    # active changes, most recently modified first
openspec list --archived         # archived changes
openspec list --all              # active and archived changes
openspec list --specs            # specs with requirement counts
openspec list --json             # machine-readable, includes the resolved root

Строки берутся из openspec/changes/ и openspec/specs/ в разрешенном корне. Список изменений по умолчанию пропускает openspec/changes/archive/.

Опции

Флаг	Действие
--specs	Перечисляет спецификации вместо изменений.
--changes	Перечисляет изменения. Это значение по умолчанию.
--archived	Перечисляет только архивные изменения. Нельзя сочетать с --specs.
--all	Перечисляет активные и архивные изменения. Нельзя сочетать с --specs. Имеет приоритет над --archived.
--sort <order>	recent (сначала последние измененные) или name. По умолчанию: recent. Спецификации всегда сортируются по имени.
--json	Выводит JSON вместо таблицы.
--store <id>	Использует зарегистрированное хранилище как корень OpenSpec вместо текущего проекта.

Вывод

По одной строке на изменение: имя, статус задач, время последнего изменения. В столбце статуса отображается No tasks, 2/5 tasks или ✓ Complete.

Changes:
  add-rate-limit     No tasks      just now

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

Changes:
  add-rate-limit     No tasks      just now

Archived Changes:
  2026-08-10-add-login     ✓ Complete    2d ago

Specs:
  api     requirements 1

--json добавляет количество задач и status со значением no-tasks, in-progress или complete:

{
  "changes": [
    {
      "name": "add-rate-limit",
      "completedTasks": 0,
      "totalTasks": 0,
      "lastModified": "2026-08-11T13:44:40.171Z",
      "status": "no-tasks"
    }
  ],
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

С --archived или --all каждый объект изменения включает логическое поле archived. Объединенный массив использует выбранный порядок сортировки. Архивное изменение может по-прежнему иметь статус in-progress, если в его отслеживаемом файле задач есть невыполненные задачи. Без любого из этих флагов структура JSON остается неизменной.

Пустой список выводит No active changes found., No archived changes found., No changes found. или No specs found. и по-прежнему завершается с кодом 0.

Изменение — это каталог непосредственно внутри openspec/changes/. В отличие от спецификаций, изменения не могут быть вложены в папку пространства имен. Папка, такая как changes/mobile/, которая только оборачивает изменение (changes/mobile/refresh-token/), перечисляется со статусом not a change, за которым следует предупреждение с указанием вложенных каталогов. --json помечает эту запись массивом nested и добавляет массив warnings верхнего уровня. show, status, validate и archive отказываются работать с такой папкой с тем же сообщением. Чтобы исправить это, переместите изменение вверх и включите пространство имен в его имя:

mv openspec/changes/mobile/refresh-token openspec/changes/mobile-refresh-token
rmdir openspec/changes/mobile

Коды выхода

• 0: список выведен, даже если он пуст.
• 1: корень OpenSpec не найден (вне проекта, без --store).

openspec show

Выводит изменение или спецификацию в виде Markdown или JSON.

openspec show add-rate-limit              # change: prints proposal.md
openspec show add-rate-limit --diff       # change: append requirement diffs
openspec show api                         # spec: prints spec.md
openspec show api --json --no-scenarios   # spec JSON without scenario text

Без имени show запрашивает изменение или спецификацию, затем выводит список элементов для выбора. Вне интерактивного терминала он завершается с кодом 1 и выводит прямые формы вместо этого.

Аргументы

Аргумент	Что это такое
item-name	Изменение или спецификация для показа, по имени папки (add-rate-limit, api).

Опции

Флаг	Действие
--json	Выводит структурированный JSON вместо сырого Markdown.
--type <change|spec>	Выбирает тип, когда изменение и спецификация имеют одинаковое имя.
--no-interactive	Никогда не запрашивает: отсутствующее имя становится ошибкой.
--deltas-only	JSON, изменение: ограничивает вывод дельтами. JSON изменения уже содержит только дельты, поэтому вывод совпадает с обычным --json.
--requirements-only	Устаревший алиас для --deltas-only. Выводит предупреждение в stderr.
--diff	Изменение: добавляет дельта-диффы по каждому требованию. Игнорируется с предупреждением для спецификаций.
--requirements	JSON, спецификация: сохраняет текст требований, очищает массивы scenarios.
--no-scenarios	JSON, спецификация: тот же вывод, что и --requirements.
-r, --requirement <id>	JSON, спецификация: выводит одно требование по позиции с 1. Нельзя сочетать с --requirements.
--store <id>	Использует зарегистрированное хранилище как корень OpenSpec вместо текущего проекта.

Флаги, которые не применяются к разрешенному типу, игнорируются с предупреждением в stderr.

Вывод

Текстовый режим — это прямая передача: изменение выводит свой proposal.md, спецификация выводит свой spec.md.

# Add rate limiting

Зачем

Неаутентифицированные клиенты могут исчерпать ресурсы API.

Какие изменения

• Добавить ограничение частоты запросов для каждого клиента в публичном API.

Для изменения `--diff` сначала выводит предложение, затем раздел `Specifications Changed (diffs)`. Требования ADDED включают полный текст. Требования REMOVED сохраняют указанные автором Reason и Migration. Требования RENAMED показывают FROM и TO. Требования MODIFIED показывают унифицированный diff относительно соответствующего требования в основной спецификации.

Если заголовок MODIFIED совпадает только после нормализации регистра или пробелов, вывод включает и diff, и предупреждение о том, что сопоставление в архиве выполняется точно. Если основная спецификация или требование отсутствует, вывод выдаёт предупреждение и печатает полный блок дельты. Блок MODIFIED без текстовых различий печатает `(no textual changes)`.

Изменение с `--json` имеет форму дельты:

```json
{
  "id": "add-rate-limit",
  "title": "Add rate limiting",
  "deltaCount": 1,
  "deltas": [
    {
      "spec": "api",
      "operation": "ADDED",
      "description": "Add requirement: The API SHALL limit each client to 100 requests per minute.",
      "requirement": {
        "name": "Rate limit",
        "text": "The API SHALL limit each client to 100 requests per minute.",
        "scenarios": [
          {
            "name": "Client exceeds the limit",
            "rawText": "- **WHEN** a client sends its 101st request within a minute\n- **THEN** the API responds 429"
          }
        ]
      },
      ...
    }
  ],
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

Каждое требование содержит своё name — текст заголовка после Requirement:. Это имя, с которым архив сопоставляет записи MODIFIED, REMOVED и RENAMED. Каждый сценарий содержит своё name — текст заголовка после Scenario:. Завершающая последовательность # в любом из этих заголовков не входит в имя.

--json --diff сохраняет эту структуру верхнего уровня. Дельта MODIFIED получает строку diff, строку warning или обе. Остальные операции не меняются. Пустая строка diff означает, что основной блок и блок дельты текстуально идентичны.

Спецификация с --json перечисляет свои требования со сценариями. Требования и сценарии содержат те же поля name, что и JSON изменения:

{
  "id": "api",
  "title": "api",
  "overview": "Public HTTP API behavior.",
  "requirementCount": 1,
  "requirements": [
    {
      "name": "Health endpoint",
      "text": "The API SHALL expose a health endpoint.",
      "scenarios": [
        {
          "name": "Health check succeeds",
          "rawText": "- **WHEN** a client requests GET /health\n- **THEN** the API responds 200"
        }
      ]
    }
  ],
  "metadata": {
    "version": "1.0.0",
    "format": "openspec"
  },
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

Для неизвестного имени предлагаются близкие совпадения: Unknown item 'does-not-exist'. Did you mean: add-rate-limit, api?. Имя, совпадающее и с изменением, и со спецификацией, вызывает ошибку и требует указать --type.

Коды выхода

• 0: элемент напечатан.
• 1: неизвестное или неоднозначное имя, отсутствие имени вне терминала, индекс -r, выходящий за допустимый диапазон, комбинация --requirements с -r, или невозможность прочитать дельту или основную спецификацию для --diff.

openspec view

Выводит дашборд спецификаций и изменений на одном экране.

openspec view   # сводка по проекту на одном экране

view печатает дашборд один раз и завершает работу. Он не считывает нажатия клавиш. Изменения группируются по прогрессу задач: Draft (задач ещё нет), Active (задачи в работе, с индикатором прогресса и процентом), Completed (все задачи отмечены). Спецификации выводятся с количеством требований, начиная с наибольшего.

Опции

Флаг	Действие
--store <id>	Использовать зарегистрированное хранилище в качестве корня OpenSpec вместо текущего проекта.

Вывод

OpenSpec Dashboard

════════════════════════════════════════════════════════════
Summary:
  ● Specifications: 1 specs, 1 requirements
  ● Draft Changes: 1
  ● Active Changes: 0 in progress
  ● Completed Changes: 0

Draft Changes
────────────────────────────────────────────────────────────
  ○ add-rate-limit

Specifications
────────────────────────────────────────────────────────────
  ▪ api                            1 requirement

════════════════════════════════════════════════════════════

Use openspec list --changes or openspec list --specs for detailed views

Строка сводки Task Progress появляется, когда в каком-либо изменении есть задачи в работе.

Каждое активное изменение также показывает свою схему и состояния артефактов под индикатором прогресса задач:

    └─ [spec-driven] proposal✓ specs→ design→ tasks✓

Маркер	Состояние артефакта
✓	Его результат существует. Существующий артефакт задач считается готовым, даже если его чек-лист не завершён.
→	Он готов к созданию.
Без маркера	Он заблокирован из-за отсутствующей зависимости.
(skipped)	Изменение пропускает его.

Если workflow не удаётся загрузить, view печатает предупреждение и сохраняет видимость прогресса задач этого изменения. Запустите openspec status --change <name>, чтобы отдельно проверить workflow. После openspec view --store <id> передайте тот же --store <id> в status.

Коды выхода

• 0: дашборд напечатан.
• 1: корень OpenSpec не найден (вне проекта, без --store).

openspec validate

Проверяет изменения и спецификации на структурные проблемы.

openspec validate add-rate-limit   # одно изменение или спецификация, по имени
openspec validate --all            # все изменения и спецификации

Без имени и без флага массовой проверки validate предлагает выбрать элементы. Вне интерактивного терминала он завершается с кодом 1 и вместо этого печатает флаги массовой проверки.

Аргументы

Аргумент	Что это
item-name	Изменение или спецификация для проверки, по имени папки (add-rate-limit, api).

Опции

Флаг	Действие
--all	Проверить все изменения и спецификации.
--changes	Проверить все изменения.
--specs	Проверить все спецификации.
--archived	Проверить завершённость задач в изменениях из архива, не проверяя применённые дельты спецификаций.
--strict	Считать предупреждения ошибками.
--type <change|spec>	Выбрать тип, когда изменение и спецификация имеют одинаковое имя.
--json	Вывести структурированный отчёт вместо текста.
--report <mode>	Вывод массовой проверки: full (по умолчанию) или findings. Требует явно заданной области массовой проверки.
--concurrency <n>	Максимальное число параллельных проверок в массовых запусках. По умолчанию: OPENSPEC_CONCURRENCY, иначе 6.
--no-interactive	Никогда не запрашивать: отсутствующее или неоднозначное имя становится ошибкой.
--store <id>	Использовать зарегистрированное хранилище в качестве корня OpenSpec вместо текущего проекта.

Вывод

Массовые запуски печатают одну строку состояния на элемент, затем любые замечания и в конце итоги:

✓ change/add-rate-limit
✓ spec/api
Totals: 2 passed, 0 failed (2 items)

Замечания по чекбоксам задач

Прогресс учитывает только чекбоксы и ничего больше, поэтому файл задач, записанный обычными маркерами списка, читается как ноль задач: openspec list и openspec status сообщают об отсутствии работы, а openspec archive нечего помечать как незавершённое. Validate выдаёт WARNING для каждого отслеживаемого файла задач, в котором перечислена работа без чекбокса:

⚠ [WARNING] tasks.md: This change counts as 0 tasks: no line in its tracked task files is a checkbox, so "openspec list" and "openspec status" report no work and "openspec archive" has nothing to flag as incomplete. Write each task as "- [ ] 1.1 Description".

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

Ограждённые блоки, HTML-комментарии, front matter YAML и код с отступами не сканируются, поэтому вставленный пример из терминала никогда не принимается за список задач.

Замечания при слиянии с архивом

Для изменений validate запускает механизм слияния архива с текущими основными спецификациями без записи файлов. Он сообщает о конфликтах слияния, например об отсутствующей цели MODIFIED или конфликтующем требовании ADDED, как INFO:

ℹ [INFO] api/spec.md: Archive would refuse this delta: api MODIFIED failed for header "### Requirement: Rate limiting" - not found

Эти замечания появляются даже при успешной проверке, как в текстовом, так и в JSON-выводе. INFO никогда не меняет код выхода, в том числе при --strict: отсутствующая цель может относиться к соседнему изменению, которое ещё не архивировано. Дельты, уже синхронизированные с основными спецификациями, подчиняются существующим правилам слияния архива.

Эта проверка не запускает последующую проверку объединённых спецификаций или проверки вывода из обращения, выполняемые архивом. Отчёт без замечаний не гарантирует успешного завершения archive.

Если предварительная проверка слияния не может запуститься, замечание INFO объясняет причину. Существующие замечания проверки и код выхода остаются неизменными.

Элемент с ошибкой перечисляет каждую проблему и способ исправления:

Change 'add-rate-limit' has issues
✗ [ERROR] api/spec.md: ADDED "Rate limiting" must include at least one scenario
Next steps:
  - Ensure change has deltas in specs/: use headers ## ADDED/MODIFIED/REMOVED/RENAMED Requirements
  - Each requirement MUST include at least one #### Scenario: block
  - Debug parsed deltas: openspec show add-rate-limit --json --deltas-only

--json печатает один отчёт для запуска:

{
  "items": [
    {
      "id": "add-rate-limit",
      "type": "change",
      "valid": true,
      "issues": [],
      "durationMs": 2
    }
  ],
  "summary": {
    "totals": {
      "items": 1,
      "passed": 1,
      "failed": 0
    },
    "byType": {
      "change": {
        "items": 1,
        "passed": 1,
        "failed": 0
      }
    }
  },
  "version": "1.0",
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

Записи issues содержат level со значением ERROR, WARNING или INFO.

Коды выхода

• 0: все проверенные элементы прошли проверку, включая пустую область массовой проверки.
• 1: элемент не прошёл проверку, запрос отчёта недопустим, openspec/config.yaml невозможно прочитать или он не является допустимым YAML, либо запуск завершился ошибкой (например, неизвестное имя или отсутствие корня OpenSpec). Конфигурация, которую невозможно прочитать или разобрать, останавливает запуск до проверки любого элемента; при --json она сообщается как одна запись status с кодом unreadable_config или unparseable_config.

--report full|findings

Выбирает вывод для явно заданной области массовой проверки:

• full: все элементы. Это значение по умолчанию. Явный --report full сохраняет существующую структуру вывода без добавления метаданных отчёта.
• findings: только элементы с проблемами, включая прошедшие проверку элементы с предупреждениями или информационными сообщениями. При этом проверяются все элементы. Итоги, поведение строгого режима и коды выхода не меняются.

openspec validate --all --report findings
openspec validate --archived --report findings --json

Области

Флаги	report.scope для findings
--all	all
--changes	changes
--specs	specs
--changes --specs или --all с любым из этих флагов	all
--archived	archived

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

Текстовый вывод findings

Человекочитаемый вывод: stdout печатает Scope: <scope> (<count> items), затем итоги. Если нет элементов с проблемами:

Scope: all (2 items)
No item findings.
Totals: 2 passed, 0 failed (2 items)

Метки элементов с проблемами, метки уровня серьёзности, пути и сообщения печатаются в stderr. Сбои в активной области сохраняют после итогов подсказку о повторном запуске Details:. Существующий баннер корня и вывод прогресса могут предшествовать отчёту.

JSON-вывод findings

--report findings --json печатает один документ. В этом примере два элемента без проблем:

{
  "report": {
    "kind": "validation-findings",
    "version": "1.0",
    "scope": "all",
    "returnedItems": 0,
    "totalItems": 2
  },
  "itemFindings": [],
  "summary": {
    "totals": { "items": 2, "passed": 2, "failed": 0 },
    "byType": {
      "change": { "items": 1, "passed": 1, "failed": 0 },
      "spec": { "items": 1, "passed": 1, "failed": 0 }
    }
  },
  "root": { "path": "/Users/you/projects/my-app", "source": "nearest" }
}

• report.kind и report.version: определяют структуру validation-findings версии 1.0. На верхнем уровне нет version или items.
• report.returnedItems и report.totalItems: считают соответственно возвращённые записи и все проверенные элементы.
• itemFindings: полные записи элементов, у которых массив issues не пуст. Включает проблемы ERROR, WARNING и INFO. Каждая запись сохраняет id, type, valid, issues и durationMs. Для архивных элементов используется type: "change".
• summary: итоги всего запуска и счётчики по типам, а не счётчики возвращённого подмножества. Пустая область имеет нулевые итоги и завершается с кодом 0.
• root: те же метаданные выбранного корня, что и в полном отчёте.

Сохранение записей: возвращённые элементы сохраняют порядок полного отчёта и любые дополнительные поля элементов или проблем. Фильтрация не переписывает сообщения или местоположения, включая необязательные поля line и column.

Сбои команды: сбои выбора корня или обнаружения элементов сохраняют существующую диагностику status и завершаются с кодом 1. Они не возвращают завершённый отчёт findings или успешный пустой отчёт.

Некорректные запросы отчёта

Оба явных режима отчёта отклоняют следующие запросы до выбора корня или обнаружения элементов:

• Неподдерживаемое значение отчёта, включая пустую строку.
• Позиционное имя элемента, даже при наличии флага массовой проверки.
• Отсутствие явной области массовой проверки.
• --archived в сочетании с --all, --changes или --specs.

В JSON-режиме отклонённый запрос завершается с кодом 1 и содержит только массив status из одного элемента. В нём нет root или полезной нагрузки отчёта:

openspec validate --all --report bogus --json

{
  "status": [
    {
      "severity": "error",
      "code": "invalid_validation_report_request",
      "message": "Unknown validation report 'bogus'.",
      "fix": "Use --report full|findings with --all, --changes, --specs, or --archived, without an item name. Do not combine archived and active scopes."
    }
  ]
}

В человекочитаемом режиме ошибка печатается в stderr. Одиночный --report без значения является синтаксической ошибкой Commander в stderr, в том числе с --json; он не использует эту диагностическую обёртку.

Внешняя фильтрация полного отчёта

Чтобы получить пользовательское JSON-представление, отфильтруйте полный отчёт с помощью jq или PowerShell. Эти примеры скриптов сохраняют код выхода проверки и не изменяют документы ошибок команды.

В Bash с jq:

if validation_json=$(openspec validate --all --json); then
  validation_exit=0
else
  validation_exit=$?
fi
printf '%s\n' "$validation_json" |
  jq 'if has("items") then .items |= map(select(.issues | length > 0)) else . end'
exit "$validation_exit"

В PowerShell:

$validationJson = openspec validate --all --json
$validationExit = $LASTEXITCODE
$validationReport = $validationJson | ConvertFrom-Json
if ($validationReport.PSObject.Properties.Name -contains 'items') {
  $validationReport.items = @($validationReport.items | Where-Object { $_.issues.Count -gt 0 })
}
$validationReport | ConvertTo-Json -Depth 100
exit $validationExit

Эти пользовательские представления сохраняют ключи полного отчёта, но пропускают элементы без проблем. Они не являются ни полными отчётами full-v1, ни версионированной структурой --report findings.

openspec archive

Перемещает завершённое изменение в архив и обновляет основные спецификации.

openspec archive add-rate-limit -y                # архивировать одно изменение, объединить его дельты
openspec archive add-rate-limit -y --skip-specs   # архивировать, не затрагивая спецификации

Без указания имени архивирование предлагает выбрать изменение. Вне интерактивного терминала команда завершается с кодом 1 и выводит команду для повторного запуска.

Аргументы

Аргумент	Описание
change-name	Изменение для архивирования, по имени папки (add-rate-limit).

Параметры

Флаг	Действие
-y, --yes	Отвечать «да» на все подтверждения: обновление спецификаций, незавершённые задачи, пропущенная валидация.
--skip-specs	Архивировать, не затрагивая основные спецификации (инфраструктурные, инструментальные или документационные изменения).
--no-validate	Пропустить валидацию. Сначала архивирование попросит подтверждение, и -y ответит на него.
--json	Вывести структурированный результат вместо текста. Требует --yes для подтверждения обновления спецификаций.
--store <id>	Использовать зарегистрированное хранилище в качестве корня OpenSpec вместо текущего проекта.

Вывод

Успешный запуск отображает статус задач, предпросматривает обновления спецификаций, применяет их и сообщает имя папки архива:

Task status: ✓ Complete

Specs to update:
  api: update
Applying changes to openspec/specs/api/spec.md:
  + 1 added
Totals: + 1, ~ 0, - 0, → 0
Specs updated successfully.
Change 'add-rate-limit' archived as '2026-08-11-add-rate-limit'.

Папка изменения полностью перемещается в openspec/changes/archive/2026-08-11-add-rate-limit/, с сегодняшней датой в качестве префикса имени. Каждая дельта объединяется с основной спецификацией: добавленное требование выше было включено в openspec/specs/api/spec.md. Без -y архивирование показывает предпросмотр и спрашивает перед обновлением. Отказ всё равно архивирует изменение и оставляет спецификации нетронутыми.

С --json --yes:

{
  "archive": {
    "change": "add-rate-limit",
    "archivedAs": "2026-08-11-add-rate-limit",
    "path": "/Users/you/projects/my-app/openspec/changes/archive/2026-08-11-add-rate-limit",
    "specsUpdated": true,
    "totals": {
      "added": 1,
      "modified": 0,
      "removed": 0,
      "renamed": 0
    }
  },
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

Перед архивированием изменение проходит валидацию, и при ошибках оно отклоняется:

Validation errors in change delta specs:
  ✗ ADDED "Rate limiting" must include at least one scenario

Validation failed. Please fix the errors before archiving.
To skip validation (not recommended), use --no-validate flag.

Незавершённые задачи выводят предупреждение, но не блокируют. В интерактивном режиме архивирование спрашивает, продолжать ли, а -y продолжает автоматически:

Task status: 1/2 tasks
Warning: 1 incomplete task(s) found. Continuing due to --yes flag.

Коды завершения

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

openspec new

Создаёт новый каталог изменений.

openspec new change add-caching                                # только метаданные
openspec new change add-search --goal "Пользователи могут искать документы"  # записать цель

У команды new есть одна подкоманда — new change <name>. Она создаёт openspec/changes/<name>/, содержащий единственный файл метаданных .openspec.yaml:

schema: spec-driven
created: 2026-08-11

Артефакты (proposal, specs, design, tasks) здесь не создаются. Вы пишете их позже, а openspec status подскажет, какой следующий.

Аргументы

Аргумент	Описание
name	Имя папки для изменения (add-caching).

Параметры

Флаг	Действие
--description <text>	Также создать README.md в каталоге изменения с этим текстом.
--goal <text>	Сохранить строку goal: в .openspec.yaml.
--schema <name>	Схема рабочего процесса для изменения. По умолчанию: spec-driven, единственная поставляемая схема.
--json	Вывести созданное изменение в формате JSON вместо текста.
--store <id>	Использовать зарегистрированное хранилище в качестве корня OpenSpec вместо текущего проекта.

Вывод

Created change 'add-caching' at openspec/changes/add-caching/
Schema: spec-driven
Next: openspec status --change add-caching

Если каталог openspec/ не найден, new change создаёт его в текущей директории и сообщает об этом:

Created change 'add-caching' at openspec/changes/add-caching/
Schema: spec-driven
Next: openspec status --change add-caching

Note: no OpenSpec root was found here, so one was created at openspec/.
Run `openspec init` to finish setting this project up, or delete that directory if you meant a different project.

Уведомление выводится в stdout вместе с остальным текстовым выводом и никогда не появляется при использовании --json.

С --json в проекте, который уже содержит openspec/:

{
  "change": {
    "id": "add-caching",
    "path": "/Users/you/projects/my-app/openspec/changes/add-caching",
    "metadataPath": "/Users/you/projects/my-app/openspec/changes/add-caching/.openspec.yaml",
    "schema": "spec-driven"
  },
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

Если каталог openspec/ не найден и new change создал его, JSON имеет ту же структуру. root.path — это каталог, из которого вы запустили команду, а root.source принимает значение implicit:

"root": {
  "path": "/Users/you/projects/my-app",
  "source": "implicit"
}

Коды завершения

• 0: изменение создано.
• 1: изменение уже существует или схема неизвестна.

openspec status

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

openspec status --change add-rate-limit          # режим чек-листа
openspec status --change add-rate-limit --json   # структурированный отчёт
openspec status --all                            # все активные изменения
openspec status --all --json                     # один пакетный отчёт

Когда существуют активные изменения, укажите ровно один из вариантов --change или --all. Если не указан ни один из них, status завершается с кодом 1 и выводит список доступных изменений, даже если существует только одно:

✖ Error: Missing required option --change (or --all for every active change). Available changes:
  add-rate-limit

Когда в проекте нет активных изменений, status выводит No active changes. Create one with: openspec new change <name> и завершается с кодом 0 даже без какого-либо из этих флагов. С --all --json то же пустое состояние выглядит как { "changes": [], "message": "No active changes.", "root": ... }.

Опции

Флаг	Действие
--change <id>	Изменение, о котором выводится отчёт; указывается по имени папки.
--all	Вывести отчёт по всем активным изменениям, отсортированным по имени. Нельзя комбинировать с --change.
--schema <name>	Переопределить схему, автоматически определённую из openspec/config.yaml. Неизвестное имя является ошибкой.
--json	Вывести структурированный отчёт вместо текста.
--store <id>	Использовать зарегистрированное хранилище в качестве корня OpenSpec вместо текущего проекта.

Вывод

Чек-лист артефактов схемы: [x] — завершён, [ ] — готов к написанию, [-] — заблокирован, пока не существуют артефакты, от которых он зависит.

Change: add-rate-limit
Schema: spec-driven
Change root: /Users/you/projects/my-app/openspec/changes/add-rate-limit
Progress: 2/4 artifacts complete

[x] proposal
[x] specs
[ ] design
[-] tasks (blocked by: design)

Next: openspec instructions design --change "add-rate-limit" --json

Строка Next: называет единственную команду, которая продвигает изменение вперёд, поэтому одной команды openspec status достаточно, чтобы вернуться к работе над изменением в новой сессии. Пока планирование не завершено, она указывает следующий готовый артефакт, а когда существуют все артефакты планирования — openspec instructions apply:

[x] proposal
[x] specs
[x] design
[x] tasks

All planning artifacts complete!
Next: openspec instructions apply --change "add-rate-limit" --json

Она содержит --store <id>, когда разрешённым корнем является хранилище, и называет ту же команду, что и предложение nextSteps в JSON.

--json добавляет зависимости для каждого артефакта, разрешённые пути к файлам и предлагаемый следующий шаг. Сокращённый пример:

{
  "changeName": "add-rate-limit",
  "schemaName": "spec-driven",
  "isComplete": false,
  "nextSteps": [
    "Run openspec instructions design --change \"add-rate-limit\" --json before writing that artifact."
  ],
  "artifacts": [
    {
      "id": "proposal",
      "outputPath": "proposal.md",
      "status": "done",
      "requires": []
    },
    {
      "id": "design",
      "outputPath": "design.md",
      "status": "ready",
      "requires": [
        "proposal"
      ]
    },
    {
      "id": "tasks",
      "outputPath": "tasks.md",
      "status": "blocked",
      "requires": [
        "specs",
        "design"
      ],
      "missingDeps": [
        "design"
      ]
    }
  ]
}

С --all --json поле changes содержит тот же объект статуса для каждого изменения, без отдельного root для каждого изменения. Выбранный корень указывается один раз в объекте-обёртке. В этом примере сокращены поля статуса для каждого изменения, показанные выше:

{
  "changes": [
    {
      "changeName": "add-rate-limit",
      "schemaName": "spec-driven",
      "artifacts": []
    }
  ],
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

Если одно из изменений не удаётся загрузить, пакетная обработка продолжается. Запись этого изменения содержит changeName и диагностическое сообщение в поле status, в то время как остальные записи остаются доступными. Команда завершается с кодом 1, в том числе в режиме JSON, чтобы CI не принимал неполный отчёт за успешный. Вывод JSON при этом остаётся единым документом, пригодным для разбора.

Коды выхода

• 0: выведен статус по всем запрошенным изменениям; пустой отчёт --all также завершается с кодом 0.
• 1: запрошенное изменение не удалось загрузить, отсутствует --change или --all, оба флага использованы вместе, изменение не существует или указано неизвестное переопределение схемы.

openspec instructions

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

openspec instructions proposal --change add-rate-limit   # как написать один артефакт
openspec instructions apply --change add-rate-limit      # как реализовать изменение
openspec instructions archive --change add-rate-limit    # входные данные для архивирования

Аргументы

Аргумент	Описание
artifact	Идентификатор артефакта из схемы (proposal, specs, design, tasks в spec-driven) или зарезервированные слова apply и archive.

Опции

Флаг	Действие
--change <id>	Изменение, для которого нужно сгенерировать инструкции. Обязательный.
--schema <name>	Переопределить схему. Иначе она определяется автоматически из config.yaml.
--json	Вывести структурированный объект вместо текста.
--store <id>	Использовать зарегистрированное хранилище в качестве корня OpenSpec вместо текущего проекта.

Вывод

Вариант для артефакта выводит один блок инструкции: задачу, файл для записи, способ его написания, шаблон артефакта и то, что разблокируется после его завершения.

<artifact id="proposal" change="add-rate-limit" schema="spec-driven">

<task>
Create the proposal artifact for change "add-rate-limit".
Initial proposal document outlining the change
</task>

<output>
Write to: /Users/you/projects/my-app/openspec/changes/add-rate-limit/proposal.md
</output>

<instruction>
Create the proposal document that establishes WHY this change is needed.
...

Вариант apply выводит файлы контекста, прогресс по задачам и рабочую инструкцию:

## Apply: add-rate-limit
Schema: spec-driven

### Context Files
- proposal: /Users/you/projects/my-app/openspec/changes/add-rate-limit/proposal.md
- specs: /Users/you/projects/my-app/openspec/changes/add-rate-limit/specs/api/spec.md
- tasks: /Users/you/projects/my-app/openspec/changes/add-rate-limit/tasks.md

### Progress
1/3 complete

### Tasks
- [x] 1.1 Add rate limit middleware
- [ ] 1.2 Return 429 with Retry-After header
- [ ] 1.3 Add tests for burst traffic

### Instruction
Read context files, work through pending tasks, mark complete as you go.
Pause if you hit blockers or need clarification.

No project context or operation guidance configured.

Когда требуемые артефакты отсутствуют, apply вместо этого выводит ### ⚠️ Blocked и перечисляет их. Вариант archive выводит имя изменения, а также контекст проекта и руководства по операциям из конфигурации, если они заданы. Если ничего не настроено, команда сообщит об этом и больше ничего.

С --json каждый вариант возвращает один объект. Вариант для артефакта начинается так:

{
  "changeName": "add-rate-limit",
  "artifactId": "proposal",
  "schemaName": "spec-driven",
  "changeDir": "/Users/you/projects/my-app/openspec/changes/add-rate-limit",
  ...

и продолжается полями outputPath, existingOutputPaths, полными строками instruction и template, dependencies, unlocks и root. Вариант apply содержит contextFiles, progress, tasks, taskTrackingConfigured, state (blocked, ready, all_done) и instruction.

Каждая запись в tasks содержит id, description, done, sourcePath и line. sourcePath — абсолютный путь к отслеживаемому файлу, из которого взята задача. line — номер строки чекбокса задачи в этом файле (нумерация с единицы).

taskTrackingConfigured всегда имеет логический тип: значение true, когда в схеме для apply.tracks задано значение, отличное от null, даже если ни один файл не совпал, и false в противном случае. Если отслеживающий файл, соответствующий шаблону, не удаётся прочитать, unavailableTrackingFiles содержит его абсолютный путь в поле path и причину ошибки в поле reason. Это поле опускается, когда все совпавшие файлы читаемы. Читаемые файлы по-прежнему учитываются в tasks и progress, но state не может быть all_done, пока не прочитаны все совпавшие файлы.

Коды выхода

• 0: инструкции выведены.
• 1: неизвестный артефакт, неизвестное изменение, неизвестная схема или отсутствует --change. Каждое сообщение об ошибке перечисляет допустимые значения.

Шаблоны openspec

Выводит разрешённые пути к шаблонам для артефактов схемы.

openspec templates          # default schema: spec-driven
openspec templates --json   # map of artifact ids to paths

Опции

Флаг	Действие
--schema <name>	Схема для разрешения. По умолчанию: spec-driven.
--json	Вывести JSON-карту соответствия идентификаторов артефактов путям к шаблонам.

Вывод

Schema: spec-driven
Source: package

proposal:
  /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/proposal.md
specs:
  /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/spec.md
design:
  /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/design.md
tasks:
  /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/tasks.md

Source указывает, откуда была разрешена схема: project (openspec/schemas/ в вашем проекте), user (глобальное переопределение) или package (встроенная в CLI). Приоритет: проект выше пользовательского, пользовательское выше пакетного.

{
  "proposal": {
    "path": "/usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/proposal.md",
    "source": "package"
  },
  "specs": {
    "path": "/usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/spec.md",
    "source": "package"
  },
  "design": {
    "path": "/usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/design.md",
    "source": "package"
  },
  "tasks": {
    "path": "/usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/tasks.md",
    "source": "package"
  }
}

Коды выхода

• 0: пути выведены.
• 1: неизвестная схема. В ошибке перечислены доступные схемы.

Схемы openspec

Выводит список доступных схем рабочих процессов.

openspec schemas          # names, descriptions, artifact order
openspec schemas --json   # machine-readable, for agent use

Опции

Флаг	Действие
--json	Вывод в формате JSON (для использования агентом).

Вывод

Available schemas:

  spec-driven
    Default OpenSpec workflow - proposal → specs → design → tasks
    Artifacts: proposal → specs → design → tasks

Схемы из вашего проекта помечаются как (project), а глобальные переопределения — как (user override).

[
  {
    "name": "spec-driven",
    "description": "Default OpenSpec workflow - proposal → specs → design → tasks",
    "artifacts": [
      "proposal",
      "specs",
      "design",
      "tasks"
    ],
    "source": "package"
  }
]

Коды выхода

• 0: схемы перечислены.
• 1: не удалось прочитать список схем.

openspec schema

Проверяет, форкает или создает схему (экспериментально). Каждая подкоманда сначала выводит в stderr Note: Schema commands are experimental and may change.

openspec schema which spec-driven          # откуда берется схема
openspec schema fork spec-driven my-flow   # копировать схему в проект
openspec schema init my-schema             # создать схему с нуля

Подкоманда	Что делает
which	Показывает, откуда берется схема.
validate	Проверяет структуру схемы и шаблоны.
fork	Копирует существующую схему в проект для настройки.
init	Создает новую локальную схему проекта.

Схемы определяются из трех местоположений. Побеждает первое совпадение:

Источник	Местоположение
project	openspec/schemas/ в текущем проекте.
user	~/.local/share/openspec/schemas/ (учитываются XDG_DATA_HOME и Windows %LOCALAPPDATA%).
package	Схемы, поставляемые с CLI. spec-driven находится здесь.

openspec schema which

Показывает, какую копию схемы будет использовать CLI.

openspec schema which spec-driven
openspec schema which --all        # все схемы, сгруппированные по источнику

Аргументы

Аргумент	Что это
name	Схема для поиска. Обязательно, если не задан --all. Если не указано ни то, ни другое, which завершается с кодом 1.

Параметры

Флаг	Эффект
--all	Перечислить все схемы с указанием источника их определения.
--json	Вывести результат определения как JSON.

Вывод

Schema: spec-driven
Source: package
Path: /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven

Когда копия с более высоким приоритетом скрывает другую, раздел Shadows: перечисляет скрытые копии. С --json:

{
  "name": "my-flow",
  "source": "project",
  "path": "/Users/you/projects/my-app/openspec/schemas/my-flow",
  "shadows": []
}

Неизвестное имя приводит к завершению с кодом 1 и выводит список доступных схем.

openspec schema validate

Проверяет структуру схемы и шаблоны.

openspec schema validate spec-driven   # одна схема из любого источника
openspec schema validate               # каждая локальная схема проекта

Она проверяет, что schema.yaml существует и корректно разбирается, что структура соответствует формату схемы, что файл шаблона каждого артефакта существует в каталоге templates/ схемы, а граф зависимостей не содержит циклов или неизвестных ссылок, в том числе в apply.requires. Значение apply.tracks, которое не совпадает точно со значением generates какого-либо артефакта, выводит строку warning:, но не приводит к сбою валидации, поскольку тогда OpenSpec не может определить, к прогрессу какого артефакта относится этот файл.

Параметры

Флаг	Эффект
--json	Вывести структурированный отчет вместо текста.
--verbose	Выводить каждый шаг валидации.

Вывод

✓ Schema 'spec-driven' is valid

Без имени каждая схема проекта получает одну строку под заголовком Validation Results:. Схема с ошибками перечисляет свои проблемы, и запуск завершается с кодом 1:

✗ Schema 'my-schema' has errors:
  error: Template file 'tasks.md' not found for artifact 'tasks'

openspec schema fork

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

openspec schema fork spec-driven my-flow

Аргументы

Аргумент	Что это
source	Схема для копирования из любого местоположения источника.
name	Имя для копии. В kebab-case (my-workflow). По умолчанию: <source>-custom.

Параметры

Флаг	Эффект
--force	Перезаписать существующую целевую схему.
--json	Вывести результат как JSON.

Вывод

✔ Forked 'spec-driven' to 'my-flow'

Source: /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven (package)
Destination: /Users/you/projects/my-app/openspec/schemas/my-flow

Форк попадает в openspec/schemas/, а поле name: в его schema.yaml перезаписывается новым именем:

openspec/schemas/my-flow/
├── schema.yaml
└── templates/
    ├── design.md
    ├── proposal.md
    ├── spec.md
    └── tasks.md

Существующая цель считается ошибкой, если не передан --force. Форк, сохраняющий имя источника, перекрывает оригинал.

openspec schema init

Создает новую локальную схему проекта с начальными шаблонами.

openspec schema init my-schema --description "Lightweight flow" --artifacts proposal,tasks

Если в интерактивном терминале не указаны --description и --artifacts, init запрашивает описание, контрольный список артефактов и то, сделать ли схему схемой проекта по умолчанию. Вне терминала он использует значения по умолчанию, приведенные ниже.

Аргументы

Аргумент	Что это
name	Имя новой схемы. В kebab-case (my-workflow).

Параметры

Флаг	Эффект
--description <text>	Описание схемы. По умолчанию: Custom workflow schema for <name>.
--artifacts <list>	ID артефактов через запятую из proposal, specs, design, tasks. По умолчанию: все четыре.
--default	Записывает schema: <name> в существующий openspec/config.yaml или openspec/config.yml. Создает openspec/config.yaml, если ни одного из них нет. Новые изменения используют эту схему.
--no-default	Пропустить запрос о схеме по умолчанию.
--force	Перезаписать существующую схему с тем же именем.
--json	Вывести результат как JSON.

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

Вывод

✔ Created schema 'my-schema'

Schema created at: /Users/you/projects/my-app/openspec/schemas/my-schema

Artifacts: proposal, tasks

Структура на диске:

openspec/schemas/my-schema/
├── schema.yaml
└── templates/
    ├── proposal.md
    └── tasks.md

schema.yaml связывает выбранные артефакты с их зависимостями. Если tasks включен, схема также получает фазу apply, которая отслеживает tasks.md. Используйте схему с openspec new --schema my-schema.

openspec store

Создает хранилища и управляет ими: автономными репозиториями OpenSpec, зарегистрированными на вашей машине.

openspec store setup team-context --path ~/openspec/team-context   # создать и зарегистрировать
openspec store register ~/stores/design-system                     # зарегистрировать существующую рабочую копию
openspec store list                                                # посмотреть, что зарегистрировано

Регистрации хранятся в локальном реестре для данной машины: ~/.local/share/openspec/stores/registry.yaml или $XDG_DATA_HOME/openspec/stores/registry.yaml, когда XDG_DATA_HOME задан. Каждая подкоманда принимает --json, чтобы выводить структурированный отчет вместо текста. Запуск openspec store с отсутствующей или неизвестной подкомандой завершается с кодом 1 и выводит список подкоманд.

Подкоманда	Что делает
setup [id]	Создать папку хранилища и зарегистрировать ее.
register [path]	Зарегистрировать существующую папку хранилища.
unregister <id>	Удалить регистрацию. Папка остается на диске.
remove <id>	Удалить регистрацию и папку.
list (псевдоним ls)	Показать список зарегистрированных хранилищ.
doctor [id]	Проверить регистрацию, метаданные и состояние Git для зарегистрированных хранилищ.

openspec store setup

Создает папку хранилища и регистрирует ее.

openspec store setup team-context --path ~/openspec/team-context

В интерактивном терминале setup запрашивает недостающие имя и расположение и просит подтверждение перед созданием чего-либо. Вне интерактивного терминала отсутствие имени или --path приводит к завершению с кодом 1 и сообщением о флаге, который нужно передать. Повторный запуск setup для зарегистрированного хранилища выводит Registry: already registered.

Setup завершается с кодом 1 и ошибкой store_setup_inside_git_repo, если --path находится внутри другого Git-репозитория, поскольку инициализация хранилища там привела бы к вложению одного репозитория в другой. --no-init-git не создает репозиторий и поэтому пропускает эту проверку. Используйте его, чтобы разместить хранилище в ~/openspec/<id>, когда ваш домашний каталог сам является Git-репозиторием, например репозиторием dotfiles.

Аргументы

Аргумент	Что это
id	Имя хранилища. Оно становится id, который вы передаете в --store.

Параметры

Флаг	Эффект
--path <path>	Папка, в которой должно находиться хранилище (~ раскрывается).
--init-git	Инициализировать Git-репозиторий с начальным коммитом. По умолчанию.
--no-init-git	Пропускать все действия Git: без init и без начального коммита.
--remote <url>	Канонический источник клонирования, записываемый в store.yaml.

Вывод

Store ready: team-context
Location: /Users/you/stores/team-context
OpenSpec root: ready
Registry: registered

Next: run normal OpenSpec commands against this store, for example:
  openspec new change <change-id> --store team-context
Share this store by committing and pushing it like any Git repo.

--json сообщает, что было создано и где это было зарегистрировано:

{
  "store": {
    "id": "design-system",
    "root": "/Users/you/stores/design-system",
    "metadata_path": "/Users/you/stores/design-system/.openspec-store/store.yaml"
  },
  "registry": {
    "path": "/Users/you/.local/share/openspec/stores/registry.yaml",
    "registered": true,
    "already_registered": false
  },
  "git": {
    "is_repository": true,
    "initialized": true,
    "committed": true
  },
  "created_files": [
    "openspec/",
    "openspec/specs/",
    "openspec/changes/",
    "openspec/changes/archive/",
    "openspec/config.yaml",
    "openspec/specs/.gitkeep",
    "openspec/changes/archive/.gitkeep",
    ".openspec-store/store.yaml"
  ],
  "status": []
}

openspec store register

Регистрирует существующую папку хранилища, например хранилище коллеги, которое вы клонировали.

openspec store register ~/stores/design-system

Папка должна содержать исправный корень openspec/. Если присутствует .openspec-store/store.yaml, register повторно использует записанный id. Без него register запрашивает подтверждение перед созданием этих метаданных. Вне интерактивного терминала вместо этого передайте --yes. На одной машине можно зарегистрировать одну рабочую копию на каждый id хранилища. Второй путь с тем же id или тот же путь со вторым id приводит к завершению с кодом 1.

Аргументы

Аргумент	Что это
path	Папка хранилища для регистрации (~ раскрывается). Обязательно.

Параметры

Флаг	Эффект
--id <id>	ID хранилища. По умолчанию берется из метаданных или имени папки.
--yes	Подтвердить создание метаданных идентификации хранилища для исправного корня OpenSpec.

Вывод

Store registered: design-system
Location: /Users/you/stores/design-system
OpenSpec root: ready
Registry: registered

--json выводит документ той же структуры, что и store setup --json.

openspec store unregister

Удаляет регистрацию. Папка остается на диске.

openspec store unregister design-system

Unregistered store: design-system
Files kept at: /Users/you/stores/design-system

openspec store remove

Удаляет регистрацию и папку.

openspec store remove design-system --yes

В интерактивном режиме remove запрашивает подтверждение перед удалением. При --json или вне интерактивного терминала для удаления требуется --yes:

Error: Pass --yes to delete store files non-interactively.
Fix: openspec store remove design-system --yes

Remove завершается с кодом 1 и ничего не удаляет, если в папке нет соответствующих метаданных хранилища или она содержит другое зарегистрированное хранилище (например, хранилище, добавленное как Git-подмодуль). В этом случае ошибка — store_remove_contains_registered_store: сначала выполните openspec store unregister <nested-id> или openspec store unregister <id>, чтобы удалить регистрацию хранилища без удаления файлов.

Параметры

Флаг	Эффект
--yes	Подтвердить удаление локальной папки хранилища.

Вывод

Removed store: design-system
Deleted: /Users/you/stores/design-system

openspec store list

Выводит список зарегистрированных хранилищ. ls — псевдоним.

openspec store list

OpenSpec stores (2)

ID              Location
design-system   /Users/you/stores/design-system
team-context    /Users/you/stores/team-context

Если ничего не зарегистрировано, list выводит No stores registered. и команды setup и register, которые нужно выполнить далее.

openspec store doctor

Проверяет регистрацию, метаданные и состояние Git для зарегистрированных хранилищ.

openspec store doctor                # все зарегистрированные хранилища
openspec store doctor team-context  # одно хранилище

Вывод

Store doctor

team-context
  Location: /Users/you/stores/team-context
  OpenSpec root: ok
  Metadata: ok
  Git: repository detected (commits: yes, uncommitted changes: no, remote: none)
  Issues: none

Коды выхода

• 0: отчет выведен, даже если хранилище сообщает о проблемах.
• 1: отчет не удалось выполнить (например, неизвестный id хранилища).

openspec doctor

Сообщает о состоянии связей для разрешённого корня OpenSpec.

openspec doctor                       # ближайший корень openspec/ выше вашей текущей рабочей директории
openspec doctor --store team-context  # зарегистрированное хранилище в качестве корня

Doctor доступен только для чтения: он никогда не клонирует, не синхронизирует и не восстанавливает. Он сообщает, здоров ли корень и разрешается ли каждая ссылка, объявленная в openspec/config.yaml, на этой машине. Если над вашей текущей рабочей директорией нет корня и не указан --store, он завершается с кодом 1 и перечисляет ваши зарегистрированные хранилища.

Параметры

Флаг	Действие
--store <id>	Использует зарегистрированное хранилище в качестве корня OpenSpec вместо текущего проекта.
--json	Выводит отчёт о состоянии в формате JSON.

Вывод

Doctor

Root
  Location: /Users/you/projects/my-app
  OpenSpec root: ok

References
  - team-context: ok (/Users/you/stores/team-context)

С --store корнем является хранилище, и отчёт добавляет строку хранилища:

Using OpenSpec root: team-context (/Users/you/stores/team-context)
Doctor

Root
  Location: /Users/you/stores/team-context
  OpenSpec root: ok
  Store: team-context (metadata ok)

References
  (none declared)

{
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest",
    "healthy": true,
    "status": []
  },
  "store": null,
  "references": [
    {
      "store_id": "team-context",
      "root": "/Users/you/stores/team-context",
      "status": []
    }
  ],
  "status": []
}

Коды завершения

• 0: отчёт выведен, в том числе когда в нём перечислены проблемы.
• 1: корень не разрешён (нет openspec/ выше вашей текущей рабочей директории и не указан --store), или неизвестный идентификатор --store.

openspec context

Выводит рабочий контекст для разрешённого корня OpenSpec: корень плюс каждое ссылочное хранилище, объявленное в openspec/config.yaml, каждое с командой получения.

openspec context                       # ближайший корень openspec/ выше вашей текущей рабочей директории
openspec context --store team-context  # зарегистрированное хранилище в качестве корня
openspec context --json                # краткая сводка для агента

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

Параметры

Флаг	Действие
--store <id>	Использует зарегистрированное хранилище в качестве корня OpenSpec вместо текущего проекта.
--json	Выводит краткую сводку для агента в формате JSON.
--code-workspace <path>	Также записывает файл рабочей области VS Code для набора.
--force	Перезаписывает существующий файл --code-workspace.

Вывод

Working context for my-app (/Users/you/projects/my-app)

OpenSpec root
  my-app  /Users/you/projects/my-app

Referenced stores
  team-context  /Users/you/stores/team-context
    Fetch: openspec show <spec-id> --type spec --store team-context

С --store хранилище является всем набором:

Using OpenSpec root: team-context (/Users/you/stores/team-context)
Working context for team-context (/Users/you/stores/team-context)

OpenSpec root
  team-context  /Users/you/stores/team-context

No references declared; the working set is this root alone.

{
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest",
    "role": "openspec_root"
  },
  "members": [
    {
      "role": "referenced_store",
      "id": "team-context",
      "path": "/Users/you/stores/team-context",
      "fetch": "openspec show <spec-id> --type spec --store team-context",
      "status": []
    }
  ],
  "status": []
}

Запись файла рабочей области

--code-workspace записывает файл рабочей области VS Code по указанному вами пути: одна папка для корня, одна папка ref:<id> для каждого доступного ссылочного хранилища. Недоступные ссылки пропускаются и перечисляются в строке сводки, Wrote /Users/you/projects/my-app/openspec.code-workspace (2 folders). Сводка выводится в stderr, поэтому stdout с --json остаётся одним JSON-документом. Существующий файл приводит к завершению с кодом 1, если не передан --force.

{
  "folders": [
    {
      "name": "my-app",
      "path": "/Users/you/projects/my-app"
    },
    {
      "name": "ref:team-context",
      "path": "/Users/you/stores/team-context"
    }
  ]
}

Коды завершения

• 0: отчёт выведен.
• 1: корень не разрешён (нет openspec/ выше вашей текущей рабочей директории и не указан --store), или запись --code-workspace была отклонена.

openspec workset

Создаёт, хранит и открывает личные рабочие представления. Рабочий набор — это сохранённый именованный список папок, с которыми вы работаете совместно.

openspec workset create checkout --member ~/projects/checkout-api --member web=~/projects/checkout-web
openspec workset list
openspec workset remove checkout --yes

Подкоманда	Что делает
create [name]	Создаёт и сохраняет именованное рабочее представление из выбранных вами папок.
list, ls	Показывает сохранённые рабочие наборы с их участниками.
open <name>	Открывает сохранённый рабочий набор в вашем инструменте (окно редактора или сеанс агента).
remove <name>	Удаляет сохранённый рабочий набор (папки-участники никогда не затрагиваются).

Рабочий набор полностью локален:

• Его состояние хранится в одной папке: ~/.local/share/openspec/worksets/ ($XDG_DATA_HOME/openspec/worksets/, если переменная задана; %LOCALAPPDATA%\openspec\worksets\ в Windows).
• В папки-участники ничего не записывается, и ничего не коммитится и не распространяется.
• Удаление этой одной папки удаляет все следы.

openspec workset create

Сохраняет именованное рабочее представление из папок.

openspec workset create checkout \
  --member ~/projects/checkout-api \
  --member web=~/projects/checkout-web

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

Аргументы

Аргумент	Что это
name	Имя рабочего набора. Kebab-case: строчные буквы, цифры, одиночные дефисы. Обязательно вне интерактивного терминала.

Параметры

Флаг	Действие
--member <member>	Папка-участник в виде <path> или <name>=<path>; можно указывать несколько раз. Первая является основной. Путь должен указывать на существующую папку, а метка по умолчанию совпадает с именем самой папки.
--tool <id>	Предпочтительный инструмент для открытия этого рабочего набора. Встроенные идентификаторы: code (VS Code), cursor (Cursor). claude и codex временно отключены.
--json	Выводит сохранённый рабочий набор в формате JSON.

Вывод

Saved workset 'checkout' (2 members) to your machine.
Open it any time with: openspec workset open checkout

openspec workset list

Показывает сохранённые рабочие наборы с их участниками, отсортированные по имени.

openspec workset list   # псевдоним: ls

Параметры

Флаг	Действие
--json	Выводит рабочие наборы в формате JSON.

Вывод

Один блок на каждый рабочий набор: имя, его инструмент, если он задан, затем по одной строке name path для каждого участника. Если ничего не сохранено, list выводит No worksets saved. Create one with: openspec workset create.

checkout
  checkout-api  /Users/you/projects/checkout-api
  web           /Users/you/projects/checkout-web
checkout-tool  (opens in VS Code)
  checkout-api  /Users/you/projects/checkout-api

С --json:

{
  "worksets": [
    {
      "name": "checkout",
      "members": [
        {
          "name": "checkout-api",
          "path": "/Users/you/projects/checkout-api"
        },
        {
          "name": "web",
          "path": "/Users/you/projects/checkout-web"
        }
      ]
    }
  ],
  "status": []
}

openspec workset open

Открывает сохранённый рабочий набор в вашем инструменте. Инструменты-редакторы (code, cursor) получают сгенерированный файл .code-workspace. Открывается окно, и команда возвращает управление. CLI-инструменты агентов (claude, codex) захватывали бы этот терминал с подключением всех участников. Они временно отключены, пока этот сценарий дорабатывается, поэтому сейчас рабочие наборы открываются в IDE.

openspec workset open checkout                # сохранённый инструмент или запрос
openspec workset open checkout --tool cursor  # этот инструмент только на этот раз

Аргументы

Аргумент	Что это
name	Рабочий набор, который нужно открыть.

Параметры

Флаг	Действие
--tool <id>	Открыть с этим инструментом только на этот раз.

Если не указан --tool и нет сохранённого инструмента, команда open предлагает выбрать установленный инструмент. Вне интерактивного терминала вместо этого она завершается с кодом 1.

• Папка-участник, которой больше не существует, пропускается с предупреждением. Если основная папка отсутствует, следующая существующая папка-участник становится основной для этого открытия. Если ни одной папки-участника не существует, открытие завершается ошибкой.
• --json отклоняется: команда open передаёт терминал инструменту и не имеет режима JSON.
• Если запуск не удался, ошибка заканчивается указанием ручного способа: путь к файлу рабочей области и список участников.

Коды выхода

• Повторяет поведение инструмента: команда завершается с собственным кодом выхода инструмента, а сигнал преобразуется в 128+n (130 после Ctrl-C).
• 1: неизвестный рабочий набор, нет доступной папки-участника или нет пригодного инструмента.

openspec workset remove

Удаляет сохранённый рабочий набор и сгенерированный файл .code-workspace. Папки-участники никогда не затрагиваются.

openspec workset remove checkout --yes

В интерактивном терминале remove показывает рабочий набор и просит подтвердить действие. С --json или вне терминала требуется --yes; без него команда завершается с кодом 1.

Параметры

Флаг	Действие
--yes	Подтверждает удаление без интерактивного взаимодействия.
--json	Выводит результат удаления в формате JSON.

Вывод

Removed workset 'checkout'. Member folders were not touched.

openspec version

Сообщает версию запущенного OpenSpec и способ установки этой копии.

openspec version                 # локальная версия и сведения об установке
openspec version --json          # структурированный локальный отчёт
openspec version --check         # также проверить реестр на наличие обновления
openspec version --check --json  # структурированный отчёт о локальной версии и обновлении

Без --check эта команда работает локально и не обращается к реестру. Она работает вне проекта OpenSpec. Существующий флаг openspec --version остаётся самой короткой формой и выводит только номер версии.

Параметры

Флаг	Действие
--json	Выводит один версионированный JSON-документ вместо текста.
--check	Проверяет настроенный реестр на наличие более новой версии.

Вывод

Для глобальной установки через npm:

OpenSpec 1.13.2 (npm, global)

Область установки — global, project, temporary для временной среды выполнения, такой как npx, source для локальной копии репозитория или standalone для автономной установки. OpenSpec опускает сведения, которые не может определить, вместо того чтобы угадывать.

--json сохраняет неизвестные сведения как явные значения null:

{
  "schemaVersion": 1,
  "version": "1.13.2",
  "install": {
    "location": "/opt/homebrew/lib/node_modules/@fission-ai/openspec",
    "packageManager": "npm",
    "scope": "global"
  }
}

С --check при наличии доступного обновления добавляются последняя версия и команда, если OpenSpec может определить безопасную команду для этой установки:

OpenSpec 1.13.2 (npm, global)
Update available: 1.14.0
  npm install -g @fission-ai/openspec@latest

{
  "schemaVersion": 1,
  "version": "1.13.2",
  "install": {
    "location": "/opt/homebrew/lib/node_modules/@fission-ai/openspec",
    "packageManager": "npm",
    "scope": "global"
  },
  "update": {
    "status": "available",
    "latest": "1.14.0",
    "command": "npm install -g @fission-ai/openspec@latest",
    "canSelfUpgrade": true
  }
}

Значения статуса обновления:

Статус	Значение
available	Реестр вернул безопасную версию новее запущенной.
current	Проверка завершилась и не обнаружила более новой версии.
disabled	Существующая настройка конфиденциальности или проверки обновлений заблокировала доступ к реестру. latest равен null.
offline	Реестр был недоступен или вернул непригодный ответ. latest равен null.

Для автономной установки команда обновления — openspec install.

DO_NOT_TRACK, отключение телеметрии, OPENSPEC_NO_UPDATE_CHECK, обнаружение CI и отклонённые переопределения реестра без HTTPS отключают проверку. Отключённые и офлайн-проверки всё равно завершаются с кодом 0, поскольку информация о доступности обновлений носит рекомендательный характер. Эта команда никогда не обновляет OpenSpec; canSelfUpgrade только сообщает, может ли существующий путь openspec update безопасно обновить эту копию.

Коды выхода

• 0: локальный отчёт выведен, в том числе при отключённых или офлайн-проверках обновлений.
• 1: синтаксис команды недопустим, например неподдерживаемый параметр --upgrade.

openspec install

Устанавливает автономную версию openspec. Запустите её из установки через npm или Homebrew, чтобы переключиться на неё, либо из автономной установки, чтобы обновить её на месте.

openspec install          # новейший релиз
openspec install 1.15.0   # конкретный релиз

Команда запускает скрипт установки, который выбирает новейший релиз, у которого прикреплены все файлы, и файл для вашей машины, а затем сверяет его с SHA256SUMS этого релиза:

• Из установки через пакетный менеджер: устанавливает в ~/.local/bin (Windows: %LOCALAPPDATA%\Programs\openspec) и выводит команду удаления старой копии, например npm uninstall -g @fission-ai/openspec. Сама команда эту копию никогда не удаляет.
• Из автономной установки: заменяет запущенный файл на месте, под его же именем.

После этого сообщается, какая копия openspec теперь запускается: копия из пакетного менеджера, стоящая раньше в PATH, продолжает использоваться, пока вы её не удалите.

Аргументы

Аргумент	Описание
version	Релиз для установки, например 1.15.0. Необязательный; по умолчанию используется последняя версия.

OPENSPEC_INSTALL_DIR и OPENSPEC_INSTALL_NAME позволяют задать другую папку или имя файла.

Коды выхода

• 0: установка выполнена.
• 1: указанная версия не является версией релиза либо загрузка или установка завершились неудачей. Текущая копия остаётся без изменений.

openspec feedback

Отправляет отзыв о OpenSpec.

openspec feedback "Validate output is hard to scan"
openspec feedback "Archive fails on Windows" --body "Steps: init, propose, archive. Error: EPERM."

CLI оформляет ваше сообщение как GitHub issue в репозитории Fission-AI/OpenSpec через ваш gh CLI. Заголовком становится Feedback: <message>. Тело использует заголовки из формы отчёта об ошибке: ваше сообщение в разделе What happened, текст --body в разделе Details, а также раздел Minimal steps to reproduce с просьбой добавить шаги, поскольку CLI не может заполнить их самостоятельно. В конце добавляются версия CLI, платформа и метка времени. К issue добавляется метка feedback. Если в репозитории не определена такая метка, CLI повторяет попытку без неё и сообщает об этом.

Аргументы

Аргумент	Описание
message	Краткое резюме в одну строку. Становится заголовком issue. Обязательный.

Опции

Флаг	Действие
--body <text>	Более подробное описание, добавляемое в тело issue.

Вывод

При успехе:

✓ Feedback submitted successfully!
Issue URL: https://github.com/Fission-AI/OpenSpec/issues/1234

Если gh не установлен или в gh не выполнен вход, ничего не отправляется. CLI выводит ваш отформатированный отзыв между маркерами --- FORMATTED FEEDBACK ---, а затем ссылку, открывающую форму отчёта об ошибке с уже заполненными заголовком, описанием проблемы (ваше сообщение и текст --body), версией CLI и окружением (платформа и версия Node). Остальную часть формы вы заполняете в браузере. В варианте без выполненного входа добавляется To auto-submit in the future: gh auth login.

Коды выхода

• 0: issue создан либо выполнен резервный сценарий ручной отправки (нет gh или в gh не выполнен вход).
• 1: сообщение не передано.
• Собственный код gh: gh завершился с ошибкой после аутентификации (сеть, лимит запросов, issues отключены). Сначала CLI повторно выводит ваш отзыв и URL для ручной отправки.

openspec completion

Устанавливает или генерирует автодополнения для оболочки.

openspec completion install        # определяет вашу оболочку, устанавливает, подключает конфигурацию
openspec completion generate zsh   # выводит скрипт в stdout

Поддерживаемые оболочки: zsh, bash, fish, powershell. Каждая подкоманда принимает необязательный аргумент — оболочку. Если его опустить, CLI определит вашу оболочку по окружению.

Подкоманда	Описание
generate [shell]	Выводит скрипт автодополнения в stdout.
install [shell]	Записывает скрипт и настраивает стартовый файл вашей оболочки.
uninstall [shell]	Удаляет скрипт и блок конфигурации.

При установке через Nix автодополнения уже настроены: пакет flake поставляет скрипты для Bash, Fish и Zsh в стандартных расположениях, поэтому install не требуется (Установка).

openspec completion generate

Выводит скрипт и ничего не записывает.

#compdef openspec

# Zsh completion script for OpenSpec CLI
# Auto-generated - do not edit manually

_openspec() {
  local context state line
  typeset -A opt_args
...

openspec completion install

Записывает скрипт и правит конфигурацию вашей оболочки. Изменения в конфигурации располагаются между маркерами # OPENSPEC:START и # OPENSPEC:END. Существующий скрипт сначала сохраняется в резервную копию (.backup-<timestamp>).

Оболочка	Расположение скрипта	Изменяемая конфигурация
zsh	~/.zsh/completions/_openspec	$ZDOTDIR/.zshrc, если ZDOTDIR — абсолютный путь, иначе ~/.zshrc
bash	~/.local/share/bash-completion/completions/openspec	~/.bashrc
fish	~/.config/fish/completions/openspec.fish	Отсутствует: fish загружает его автоматически.
powershell	OpenSpecCompletion.ps1 рядом с вашим профилем	$PROFILE

Если установлен Oh My Zsh, скрипт вместо этого размещается в $ZSH_CUSTOM/completions/_openspec (по умолчанию ~/.oh-my-zsh/custom/completions/_openspec).

Относительное значение ZDOTDIR или путь, начинающийся с ~, игнорируется — вместо этого изменяется ~/.zshrc. Повторный запуск install, даже если скрипт уже актуален, всё равно добавляет блок в тот .zshrc, который читает zsh.

Опции

Флаг	Действие
--verbose	Дополнительно выводит установленный путь, путь к резервной копии (если создавалась) и какой файл конфигурации был изменён.

Вывод

✓ Completion script installed and .zshrc configured successfully

Restart your shell or run: exec zsh

openspec completion uninstall

Удаляет скрипт и помеченный блок конфигурации. Перед изменением вашей конфигурации запрашивает подтверждение (по умолчанию: Нет).

Для zsh очищает тот .zshrc, который изменяет install, а также ~/.zshrc, если более старая установка при использовании ZDOTDIR оставила там блок. Если блок не удаётся удалить, uninstall сообщает имя файла и завершается с кодом 1.

Опции

Флаг	Действие
-y, --yes	Пропускает запросы подтверждения.

Вывод

✓ Completion script removed from /Users/you/.zsh/completions/_openspec. Removed OpenSpec configuration from ~/.zshrc

Коды выхода

• 0: скрипт сгенерирован, установлен или удалён. Отменённый uninstall также завершается с кодом 0.
• 1: оболочка не поддерживается или не определена, либо один из шагов установки или удаления завершился ошибкой.

openspec change

Устаревшая форма на основе существительных для show, list и validate. При каждом запуске выводится предупреждение с указанием на команды, начинающиеся с глагола, после чего команда всё равно выполняется:

Warning: The "openspec change ..." commands are deprecated. Prefer verb-first commands (e.g., "openspec list", "openspec validate --changes").
Warning: "openspec change list" is deprecated. Use "openspec list".
add-rate-limit

Устаревшая команда	Используйте вместо неё
openspec change show <name>	openspec show <name>
openspec change list	openspec list
openspec change validate <name>	openspec validate <name> (все изменения: openspec validate --changes)

Флаги описаны в разделах, посвящённых командам, начинающимся с глагола.

openspec spec

Устаревшая форма на основе существительных для show, list и validate. При каждом запуске выводится предупреждение с указанием на команды, начинающиеся с глагола, после чего команда всё равно выполняется:

Warning: The "openspec spec ..." commands are deprecated. Prefer verb-first commands (e.g., "openspec show", "openspec validate --specs").
api

Устаревшая команда	Используйте вместо неё
openspec spec show <id>	openspec show <id>
openspec spec list	openspec list --specs
openspec spec validate <id>	openspec validate <id> (все спецификации: openspec validate --specs)

Флаги описаны в разделах, посвящённых командам, начинающимся с глагола.