Справочник по 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. См. Поддерживаемые инструменты для путей навыков и команд каждого инструмента.
Примеры:
# Интерактивная инициализация
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 | Принудительное обновление, даже если файлы актуальны |
Пример:
# Обновление файлов инструкций после обновления npm
npm install -g @fission-ai/openspec@latest
openspec updateСначала обновите пакет. Файлы инструкций генерируются установленным CLI, поэтому запуск openspec update против устаревшей установки сообщает, что всё актуально, не добавляя рабочие процессы из новых релизов.
Чтобы сделать это видимым, openspec update спрашивает реестр npm, была ли опубликована более новая версия CLI. Если ваша версия отстаёт, он предлагает обновиться:
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 / dlx | npx @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.
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 по умолчанию.
Примеры:
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 --jsonopenspec store register
Регистрация существующей папки локального хранилища. Во время бета-тестирования хранилищ корень может быть зарегистрирован до того, как будут созданы какие-либо изменения, применены спецификации или архивированы изменения; в этом случае openspec/changes/, openspec/specs/ и openspec/changes/archive/ могут отсутствовать, пока обычные команды не создадут их. Репозиторий, содержащий только конфигурацию и объявляющий store: <id>, остается указателем на другое хранилище и не регистрируется как корень хранилища, если этот указатель не будет удален.
openspec store register [path] [options]Опции:
| Опция | Описание |
|---|---|
--id <id> | Идентификатор хранилища; по умолчанию используется метаданные хранилища или имя папки |
--yes | Подтвердить создание метаданных идентичности хранилища для корректного корня OpenSpec |
--json | Вывод в формате JSON |
openspec store unregister
Забыть регистрацию локального хранилища без удаления файлов.
openspec store unregister <id> [--json]Используйте эту команду, когда хранилище было перемещено, клонировано в другое место или больше не должно отображаться OpenSpec на этой машине.
openspec store remove
Удалить регистрацию локального хранилища и удалить его локальную папку.
openspec store remove <id> [--yes] [--json]Команда remove показывает точную папку перед удалением в интерактивном терминале. Агенты, скрипты и вызовы через JSON должны передать --yes для подтверждения удаления. OpenSpec отказывается удалять папку, которая не содержит соответствующих метаданных хранилища.
openspec store list
Список локально зарегистрированных хранилищ.
openspec store list [--json]
openspec store ls [--json]openspec store doctor
Проверка регистрации локального хранилища, метаданных и наличия Git.
openspec store doctor [id] [--json]Команда doctor предназначена только для диагностики; она сообщает об отсутствующих корнях, несоответствиях метаданных и недопустимом состоянии локального реестра, не изменяя само хранилище.
Ссылки на хранилища из проекта
Репозиторий проекта может объявить, какие хранилища используются в его работе, в файле openspec/config.yaml:
schema: spec-driven
references:
- team-contextНачиная с этого момента, вывод openspec instructions в этом репозитории (как для отдельных артефактов, так и для поверхности apply, в режимах JSON и человека) содержит индекс спецификаций каждого ссылочного хранилища — идентификаторы спецификаций, однострочное резюме из раздела Purpose каждой спецификации и команду для получения (openspec show <spec-id> --type spec --store <id>). Индекс формируется в реальном времени на основе зарегистрированной копии при каждом запуске; содержимое спецификаций никогда не копируется в вывод.
Ссылки являются контекстом только для чтения. Они никогда не меняют область действия команд: работа остается в собственном корне репозитория, а запись в ссылочное хранилище остается явным действием с флагом --store. Ссылка, которую невозможно разрешить (например, хранилище не зарегистрировано на этой машине), преобразуется в предупреждение в индексе с точным исправлением, и инструкции все равно генерируются. openspec doctor сообщает о здоровье ссылок в одном месте.
Запись источника клонирования хранилища
Хранилище может записать свой канонический источник клонирования в файл своей идентичности, чтобы он всегда был доступен после регистрации:
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>):
references:
- { id: team-context, remote: "git@github.com:acme/team-context.git" }Запись удаленного адреса не означает синхронизации: OpenSpec никогда не выполняет клонирование, вытягивание или отправку самостоятельно.
Объявление хранилища по умолчанию
Репозиторий, чье планирование полностью вынесено вовне — без локальных openspec/specs/ или openspec/changes/ — может объявить свое хранилище один раз вместо передачи --store в каждой команде:
# 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, и доступны ли хранилища, на которые он ссылается, на этой машине?
openspec doctor [--store <id>] [--json]Отчёт разделяет здоровье корня, здоровье метаданных хранилищ (включая примечание, когда записанный удалённый репозиторий расходится с origin рабочей копии, и примечание, когда рабочая копия хранилища отстала от последнего полученного отслеживаемого ref вышестоящего репозитория), и здоровье ссылок (те же диагностические инструкции, которые показывает instructions, с исправлениями клонирования для неразрешённых ссылок). Находки о здоровье любой серьёзности завершаются кодом 0 — агенты читают массивы status; только сбои команд (нет корня, неизвестное хранилище) завершаются кодом 1. Doctor никогда не клонирует, не синхронизирует и не исправляет. Чтобы получить сам собранный набор, а не его здоровье, используйте openspec context.
Рабочий контекст (собранный набор)
Всё, к чему эта работа относится через объявления OpenSpec, в одном рабочем наборе: корень OpenSpec и хранилища, на которые он ссылается.
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 отвечает на вопрос, что собой представляет набор.
Персональные рабочие наборы
Бета. Рабочие наборы — часть новой бета-поверхности; команды, флаги и форматы файлов могут меняться между выпусками. Для пошагового руководства см. руководство по хранилищам.
Рабочий набор — это персональное именованное представление папок, с которыми вы работаете вместе, — корень планирования плюс всё остальное, что вы выберете, — хранится на вашей машине и открывается по имени в вашем инструменте. Он чисто локальный: никогда не коммитится, не публикуется, не выводится из объявлений, и его удаление никогда не затрагивает папки-элементы.
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) добавляет инструменты или настраивает встроенные по полям:
{
"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 |
Примеры:
# Список всех активных изменений
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) |
Примеры:
# Интерактивный выбор
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 хука.
Примеры:
# Интерактивная валидация
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):
{
"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 | Пропустить валидацию (требуется подтверждение). Также отключает вывод функциональных возможностей из эксплуатации — без вердикта валидатора ничего не выводится |
Примеры:
# Интерактивная архивация (спрашивает, какое изменение, затем подтверждает)
openspec archive
# Архивировать конкретное изменение
openspec archive add-dark-mode
# Архивировать без запросов (агенты, CI, скрипты)
openspec archive add-dark-mode --yes
# Архивировать инструментальное изменение, не влияющее на спецификации
openspec archive update-ci-config --skip-specsВывод функциональной возможности из эксплуатации: Добавьте маркер вывода в метаданные изменения:
# openspec/changes/retire-legacy/.openspec.yaml
schema: spec-driven
retire_capabilities: trueЗатем архивируйте изменение обычным образом:
openspec archive retire-legacy --yesКогда изменение удаляет последнее требование функциональной возможности, OpenSpec удаляет её рабочий spec.md. Другие дельты возможностей в том же изменении по-прежнему обновляют свои основные спецификации. Без маркера архивация останавливается перед изменением любых файлов и сообщает, что нужно его добавить.
Что делает:
- Проверяет изменение (если не указан
--no-validate) - Запрашивает подтверждение (если не указан
--yes) - Резервирует место назначения архива перед изменением любых основных спецификаций
- Проверяет и объединяет активные дельта-спецификации в
openspec/specs/— функциональная возможность, чьё последнее требование удаляется изменением, выводится из эксплуатации, а её spec файл удаляется, но только если в.openspec.yamlизменения установленretire_capabilities: trueрядом сschema: - Перемещает папку изменения в
openspec/changes/archive/YYYY-MM-DD-<name>/ - Если мутация спецификации или финальный перенос завершаются неудачей до создания полного архива, восстанавливает спецификации и оставляет или возвращает изменение на его активный путь
- Если проверенная резервная копия создана, но очистка промежуточных источников не удалась, сохраняется полный архив и зафиксированное состояние спецификаций для восстановления
Без терминала: агент ИИ, задача CI или любой запуск с закрытым stdin не могут ответить на шаг 2, поэтому архивация останавливается, ничего не трогая, завершается с кодом 1 и называет команду для повторного запуска — openspec archive <name> --yes, с любыми другими переданными флагами. Передайте --yes (и имя изменения) сразу, чтобы избежать повторного запроса.
Workflow Commands
Эти команды поддерживают артефакто-ориентированный рабочий процесс OPSX. Они полезны как для людей, отслеживающих прогресс, так и для агентов, определяющих следующие шаги.
openspec new change
Создаёт каталог изменения и необязательные метаданные в корневом каталоге OpenSpec.
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 |
Примеры:
openspec new change add-billing-api
openspec new change add-billing-api --store team-context --jsonopenspec status
Отображает статус завершения артефактов для изменения.
openspec status [options]Параметры:
| Параметр | Описание |
|---|---|
--change <id> | Имя изменения (запрос при отсутствии) |
--schema <name> | Переопределение схемы (определяется автоматически из конфигурации изменения) |
--json | Вывод в формате JSON |
Примеры:
# Интерактивная проверка статуса
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):
{
"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) для действительного изменения; это не архивирует и не изменяет ничего.
Примеры:
# Получить инструкции для следующего артефакта
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 |
Примеры:
# Показать пути шаблонов для схемы по умолчанию
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.mdopenspec schemas
Перечисляет доступные схемы рабочего процесса с их описаниями и потоками артефактов.
openspec schemas [options]Параметры:
| Параметр | Описание |
|---|---|
--json | Вывод в формате JSON |
--store <id> | Использовать зарегистрированное хранилище в качестве корневого каталога OpenSpec |
Пример:
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 |
Примеры:
# Интерактивное создание схемы
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.mdopenspec schema fork
Копирование существующей схемы в ваш проект для кастомизации.
openspec schema fork <source> [name] [options]Аргументы:
| Аргумент | Обязательный | Описание |
|---|---|---|
source | Да | Схема для копирования |
name | Нет | Новое имя схемы (по умолчанию: <source>-custom) |
Опции:
| Опция | Описание |
|---|---|
--force | Перезаписать существующий файл назначения |
--json | Вывод в формате JSON |
Пример:
# Копирование встроенной схемы spec-driven
openspec schema fork spec-driven my-workflowopenspec schema validate
Проверка структуры схемы и шаблонов.
openspec schema validate [name] [options]Аргументы:
| Аргумент | Обязательный | Описание |
|---|---|---|
name | Нет | Схема для проверки (если не указано, проверяются все схемы) |
Опции:
| Опция | Описание |
|---|---|
--verbose | Показывать подробные шаги проверки |
--json | Вывод в формате JSON |
Пример:
# Проверка конкретной схемы
openspec schema validate my-workflow
# Проверка всех схем
openspec schema validateopenspec schema which
Показывает источник разрешения схемы (полезно для отладки приоритетов).
openspec schema which [name] [options]Аргументы:
| Аргумент | Обязательный | Описание |
|---|---|---|
name | Нет | Имя схемы |
Опции:
| Опция | Описание |
|---|---|
--all | Список всех схем с их источниками |
--json | Вывод в формате JSON |
Пример:
# Проверка источника схемы
openspec schema which spec-drivenВывод:
spec-driven resolves from: package
Source: /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-drivenПриоритет схем:
- Проект:
openspec/schemas/<name>/ - Пользователь:
~/.local/share/openspec/schemas/<name>/ - Пакет: Встроенные схемы
Команды конфигурации
openspec config
Просмотр и изменение глобальной конфигурации OpenSpec.
openspec config <subcommand> [options]Подкоманды:
| Подкоманда | Описание |
|---|---|
path | Показать расположение файла конфигурации |
list | Показать все текущие настройки |
get <key> | Получить конкретное значение |
set <key> <value> | Установить значение |
unset <key> | Удалить ключ |
reset | Сбросить до значений по умолчанию |
edit | Открыть в $EDITOR |
profile [preset] | Интерактивная настройка профиля рабочего процесса или использование предустановки |
Примеры:
# Показать путь к файлу конфигурации
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? при появлении запроса внутри проекта).
Интерактивные примеры:
# Обновление только доставки
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).
Пример:
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
Примеры:
# Установка дополнений (автоматическое определение оболочки)
openspec completion install
# Установка для конкретной оболочки
openspec completion install zsh
# Генерация скрипта для ручной установки (bash)
openspec completion generate bash > ~/.bash_completion.d/openspec
# Удаление
openspec completion uninstallWindows (PowerShell): Установка дополнений для текущего хоста PowerShell:
$env:PROFILE = $PROFILE
openspec completion install powershell
. $PROFILE$env:PROFILE указывает OpenSpec, какой профиль нужно настроить в этой сессии. Установщик создает отсутствующие директории профиля и добавляет управляемый блок, который загружает OpenSpecCompletion.ps1. Перезагрузка профиля немедленно включает автодополнение.
Для удаления из текущего хоста выполните:
$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 - Руководство по первоначальной настройке