Skip to content

Справочник по CLI ​

CLI OpenSpec (openspec) предоставляет терминальные команды для настройки проекта, проверки, просмотра статуса и управления. Эти команды дополняют AI-команды с косой чертой (например, /opsx:propose), описанные в разделе Commands.

Сводка ​

КатегорияКомандыНазначение
Настройкаinit, updateИнициализация и обновление OpenSpec в вашем проекте
Хранилища (автономные репозитории OpenSpec)store setup, store register, store unregister, store remove, store list, store doctorУправление хранилищами — зарегистрированными вами автономными репозиториями OpenSpec
ДиагностикаdoctorОтчёт о состоянии связей для разрешённого корня
Рабочий контекстcontextФормирование рабочего набора (корень + связанные хранилища)
Личные рабочие наборыworkset create, workset list, workset open, workset removeСоздание и открытие личных локальных рабочих представлений в вашем инструменте
Просмотрlist, view, showПросмотр изменений и спецификаций
ПроверкаvalidateПроверка изменений и спецификаций на наличие проблем
Жизненный циклarchiveЗавершение выполненных изменений
Рабочий процессnew change, status, instructions, templates, schemasПоддержка рабочего процесса на основе артефактов
Схемыschema init, schema fork, schema validate, schema whichСоздание и управление пользовательскими рабочими процессами
КонфигурацияconfigПросмотр и изменение настроек
Утилитыfeedback, completionОбратная связь и интеграция с оболочкой

Команды для человека и для агента ​

Большинство CLI-команд предназначены для использования человеком в терминале. Некоторые команды также поддерживают использование агентами/скриптами через JSON-вывод.

Команды только для человека ​

Эти команды интерактивные и предназначены для использования в терминале:

КомандаНазначение
openspec initИнициализация проекта (интерактивные подсказки)
openspec viewИнтерактивная панель управления
openspec workset open <name>Открыть сохранённый набор работ (окно редактора или сессия терминального агента)
openspec config editОткрыть конфигурацию в редакторе
openspec feedbackОтправить обратную связь через GitHub
openspec completion installУстановить автодополнение оболочки

Команды, совместимые с агентами ​

Эти команды поддерживают вывод --json для программного использования ИИ-агентами и скриптами:

КомандаИспользование человекомИспользование агентом
openspec listПросмотр изменений/спецификаций--json для структурированных данных
openspec show <item>Чтение содержимого--json для разбора
openspec validateПроверка проблем--all --json для пакетной валидации
openspec statusПросмотр прогресса артефактов--json для структурированного статуса
openspec instructionsПолучение следующих шагов--json для инструкций агента
openspec templatesПоиск путей шаблонов--json для разрешения путей
openspec schemasСписок доступных схем--json для обнаружения схем; --store <id> для выбора зарегистрированного корня
openspec store setup <id>Создание и регистрация локального хранилища--json с явными входными данными для структурированного вывода установки
openspec store register <path>Регистрация существующего хранилища--json для структурированного вывода регистрации
openspec store unregister <id>Удаление регистрации локального хранилища--json для структурированного вывода очистки
openspec store remove <id>Удаление зарегистрированной папки локального хранилища--yes --json для неинтерактивного удаления
openspec store listПросмотр зарегистрированных хранилищ--json для структурированных регистраций
openspec store doctorПроверка настройки локального хранилища--json для структурированной диагностики
openspec new change <id>Создание каркаса локального изменения в репозитории--json, а также --store <id> для использования зарегистрированного хранилища как корня OpenSpec
openspec workset create [name]Составление персонального рабочего представления--member <path> --json для неинтерактивного составления
openspec workset listПросмотр сохранённых наборов работ--json для структурированных представлений
openspec workset remove <name>Удаление сохранённого представления--yes --json для неинтерактивного удаления

Глобальные параметры ​

Эти параметры работают со всеми командами:

ПараметрОписание
--version, -VПоказать номер версии
--no-colorОтключить цветной вывод
--help, -hПоказать справку по команде

Команды настройки ​

openspec init ​

Инициализация OpenSpec в вашем проекте. Создаёт структуру папок и настраивает интеграции с ИИ-инструментами.

Поведение по умолчанию использует значения глобальной конфигурации по умолчанию: профиль core, доставка both, рабочие процессы propose, explore, apply, update, sync, archive.

openspec init [path] [options]

Используйте --language <language>, чтобы добавить языковую инструкцию в openspec/config.yaml нового проекта. Для существующего проекта отредактируйте поле context конфигурации, чтобы OpenSpec никогда не перезаписывал проектные указания.

Аргументы:

АргументОбязательныйОписание
pathНетЦелевая директория (по умолчанию: текущая директория)

Параметры:

ПараметрОписание
--tools <list>Настройка ИИ-инструментов в неинтерактивном режиме. Используйте all, none или разделённый запятыми список
--language <language>Создавать артефакты на этом языке при создании новой конфигурации
--forceАвтоматическая очистка устаревших файлов без запроса
--profile <profile>Переопределить глобальный профиль для этой инициализации (core или custom)
--no-animationПоказать статичный экран приветствия вместо анимированного
--copilot-cloudНастроить файлы облачного coding-agent GitHub Copilot cloud coding-agent files без запроса
--no-copilot-cloudПропустить файлы облачного coding-agent GitHub Copilot без запроса

--profile custom использует те рабочие процессы, которые в данный момент выбраны в глобальной конфигурации (openspec config profile).

Анимация приветствия также пропускается, когда установлена переменная окружения OPENSPEC_NO_ANIMATION (любое значение, включая пустое), когда NO_COLOR установлен в непустое значение или когда включено системное предпочтение уменьшенного движения (Reduce Motion в macOS, отключённые анимации GNOME).

Поддерживаемые ID инструментов (--tools) — windsurf также принимается как псевдоним для devin: amazon-q, antigravity, auggie, bob, claude, cline, command-code, codeartsagent, codex, devin, forgecode, codebuddy, continue, costrict, crush, cursor, factory, gemini, github-copilot, hermes, iflow, junie, kilocode, kimi, kiro, lingma, minimax-code, vibe, oh-my-pi, opencode, pi, codeassistant, qoder, qwen, rovodev, roocode, trae, zed, zcode, agents

Этот список отражает AI_TOOLS в src/core/config.ts. См. Поддерживаемые инструменты для путей навыков и команд каждого инструмента.

Примеры:

bash
# Интерактивная инициализация
openspec init

# Инициализация в конкретной директории
openspec init ./my-project

# Неинтерактивно: настройка для Claude и Cursor
openspec init --tools claude,cursor

# Неинтерактивно: настройка глобальных навыков MiniMax Code
openspec init --tools minimax-code

# Настройка для всех поддерживаемых инструментов
openspec init --tools all

# Переопределение профиля для этого запуска
openspec init --profile core

# Пропуск запросов и автоматическая очистка устаревших файлов
openspec init --force

Что создаётся:

openspec/
├── specs/              # Ваши спецификации (источник истины)
├── changes/            # Предложенные изменения
└── config.yaml         # Конфигурация проекта

.claude/skills/         # Навыки Claude Code (если выбран claude)
.cursor/skills/         # Навыки Cursor (если выбран cursor)
.cursor/commands/       # Команды OPSX для Cursor (если доставка включает команды)
.agents/skills/         # Общие навыки для инструментов, совместимых с AGENTS.md (если выбран agents)
... (конфигурации других инструментов)

openspec update ​

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

openspec update [path] [options]

Аргументы:

АргументОбязательныйОписание
pathНетЦелевая директория (по умолчанию: текущая директория)

Параметры:

ПараметрОписание
--forceПринудительное обновление, даже если файлы актуальны

Пример:

bash
# Обновление файлов инструкций после обновления npm
npm install -g @fission-ai/openspec@latest
openspec update

Сначала обновите пакет. Файлы инструкций генерируются установленным CLI, поэтому запуск openspec update против устаревшей установки сообщает, что всё актуально, не добавляя рабочие процессы из новых релизов.

Чтобы сделать это видимым, openspec update спрашивает реестр npm, была ли опубликована более новая версия CLI. Если ваша версия отстаёт, он предлагает обновиться:

text
A newer OpenSpec CLI is available (v1.6.0 → v1.7.0).
  Running from: /usr/local/lib/node_modules/@fission-ai/openspec
? Upgrade to v1.7.0 now? (Y/n)

Ответьте «да», и он выполнит npm install -g @fission-ai/openspec@latest, затем повторно запустит обновление с новым CLI, чтобы новые рабочие процессы были добавлены в рамках той же команды. Он подтверждает обновление, запрашивая версию у установленного бинарного файла, а не доверяя коду выхода npm, поэтому если другая установка ранее в вашем PATH всё ещё отвечает, он сообщит об этом вместо того, чтобы заявить об успехе. Ответьте «нет», и он выведет команду и обновит с помощью имеющегося у вас CLI. Ctrl-C останавливает команду.

Предложение появляется только в интерактивном терминале и только когда npm владеет установкой — единственный случай, когда npm install -g действительно исправляет ситуацию. Во всех остальных случаях вы получаете команду, соответствующую способу установки:

Способ установки OpenSpecЧто вы получите
Глобальная установка через npmЗапрос и выполнение обновления за вас — в интерактивном терминале; при перенаправлении вывода вы получите напечатанную команду
Глобальная установка через pnpm, bun, yarn или voltaСобственная команда этого менеджера: pnpm add -g …@latest, bun add -g …@latest, yarn global add …@latest или volta install …@latest
Зависимость проектаПримечание об обновлении зависимости, поскольку её lockfile принадлежит менеджеру пакетов проекта
Кэш npx / dlxnpx @fission-ai/openspec@latest update — эта команда и есть обновление, поэтому второго шага нет
Гит-клонированиеНичего — ваша версия определяется веткой

Когда что-либо выводится, указывается директория, из которой был загружен работающий CLI — именно то, что нужно проверить, если вы действительно обновились, но устаревший shim всё ещё владеет вашим PATH.

Он обращается к реестру в npm_config_registry, когда npm его экспортирует, и к https://registry.npmjs.org в противном случае. Файл .npmrc не читается: допускать, чтобы содержимое файла определяло, куда отправляется исходящий запрос, — это процесс, которого стоит избегать, и .npmrc проекта перемещается вместе с репозиторием. На частном зеркале экспортируйте npm_config_registry — или установите OPENSPEC_NO_UPDATE_CHECK, чтобы полностью пропустить проверку. Проверка пропускается, когда CI установлен в любое значение, кроме явного отключающего (false, 0, no, off или пустое), при NODE_ENV=test, а также когда установлено OPENSPEC_NO_UPDATE_CHECK (любое значение), DO_NOT_TRACK=1 или OPENSPEC_TELEMETRY=0. Она выполняется перед обновлением и может задержать его не более чем на 1,5 секунды — после этого она сдаётся, даже если сеть молча теряет пакеты, и молчит, когда реестр недоступен.

Как определяется «актуально»: файлы навыков записывают версию, которая их сгенерировала, поэтому OpenSpec сравнивает её с установленным CLI. Файлы команд не несут метки версии, поэтому для инструмента, у которого есть команды, но нет навыков (доставка commands), OpenSpec сравнивает содержимое файлов с тем, что он сгенерирует сейчас — правки этих файлов считаются дрейфом и перезаписываются. При доставке skills или both проверяется только записанная версия, поэтому вручную отредактированный файл, чья версия всё ещё совпадает, не трогается; используйте --force, чтобы переписать его. В любом случае сгенерированные файлы принадлежат OpenSpec — храните собственные инструкции в другом месте.


Хранилища (отдельные репозитории OpenSpec) ​

Бета-версия. Хранилища и функции, построенные на их основе (ссылки, рабочий контекст, рабочие наборы), являются новыми; имена команд, флаги, форматы файлов и вывод JSON могут изменяться между релизами. Пошаговое руководство, ориентированное на решение проблем, см. в руководстве по хранилищам.

Хранилище — это отдельный репозиторий OpenSpec, который вы зарегистрировали на этой машине — например, репозиторий планирования или репозиторий контрактов. Регистрация хранилища позволяет обычным командам (list, show, status, validate, new change, archive и т. д.) работать с ним из любого места путем передачи флага --store <id>.

openspec store setup ​

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

bash
openspec store setup [id] [options]

Опции:

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

Неинтерактивные запуски (--json, скрипты, агенты) должны передавать как идентификатор хранилища, так и --path. В интерактивном терминале настройка запрашивает местоположение с редактируемым предложением в видимом месте, принадлежащем пользователю (например, ~/openspec/<id>); она никогда не использует каталог управляемых данных OpenSpec по умолчанию.

Примеры:

bash
openspec store setup
openspec store setup team-context
openspec store setup team-context --path ~/openspec/team-context --no-init-git
openspec store setup team-context --path ~/openspec/team-context --no-init-git --json

openspec store register ​

Регистрация существующей папки локального хранилища. Во время бета-тестирования хранилищ корень может быть зарегистрирован до того, как будут созданы какие-либо изменения, применены спецификации или архивированы изменения; в этом случае openspec/changes/, openspec/specs/ и openspec/changes/archive/ могут отсутствовать, пока обычные команды не создадут их. Репозиторий, содержащий только конфигурацию и объявляющий store: <id>, остается указателем на другое хранилище и не регистрируется как корень хранилища, если этот указатель не будет удален.

bash
openspec store register [path] [options]

Опции:

ОпцияОписание
--id <id>Идентификатор хранилища; по умолчанию используется метаданные хранилища или имя папки
--yesПодтвердить создание метаданных идентичности хранилища для корректного корня OpenSpec
--jsonВывод в формате JSON

openspec store unregister ​

Забыть регистрацию локального хранилища без удаления файлов.

bash
openspec store unregister <id> [--json]

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

openspec store remove ​

Удалить регистрацию локального хранилища и удалить его локальную папку.

bash
openspec store remove <id> [--yes] [--json]

Команда remove показывает точную папку перед удалением в интерактивном терминале. Агенты, скрипты и вызовы через JSON должны передать --yes для подтверждения удаления. OpenSpec отказывается удалять папку, которая не содержит соответствующих метаданных хранилища.

openspec store list ​

Список локально зарегистрированных хранилищ.

bash
openspec store list [--json]
openspec store ls [--json]

openspec store doctor ​

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

bash
openspec store doctor [id] [--json]

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

Ссылки на хранилища из проекта ​

Репозиторий проекта может объявить, какие хранилища используются в его работе, в файле openspec/config.yaml:

yaml
schema: spec-driven
references:
  - team-context

Начиная с этого момента, вывод openspec instructions в этом репозитории (как для отдельных артефактов, так и для поверхности apply, в режимах JSON и человека) содержит индекс спецификаций каждого ссылочного хранилища — идентификаторы спецификаций, однострочное резюме из раздела Purpose каждой спецификации и команду для получения (openspec show <spec-id> --type spec --store <id>). Индекс формируется в реальном времени на основе зарегистрированной копии при каждом запуске; содержимое спецификаций никогда не копируется в вывод.

Ссылки являются контекстом только для чтения. Они никогда не меняют область действия команд: работа остается в собственном корне репозитория, а запись в ссылочное хранилище остается явным действием с флагом --store. Ссылка, которую невозможно разрешить (например, хранилище не зарегистрировано на этой машине), преобразуется в предупреждение в индексе с точным исправлением, и инструкции все равно генерируются. openspec doctor сообщает о здоровье ссылок в одном месте.

Запись источника клонирования хранилища ​

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

bash
openspec store setup team-context --path ~/openspec/team-context \
  --remote git@github.com:acme/team-context.git

Удаленный адрес попадает в .openspec-store/store.yaml внутри первого коммита, поэтому каждая копия сразу знает об этом. Для существующего хранилища отредактируйте store.yaml вручную и выполните коммит. store doctor показывает записанный удаленный адрес (и наблюдаемый Git-источник копии); рекомендации по настройке/регистрации называют его; а регистрация записывает источник копии в локальный реестр машины.

Объявление ссылки также может содержать источник клонирования, поэтому коллеге, у которого еще нет хранилища, будет предоставлено полное, готовое к копированию исправление (git clone <remote> <path> && openspec store register <path> --id <id>):

yaml
references:
  - { id: team-context, remote: "git@github.com:acme/team-context.git" }

Запись удаленного адреса не означает синхронизации: OpenSpec никогда не выполняет клонирование, вытягивание или отправку самостоятельно.

Объявление хранилища по умолчанию ​

Репозиторий, чье планирование полностью вынесено вовне — без локальных openspec/specs/ или openspec/changes/ — может объявить свое хранилище один раз вместо передачи --store в каждой команде:

yaml
# openspec/config.yaml (единственный файл под openspec/)
store: team-context

Обычные команды затем автоматически разрешаются к объявленному хранилищу; баннер корня и блок JSON root сообщают source: "declared" с идентификатором хранилища, а печатные подсказки все еще содержат --store <id>. Объявление является резервным вариантом, а не переопределением: явный --store всегда имеет приоритет, а директория с реальными папками планирования игнорирует указатель (с предупреждением). Чтобы преобразовать репозиторий-указатель в локальный корень OpenSpec, удалите строку store: и выполните openspec init — init откажется создавать структуру, пока объявление присутствует.

Вариант на уровне машины охватывает все репозитории сразу: openspec config set defaultStore <id> (см. Конфигурация). Он проверяется только после того, как --store, локальный корень и указатель проекта не удалось разрешить; тогда баннер корня и блок JSON root сообщают source: "global_default".

Doctor (здоровье связей) ​

Один вопрос только для чтения, в одном месте: исправен ли корневой каталог OpenSpec, и доступны ли хранилища, на которые он ссылается, на этой машине?

bash
openspec doctor [--store <id>] [--json]

Отчёт разделяет здоровье корня, здоровье метаданных хранилищ (включая примечание, когда записанный удалённый репозиторий расходится с origin рабочей копии, и примечание, когда рабочая копия хранилища отстала от последнего полученного отслеживаемого ref вышестоящего репозитория), и здоровье ссылок (те же диагностические инструкции, которые показывает instructions, с исправлениями клонирования для неразрешённых ссылок). Находки о здоровье любой серьёзности завершаются кодом 0 — агенты читают массивы status; только сбои команд (нет корня, неизвестное хранилище) завершаются кодом 1. Doctor никогда не клонирует, не синхронизирует и не исправляет. Чтобы получить сам собранный набор, а не его здоровье, используйте openspec context.

Рабочий контекст (собранный набор) ​

Всё, к чему эта работа относится через объявления OpenSpec, в одном рабочем наборе: корень OpenSpec и хранилища, на которые он ссылается.

bash
openspec context [--store <id>] [--json] [--code-workspace <path> [--force]]

Краткое JSON-описание предназначено для агентов (каждое доступное ссылочное хранилище несёт свой рецепт получения; неразрешённые элементы несут те же инструкции по исправлению, что и doctor show). --code-workspace дополнительно записывает файл рабочей области VS Code, содержащий корень плюс доступные ссылочные хранилища (папки ref:<id>) — это единственная запись, которую выполняет данная команда, и она отказывается работать без --force, если файл уже существует. Недоступные элементы фиксируются в отчёте, но никогда не угадываются.

«Рабочий контекст» — это собранный набор; поле context: в openspec/config.yaml — это фон проекта, внедряемый в инструкции, — две разные вещи. openspec doctor отвечает на вопрос, исправен ли набор; openspec context отвечает на вопрос, что собой представляет набор.

Персональные рабочие наборы ​

Бета. Рабочие наборы — часть новой бета-поверхности; команды, флаги и форматы файлов могут меняться между выпусками. Для пошагового руководства см. руководство по хранилищам.

Рабочий набор — это персональное именованное представление папок, с которыми вы работаете вместе, — корень планирования плюс всё остальное, что вы выберете, — хранится на вашей машине и открывается по имени в вашем инструменте. Он чисто локальный: никогда не коммитится, не публикуется, не выводится из объявлений, и его удаление никогда не затрагивает папки-элементы.

bash
openspec workset create [name] [--member <path> | --member <name>=<path>]... [--tool <id>] [--json]
openspec workset list [--json]
openspec workset open <name> [--tool <id>]
openspec workset remove <name> [--yes] [--json]

create запускает короткий интерактивный процесс (или принимает флаги --member без интерактива; первый элемент является основным — сеансы начинаются с него). open запускает выбранный инструмент: редакторы (VS Code, Cursor) открывают окно со всеми элементами и завершаются; CLI-агенты (Claude Code, codex) захватывают этот терминал как сеанс со всеми присоединёнными элементами и без предзаполненного запроса, завершающийся при вашем выходе. Папка-элемент, отсутствующая на момент открытия, пропускается с примечанием; остальное открывается. Сохранённая настройка инструмента переопределяется для каждого открытия с помощью --tool.

Поддержка нового инструмента — это конфигурация, а не код. Каждый инструмент относится к одному из двух стилей запуска — workspace-file (запускается с сгенерированным .code-workspace) или attach-dirs (один флаг присоединения на элемент) — и ключ openers в глобальном config.json (откройте его с помощью openspec config edit) добавляет инструменты или настраивает встроенные по полям:

json
{
  "openers": {
    "zed": { "style": "workspace-file" },
    "claude": { "attach_flag": "--dir" }
  }
}

Всё состояние рабочих наборов хранится в папке worksets/ в глобальном каталоге данных (сохранённые представления плюс сгенерированные файлы <name>.code-workspace, регенерируемые при каждом открытии); удаление этой папки устраняет все следы.


Команды просмотра ​

openspec list ​

Список изменений или спецификаций в вашем проекте.

openspec list [options]

Опции:

ОпцияОписание
--specsСписок спецификаций вместо изменений
--changesСписок изменений (по умолчанию)
--sort <order>Сортировка по recent (по умолчанию) или name
--jsonВывод в формате JSON

Примеры:

bash
# Список всех активных изменений
openspec list

# Список всех спецификаций
openspec list --specs

# JSON-вывод для скриптов
openspec list --json

Вывод (текст):

Изменения:
  add-dark-mode     Нет задач      только что

openspec view ​

Отображение интерактивной панели для изучения спецификаций и изменений.

openspec view

Открывает терминальный интерфейс для навигации по спецификациям и изменениям вашего проекта.


openspec show ​

Отображение сведений об изменении или спецификации.

openspec show [item-name] [options]

Аргументы:

АргументОбязательныйОписание
item-nameНетИмя изменения или спецификации (запрашивается, если опущено)

Опции:

ОпцияОписание
--type <type>Указание типа: change или spec (определяется автоматически, если нет неоднозначности)
--jsonВывод в формате JSON
--no-interactiveОтключение запросов

Опции для изменений:

ОпцияОписание
--deltas-onlyПоказывать только дельта-спецификации (режим JSON)

Опции для спецификаций:

ОпцияОписание
--requirementsПоказывать только требования, исключая сценарии (режим JSON)
--no-scenariosИсключить содержимое сценариев (режим JSON)
-r, --requirement <id>Показать конкретное требование по индексу с 1 (режим JSON)

Примеры:

bash
# Интерактивный выбор
openspec show

# Показать конкретное изменение
openspec show add-dark-mode

# Показать конкретную спецификацию
openspec show auth --type spec

# JSON-вывод для разбора
openspec show add-dark-mode --json

Команды валидации ​

openspec validate ​

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

openspec validate [item-name] [options]

Изменение с нулевым количеством дельта-спецификаций не проходит валидацию, если в его .openspec.yaml не указано skip_specs: true (для чисто рефакторинговых, инструментальных или документационных задач — см. Рецепт 5).

Аргументы:

АргументОбязательныйОписание
item-nameНетКонкретный элемент для проверки (если не указан, будет предложен выбор)

Опции:

ОпцияОписание
--allПроверить все изменения и спецификации
--changesПроверить все изменения
--specsПроверить все спецификации
--archivedПроверить, что у всех архивных изменений выполнены все задачи (для проверки в pre-commit)
--type <type>Указать тип при неоднозначности имени: change или spec
--strictВключить строгий режим валидации
--jsonВывести результат в формате JSON
--concurrency <n>Максимальное количество параллельных проверок (по умолчанию: 6, либо значение переменной OPENSPEC_CONCURRENCY)
--no-interactiveОтключить интерактивные запросы

--archived имеет свою область применения: он не проверяет дельта-спецификации (они уже применены при архивации), а убеждается, что каждое изменение в changes/archive/ имеет все отмеченные чекбоксы в tasks.md и завершается с ненулевым кодом, если хоть один не отмечен. Это отлавливает изменения, которые были заархивированы с незавершённой работой — удобно для pre-commit хука.

Примеры:

bash
# Интерактивная валидация
openspec validate

# Проверить конкретное изменение
openspec validate add-dark-mode

# Проверить все изменения
openspec validate --changes

# Проверить всё с выводом в JSON (для CI/скриптов)
openspec validate --all --json

# Строгая валидация с увеличенной параллельностью
openspec validate --all --strict --concurrency 12

# Завершиться с ошибкой, если в любом архивном изменении есть неотмеченные задачи
openspec validate --archived

Вывод (текстовый):

Validating add-dark-mode...
  ✓ proposal.md valid
  ✓ specs/ui/spec.md valid
  ⚠ design.md: missing "Technical Approach" section

1 warning found

Вывод (JSON):

json
{
  "version": "1.0.0",
  "results": {
    "changes": [
      {
        "name": "add-dark-mode",
        "valid": true,
        "warnings": ["design.md: missing 'Technical Approach' section"]
      }
    ]
  },
  "summary": {
    "total": 1,
    "valid": 1,
    "invalid": 0
  }
}

Команды жизненного цикла ​

openspec archive ​

Архивировать завершённое изменение и слить дельта-спецификации в основные спецификации.

openspec archive [change-name] [options]

Аргументы:

АргументОбязательныйОписание
change-nameНетИзменение для архивации (если не указан, будет предложен выбор; обязателен, когда ничто не может ответить на запрос)

Опции:

ОпцияОписание
-y, --yesПропустить запросы подтверждения. Обязателен, когда ничто не может на них ответить — агент ИИ, задача CI или любой запуск с закрытым stdin
--skip-specsПропустить обновление спецификаций для одного запуска архивации. Изменение, которое постоянно не имеет дельта-спецификаций, должно содержать skip_specs: true в своем .openspec.yaml — тогда оно архивируется без флага
--no-validateПропустить валидацию (требуется подтверждение). Также отключает вывод функциональных возможностей из эксплуатации — без вердикта валидатора ничего не выводится

Примеры:

bash
# Интерактивная архивация (спрашивает, какое изменение, затем подтверждает)
openspec archive

# Архивировать конкретное изменение
openspec archive add-dark-mode

# Архивировать без запросов (агенты, CI, скрипты)
openspec archive add-dark-mode --yes

# Архивировать инструментальное изменение, не влияющее на спецификации
openspec archive update-ci-config --skip-specs

Вывод функциональной возможности из эксплуатации: Добавьте маркер вывода в метаданные изменения:

yaml
# openspec/changes/retire-legacy/.openspec.yaml
schema: spec-driven
retire_capabilities: true

Затем архивируйте изменение обычным образом:

bash
openspec archive retire-legacy --yes

Когда изменение удаляет последнее требование функциональной возможности, OpenSpec удаляет её рабочий spec.md. Другие дельты возможностей в том же изменении по-прежнему обновляют свои основные спецификации. Без маркера архивация останавливается перед изменением любых файлов и сообщает, что нужно его добавить.

Что делает:

  1. Проверяет изменение (если не указан --no-validate)
  2. Запрашивает подтверждение (если не указан --yes)
  3. Резервирует место назначения архива перед изменением любых основных спецификаций
  4. Проверяет и объединяет активные дельта-спецификации в openspec/specs/ — функциональная возможность, чьё последнее требование удаляется изменением, выводится из эксплуатации, а её spec файл удаляется, но только если в .openspec.yaml изменения установлен retire_capabilities: true рядом с schema:
  5. Перемещает папку изменения в openspec/changes/archive/YYYY-MM-DD-<name>/
  6. Если мутация спецификации или финальный перенос завершаются неудачей до создания полного архива, восстанавливает спецификации и оставляет или возвращает изменение на его активный путь
  7. Если проверенная резервная копия создана, но очистка промежуточных источников не удалась, сохраняется полный архив и зафиксированное состояние спецификаций для восстановления

Без терминала: агент ИИ, задача CI или любой запуск с закрытым stdin не могут ответить на шаг 2, поэтому архивация останавливается, ничего не трогая, завершается с кодом 1 и называет команду для повторного запуска — openspec archive <name> --yes, с любыми другими переданными флагами. Передайте --yes (и имя изменения) сразу, чтобы избежать повторного запроса.

Workflow Commands ​

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

openspec new change ​

Создаёт каталог изменения и необязательные метаданные в корневом каталоге OpenSpec.

bash
openspec new change <name> [options]

Имена изменений должны использовать нижний регистр kebab-case: строчные буквы, цифры и одиночные дефисы. Они не могут содержать пробелы, подчёркивания, заглавные буквы, последовательные дефисы или дефисы в начале/конце. Цифра в начале допустима, поэтому вы можете использовать префиксы для упорядочивания или разграничения изменений, например 100-add-feature или 00001-add-auth.

Параметры:

ПараметрОписание
--description <text>Описание для добавления в index.md
--goal <text>Необязательные метаданные цели для хранения вместе с изменением
--schema <name>Схема рабочего процесса для использования
--store <id>Идентификатор хранилища для использования в качестве корневого каталога OpenSpec (хранилище — это самостоятельный репозиторий OpenSpec, который вы зарегистрировали)
--jsonВывод в формате JSON

Примеры:

bash
openspec new change add-billing-api
openspec new change add-billing-api --store team-context --json

openspec status ​

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

openspec status [options]

Параметры:

ПараметрОписание
--change <id>Имя изменения (запрос при отсутствии)
--schema <name>Переопределение схемы (определяется автоматически из конфигурации изменения)
--jsonВывод в формате JSON

Примеры:

bash
# Интерактивная проверка статуса
openspec status

# Статус для конкретного изменения
openspec status --change add-dark-mode

# JSON для использования агентом
openspec status --change add-dark-mode --json

Вывод (текст):

Change: add-dark-mode
Schema: spec-driven
Progress: 2/4 artifacts complete

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

Изменение с объявлением skip_specs: true отображает этап specs как [~] specs (skipped: change declares skip_specs) и исключает его из подсчёта прогрессa.

Вывод (JSON):

json
{
  "changeName": "add-dark-mode",
  "schemaName": "spec-driven",
  "isPlanningComplete": false,
  "isComplete": false,
  "applyRequires": ["tasks"],
  "artifacts": [
    {"id": "proposal", "outputPath": "proposal.md", "status": "done", "requires": []},
    {"id": "specs", "outputPath": "specs/**/*.md", "status": "done", "requires": ["proposal"]},
    {"id": "design", "outputPath": "design.md", "status": "ready", "requires": ["proposal"]},
    {"id": "tasks", "outputPath": "tasks.md", "status": "blocked", "requires": ["specs", "design"], "missingDeps": ["design"]}
  ]
}

isPlanningComplete сообщает, существует ли каждый не пропущенный артефакт планирования; пропущенные артефакты считаются выполненными без создания. Это поле не сообщает о завершении задач реализации. isComplete сохраняется как алиас совместимости с тем же значением.

Артефакты перечисляются в порядке зависимостей — зависимость никогда не появляется после того, что её требует, — а артефакты, которые становятся готовыми одновременно (у spec-driven и specs, и design требуется только proposal), сохраняют порядок, объявленный схемой, а не алфавитный. Таким образом, первый элемент с ready — это артефакт, который нужно написать следующим.


openspec instructions ​

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

openspec instructions [artifact] [options]

Аргументы:

АргументОбязательныйОписание
artifactНетИдентификатор артефакта или входная поверхность рабочего процесса: apply или archive

Параметры:

ПараметрОписание
--change <id>Имя изменения (обязательно в неинтерактивном режиме)
--schema <name>Переопределение схемы
--jsonВывод в формате JSON

Особые случаи: Используйте apply, чтобы получить инструкции по реализации задач. Используйте archive, чтобы получить текущие входные данные архива только для чтения (context и operationGuidance) для действительного изменения; это не архивирует и не изменяет ничего.

Примеры:

bash
# Получить инструкции для следующего артефакта
openspec instructions --change add-dark-mode

# Получить инструкции для конкретного артефакта
openspec instructions design --change add-dark-mode

# Получить инструкции по применению/реализации
openspec instructions apply --change add-dark-mode

# Получить текущие входные данные операции архива без архивирования
openspec instructions archive --change add-dark-mode --json

# JSON для потребления агентом
openspec instructions design --change add-dark-mode --json

Вывод включает:

  • Содержимое шаблона для артефакта
  • Контекст проекта из конфигурации
  • Содержимое из зависимых артефактов
  • Правила для каждого артефакта из конфигурации
  • Текущий контекст проекта и соответствующие рекомендации по операциям для apply/archive

Входные данные операций читаются из разрешённого репозитория или выбранного хранилища при каждом вызове. Контекст проекта — это обязательный входной параметр уровня подсказки: агенты читают его и применяют соответствующие факты проекта, соглашения и ограничения. Рекомендации по операциям — это необязательные дополнительные советы: агенты рассматривают каждый пункт и следуют только тем, которые применимы и совместимы со встроенным рабочим процессом. Оба поля остаются отдельными от явных пользовательских выборов, состояния, управляемого CLI, встроенных инструкций и правил артефактов. Конфликтующий контекст сообщается; конфликтующие или неприменимые рекомендации не выполняются, и причина объясняется. Это поведенческие контракты для сгенерированных агентов, а не проверяемые CLI-проверки. instructions archive возвращает только выбранное изменение, необязательные входные данные и корневые метаданные; он не включает статический рабочий процесс архива.

Для артефакта, пропущенного через skip_specs: true, выводом является только предупреждение (JSON добавляет поля skipped/warning) — артефакт не должен быть создан.


openspec templates ​

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

openspec templates [options]

Параметры:

ПараметрОписание
--schema <name>Схема для просмотра (по умолчанию: spec-driven)
--jsonВывод в формате JSON

Примеры:

bash
# Показать пути шаблонов для схемы по умолчанию
openspec templates

# Показать шаблоны для пользовательской схемы
openspec templates --schema my-workflow

# JSON для программного использования
openspec templates --json

Вывод (текст):

Schema: spec-driven

Templates:
  proposal  → ~/.openspec/schemas/spec-driven/templates/proposal.md
  specs     → ~/.openspec/schemas/spec-driven/templates/specs.md
  design    → ~/.openspec/schemas/spec-driven/templates/design.md
  tasks     → ~/.openspec/schemas/spec-driven/templates/tasks.md

openspec schemas ​

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

openspec schemas [options]

Параметры:

ПараметрОписание
--jsonВывод в формате JSON
--store <id>Использовать зарегистрированное хранилище в качестве корневого каталога OpenSpec

Пример:

bash
openspec schemas

Вывод:

Available schemas:

  spec-driven (package)
    The default spec-driven development workflow
    Flow: proposal → specs → design → tasks

  my-custom (project)
    Custom workflow for this project
    Flow: research → proposal → tasks

Команды схем ​

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

openspec schema init ​

Создание новой локальной для проекта схемы.

openspec schema init <name> [options]

Аргументы:

АргументОбязательныйОписание
nameДаИмя схемы (kebab-case)

Опции:

ОпцияОписание
--description <text>Описание схемы
--artifacts <list>Список идентификаторов артефактов через запятую (по умолчанию: proposal,specs,design,tasks)
--defaultУстановить как схему по умолчанию для проекта
--no-defaultНе запрашивать установку в качестве схемы по умолчанию
--forceПерезаписать существующую схему
--jsonВывод в формате JSON

Примеры:

bash
# Интерактивное создание схемы
openspec schema init research-first

# Неинтерактивное создание с указанием конкретных артефактов
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

Что создается:

openspec/schemas/<name>/
├── schema.yaml           # Определение схемы
└── templates/
    ├── proposal.md       # Шаблон для каждого артефакта
    ├── specs.md
    ├── design.md
    └── tasks.md

openspec schema fork ​

Копирование существующей схемы в ваш проект для кастомизации.

openspec schema fork <source> [name] [options]

Аргументы:

АргументОбязательныйОписание
sourceДаСхема для копирования
nameНетНовое имя схемы (по умолчанию: <source>-custom)

Опции:

ОпцияОписание
--forceПерезаписать существующий файл назначения
--jsonВывод в формате JSON

Пример:

bash
# Копирование встроенной схемы spec-driven
openspec schema fork spec-driven my-workflow

openspec schema validate ​

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

openspec schema validate [name] [options]

Аргументы:

АргументОбязательныйОписание
nameНетСхема для проверки (если не указано, проверяются все схемы)

Опции:

ОпцияОписание
--verboseПоказывать подробные шаги проверки
--jsonВывод в формате JSON

Пример:

bash
# Проверка конкретной схемы
openspec schema validate my-workflow

# Проверка всех схем
openspec schema validate

openspec schema which ​

Показывает источник разрешения схемы (полезно для отладки приоритетов).

openspec schema which [name] [options]

Аргументы:

АргументОбязательныйОписание
nameНетИмя схемы

Опции:

ОпцияОписание
--allСписок всех схем с их источниками
--jsonВывод в формате JSON

Пример:

bash
# Проверка источника схемы
openspec schema which spec-driven

Вывод:

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

Приоритет схем:

  1. Проект: openspec/schemas/<name>/
  2. Пользователь: ~/.local/share/openspec/schemas/<name>/
  3. Пакет: Встроенные схемы

Команды конфигурации ​

openspec config ​

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

openspec config <subcommand> [options]

Подкоманды:

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

Примеры:

bash
# Показать путь к файлу конфигурации
openspec config path

# Список всех настроек
openspec config list

# Получить конкретное значение
openspec config get telemetry.enabled

# Установить значение (отключить анонимную телеметрию использования)
openspec config set telemetry.enabled false

# Явно установить строковое значение
openspec config set user.name "My Name" --string

# Удалить пользовательскую настройку
openspec config unset user.name

# Установить системную настройку по умолчанию (корневой указатель резервного хранилища при отсутствии --store,
# локального корня или проектного хранилища)
openspec config set defaultStore team-plans

# Сбросить всю конфигурацию
openspec config reset --all --yes

# Редактировать конфигурацию в вашем редакторе
openspec config edit

# Настроить профиль с помощью мастера на основе действий
openspec config profile

# Быстрая предустановка: переключение рабочих процессов на core (сохраняет режим доставки)
openspec config profile core

Отказ от телеметрии: telemetry.enabled по умолчанию включено, если не задано (модель отказа). Установите значение false, чтобы отключить статистику анонимного использования и проверку версии openspec update. Переменные окружения имеют приоритет над конфигурацией: OPENSPEC_TELEMETRY=0, DO_NOT_TRACK=1, и истинное значение CI (например, true/1/yes) всегда отключает телеметрию независимо от значения в конфигурации.

openspec config profile начинается со сводки текущего состояния, затем позволяет выбрать:

  • Изменить доставку и рабочие процессы
  • Изменить только доставку
  • Изменить только рабочие процессы
  • Сохранить текущие настройки (выход)

Если вы сохраняете текущие настройки, изменения не записываются, и запрос на обновление не отображается. Если изменений конфигурации нет, но текущие файлы проекта рассинхронизированы с вашим глобальным профилем/режимом доставки, OpenSpec покажет предупреждение и предложит выполнить openspec update. Нажатие Ctrl+C также корректно отменяет процесс (без вывода стека вызовов) и завершает работу с кодом 130. В контрольном списке рабочих процессов [x] означает, что рабочий процесс выбран в глобальной конфигурации. Чтобы применить эти выборы к файлам проекта, выполните openspec update (или выберите Apply changes to this project now? при появлении запроса внутри проекта).

Интерактивные примеры:

bash
# Обновление только доставки
openspec config profile
# выберите: Change delivery only
# выберите доставку: Skills only

# Обновление только рабочих процессов
openspec config profile
# выберите: Change workflows only
# отметьте рабочие процессы в контрольном списке, затем подтвердите

Вспомогательные команды ​

openspec feedback ​

Отправка отзывов об OpenSpec. Создает issue в GitHub.

openspec feedback <message> [options]

Аргументы:

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

Опции:

ОпцияОписание
--body <text>Дополнительные детали, добавляемые после краткого резюме

Требования: Должны быть установлены и аутентифицированы GitHub CLI (gh).

Пример:

bash
openspec feedback "Add support for custom artifact types" \
  --body "I'd like to define my own artifact types beyond the built-in ones."

openspec completion ​

Управление автодополнением команд для CLI OpenSpec.

openspec completion <subcommand> [shell]

Подкоманды:

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

Поддерживаемые оболочки: bash, zsh, fish, powershell

Примеры:

bash
# Установка дополнений (автоматическое определение оболочки)
openspec completion install

# Установка для конкретной оболочки
openspec completion install zsh

# Генерация скрипта для ручной установки (bash)
openspec completion generate bash > ~/.bash_completion.d/openspec

# Удаление
openspec completion uninstall

Windows (PowerShell): Установка дополнений для текущего хоста PowerShell:

powershell
$env:PROFILE = $PROFILE
openspec completion install powershell
. $PROFILE

$env:PROFILE указывает OpenSpec, какой профиль нужно настроить в этой сессии. Установщик создает отсутствующие директории профиля и добавляет управляемый блок, который загружает OpenSpecCompletion.ps1. Перезагрузка профиля немедленно включает автодополнение.

Для удаления из текущего хоста выполните:

powershell
$env:PROFILE = $PROFILE
openspec completion uninstall powershell

Перезапустите PowerShell после удаления, чтобы очистить автодополнение из текущей сессии.

Автодополнение является опциональным. CLI упоминает о нем один раз, в stderr, при первом запуске команды в интерактивном терминале, и больше никогда — он также молчит, если у вас уже установлены дополнения. Установите OPENSPEC_NO_COMPLETIONS=1, чтобы полностью подавить этот совет.


Коды выхода ​

КодЗначение
0Успех
1Ошибка (сбой проверки, отсутствие файлов и т.д.)

Переменные окружения ​

ПеременнаяОписание
OPENSPEC_TELEMETRYУстановите 0, чтобы отключить телеметрию и проверку версии openspec update (переопределяет telemetry.enabled в глобальной конфигурации)
DO_NOT_TRACKУстановите 1, чтобы отключить телеметрию и проверку версии openspec update (стандартный сигнал DNT; переопределяет конфигурацию)
OPENSPEC_CONCURRENCYПараллелизм по умолчанию для массовой проверки (по умолчанию: 6)
EDITOR или VISUALРедактор для openspec config edit
NO_COLORОтключает вывод цветовых кодов при установке
OPENSPEC_NO_ANIMATIONОтключает приветственную анимацию openspec init при установке
OPENSPEC_NO_COMPLETIONSУстановите 1, чтобы подавить одноразовый совет об автодополнении оболочек
OPENSPEC_NO_UPDATE_CHECKОтключает проверку openspec update на наличие более новой опубликованной версии CLI при установке (любое значение, включая пустое). Также пропускается, если установлена переменная CI (кроме значений false/0/no/off) или NODE_ENV=test
npm_config_registryРеестр, который запрашивает проверка версии openspec update. Должен быть URL http(s) или произойдет возврат к https://registry.npmjs.org. Файл .npmrc не читается

Связанная документация ​

  • Commands - AI slash-команды (/opsx:propose, /opsx:apply и др.)
  • Workflows - Распространенные шаблоны и случаи использования каждой команды
  • Customization - Создание пользовательских схем и шаблонов
  • Getting Started - Руководство по первоначальной настройке