Справочник CLI

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

Краткий обзор

Категория	Команды	Назначение
Настройка	`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>`	Переопределить глобальный профиль для этого вызова init (`core` или `custom`)
`--no-animation`	Показать статическую заставку вместо анимированной
`--copilot-cloud`	Без запроса настроить файлы облачного агента GitHub Copilot
`--no-copilot-cloud`	Без запроса пропустить файлы облачного агента 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. Если у вас установлена устаревшая версия, команда предложит обновление:

Доступна более новая версия OpenSpec CLI (v1.6.0 → v1.7.0).
  Запущена из: /usr/local/lib/node_modules/@fission-ai/openspec
? Обновить до v1.7.0 сейчас? (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`
Зависимость проекта	Подсказка обновить зависимость, поскольку файлом блокировки управляет менеджер пакетов проекта
Кэш `npx` / `dlx`	`npx @fission-ai/openspec@latest update` — эта команда одновременно выполняет обновление, второй шаг не нужен
Клонирование через git	Ничего — ваша версия определяется текущей веткой

Если команда что-либо выводит, она указывает каталог, из которого загружен CLI. Проверьте этот путь, если вы обновились, но в PATH по-прежнему используется устаревший shim.

Для запроса используется реестр из 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>`	Сохранить основной удалённый URL в `store.yaml` нового хранилища
`--init-git`	Инициализировать репозиторий Git и создать начальный коммит (по умолчанию)
`--no-init-git`	Пропустить все действия Git: не запускать init и не создавать коммит
`--json`	Вывод в формате JSON

Для неинтерактивного запуска (--json, сценарии, агенты) необходимо указать и ID хранилища, и --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 --json

`openspec store register`

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

openspec store register [path] [options]

Параметры:

Параметр	Описание
`--id <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-режиме, так и в человекочитаемом) содержит индекс спецификаций каждого указанного хранилища: ID спецификаций, краткое описание из раздела 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

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

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

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

Сохранение удалённого URL не является синхронизацией: OpenSpec не клонирует, не выполняет pull и не отправляет изменения самостоятельно.

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

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

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

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

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

Doctor (состояние связей)

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

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

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

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

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

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

Краткий вывод JSON предназначен для агентов (для каждого доступного хранилища указан способ получения данных; для неразрешённых элементов приведены те же команды исправления, что и в doctor). --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`	Проверить, что все задачи архивированных изменений выполнены (для проверки перед коммитом)
`--type <type>`	Указать тип, если имя неоднозначно: `change` или `spec`
`--strict`	Включить строгий режим проверки
`--json`	Вывести результат в формате JSON
`--concurrency <n>`	Максимальное число параллельных проверок (по умолчанию: 6 или значение переменной `OPENSPEC_CONCURRENCY`)
`--no-interactive`	Отключить запросы

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

Примеры:

# Интерактивная проверка
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

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

Проверяю add-dark-mode...
  ✓ proposal.md корректен
  ✓ specs/ui/spec.md корректен
  ⚠ design.md: отсутствует раздел «Технический подход»

Обнаружено 1 предупреждение

Вывод (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

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

schema: spec-driven
retire_capabilities: true

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

openspec archive retire-legacy --yes

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

Что делает команда:

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

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

Команды рабочего процесса

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

`openspec new change`

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

openspec new change <name> [options]

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

Параметры:

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

Примеры:

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

Примеры:

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

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

# JSON для агента
openspec status --change add-dark-mode --json

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

Изменение: add-dark-mode
Схема: spec-driven
Выполнено артефактов: 2/4

[x] proposal
[x] specs
[ ] design
[-] tasks (заблокировано: design)

У изменения с skip_specs: true этап спецификаций отображается как [~] specs (пропущено: в изменении задан skip_specs) и не учитывается в прогрессе.

Вывод (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`	Нет	ID артефакта или интерфейс ввода рабочего процесса: `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

# Получить инструкции для apply/реализации
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

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

Схема: spec-driven

Шаблоны:
  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

Пример:

openspec schemas

Вывод:

Доступные схемы:

  spec-driven (package)
    Стандартный рабочий процесс разработки на основе спецификаций
    Последовательность: proposal → specs → design → tasks

  my-custom (project)
    Пользовательский рабочий процесс этого проекта
    Последовательность: research → proposal → tasks

Команды схем

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

`openspec schema init`

Создать новую схему в проекте.

openspec schema init <name> [options]

Аргументы:

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

Параметры:

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

Примеры:

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

# Неинтерактивный режим с указанными артефактами
openspec schema init rapid \
  --description "Рабочий процесс быстрой итерации" \
  --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

Пример:

# Создать копию встроенной схемы spec-driven
openspec schema fork spec-driven my-workflow

`openspec schema validate`

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

openspec schema validate [name] [options]

Аргументы:

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

Параметры:

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

Пример:

# Проверить конкретную схему
openspec schema validate my-workflow

# Проверить все схемы
openspec schema validate

`openspec schema which`

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

openspec schema which [name] [options]

Аргументы:

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

Параметры:

Параметр	Описание
`--all`	Вывести все схемы с указанием источников
`--json`	Вывод в формате JSON

Пример:

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

Вывод:

spec-driven загружена из: package
  Источник: /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, локальный корень или указатель 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
# выберите: изменить только способ установки
# выберите способ: только навыки

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

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

`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 uninstall

Windows (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`	Отключить проверку наличия более новой версии CLI в `openspec update` (любое значение, включая пустое). Проверка также пропускается, если задана `CI` (кроме `false`/`0`/`no`/`off`) или `NODE_ENV=test`
`npm_config_registry`	Реестр для проверки версии в `openspec update`. Должен быть URL `http(s)`; иначе используется `https://registry.npmjs.org`. Файл `.npmrc` не читается

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

Команды — slash-команды ИИ (/opsx:propose, /opsx:apply и др.)
Рабочие процессы — распространённые шаблоны и их применение
Настройка — создание пользовательских схем и шаблонов
Начало работы — руководство по первоначальной настройке

HagiCode

HagiCode — агентная среда разработки со структурированными процессами, параллельным выполнением несколькими агентами и интерфейсами Hero Dungeon.

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

SmartСтруктурированные процессы превращают намерение в исполнимый путь от идеи до готового изменения.
EfficientМультиагентные процессы параллельно продвигают исследование, реализацию и проверку.
FunHero Dungeon делает длительную совместную разработку наглядной и увлекательной.

Перейти на HagiCode

Справочник CLI

Краткий обзор

Команды для пользователя и агента

Только для пользователя

Для агентов и сценариев

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

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

openspec init

openspec update

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

openspec store setup

openspec store register

openspec store unregister

openspec store remove

openspec store list

openspec store doctor

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

Сохранение адреса клонирования хранилища

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

Doctor (состояние связей)

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

Личные рабочие наборы

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

openspec list

openspec view

openspec show

Команды проверки

openspec validate

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

openspec archive

Команды рабочего процесса

openspec new change

openspec status

openspec instructions

openspec templates

openspec schemas

Команды схем

openspec schema init

openspec schema fork

openspec schema validate

openspec schema which

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

openspec config

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

openspec feedback

openspec completion

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

Переменные среды

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

HagiCode

Сайты экосистемы

Быстрые ссылки

Сообщество

`openspec init`

`openspec update`

`openspec store setup`

`openspec store register`

`openspec store unregister`

`openspec store remove`

`openspec store list`

`openspec store doctor`

`openspec list`

`openspec view`

`openspec show`

`openspec validate`

`openspec archive`

`openspec new change`

`openspec status`

`openspec instructions`

`openspec templates`

`openspec schemas`

`openspec schema init`

`openspec schema fork`

`openspec schema validate`

`openspec schema which`

`openspec config`

`openspec feedback`

`openspec completion`