CLI

КомандыCopy Anchor Link

Настройка

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

Процессы и схемы

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

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

Утилиты

Устаревшие

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

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

openspec initCopy Anchor Link

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

openspec init                        # current directory, interactive tool picker
openspec init --tools claude,cursor  # set up specific tools, no prompts
openspec init --tools none           # openspec/ structure only, no tool files

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

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

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

# install Claude Code integration files in the code repo
openspec init --tools claude

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

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

Аргументы

Опции

Вывод

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

▌ OpenSpec structure created
✔ Setup complete for Claude Code

OpenSpec Setup Complete

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

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

Restart your IDE for the new commands to take effect.

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

Коды возврата

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

openspec updateCopy Anchor Link

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

openspec update             # refresh tools whose files are older than the CLI
openspec update --force     # rewrite files even when they're current
openspec update --dry-run   # list what an update would change, and change nothing

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

Аргументы

Опции

Предпросмотр обновления

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

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

openspec update --dry-run

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

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

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

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

Вывод

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

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

Use --force to refresh files anyway.

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

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

✔ Updated Claude Code

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

Restart your IDE for changes to take effect.

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

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

Коды возврата

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

openspec configCopy Anchor Link

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

openspec config list                  # see current settings
openspec config set delivery skills   # change one value
openspec config profile               # interactive workflow picker

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

openspec config pathCopy Anchor Link

openspec config path

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

openspec config listCopy Anchor Link

openspec config list          # readable settings plus profile summary
openspec config list --json   # raw config as JSON

Опции

Вывод

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

featureFlags: {}
profile: core
delivery: both

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

openspec config getCopy Anchor Link

openspec config get delivery

Аргументы

Вывод

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

both

Коды возврата

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

openspec config setCopy Anchor Link

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

Аргументы

Опции

Вывод

Set featureFlags.workspaces = true

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

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

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

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

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

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

openspec config unsetCopy Anchor Link

openspec config unset delivery

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

Unset delivery (reverted to default)

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

openspec config resetCopy Anchor Link

openspec config reset --all      # asks for confirmation
openspec config reset --all -y   # no prompt

Опции

Вывод

Configuration reset to defaults

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

Коды возврата

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

openspec config editCopy Anchor Link

openspec config edit

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

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

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

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

openspec config profileCopy Anchor Link

openspec config profile        # interactive picker (needs a terminal)
openspec config profile core   # apply the core preset directly

Аргументы

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

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

Вывод

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

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

Коды возврата

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

openspec listCopy Anchor Link

Выводит список изменений или спецификаций (с флагом --specs).

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

Строки формируются из содержимого openspec/changes/ и openspec/specs/ в разрешённом корне. По умолчанию при выводе списка изменений каталог openspec/changes/archive/ пропускается.

Опции

Вывод

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

Changes:
  add-rate-limit     No tasks      just now

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

Changes:
  add-rate-limit     No tasks      just now

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

Specs:
  api     requirements 1

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

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

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

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

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

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

Коды возврата

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

openspec showCopy Anchor Link

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

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

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

Аргументы

Опции

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

Вывод

Текстовый режим выводит содержимое напрямую без обработки: для изменения выводится его proposal.md, для спецификации — её spec.md.

# Add rate limiting

## Why
Unauthenticated clients can exhaust the API.

## What Changes
- Add per-client rate limiting to the public API.

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

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

Изменение с флагом --json имеет структуру дельт:

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

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

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

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

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

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

Коды возврата

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

openspec viewCopy Anchor Link

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

openspec view   # project summary in one screen

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

Опции

Вывод

OpenSpec Dashboard

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

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

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

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

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

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

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

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

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

Коды возврата

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

openspec validateCopy Anchor Link

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

openspec validate add-rate-limit   # one change or spec, by name
openspec validate --all            # every change and spec

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

Аргументы

Опции

Вывод

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

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

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

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

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

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

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

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

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

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

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

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

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

Для элемента, не прошедшего проверку, перечисляется каждая проблема и способ её исправления:

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

Флаг --json выводит единый отчёт за запуск:

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

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

Коды возврата

• 0: каждый проверенный элемент прошёл валидацию, включая пустую область массовой проверки.
• 1: элемент не прошёл проверку, запрос отчёта некорректен или выполнение завершилось ошибкой (например, неизвестное имя или отсутствует корень OpenSpec).

--report full|findingsCopy Anchor Link

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

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

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

Области проверки

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

Текстовый вывод замечанийCopy Anchor Link

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

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

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

JSON-вывод замечанийCopy Anchor Link

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

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

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

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

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

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

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

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

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

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

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

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

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

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

В Bash с jq:

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

В PowerShell:

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

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

openspec archiveCopy Anchor Link

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

openspec archive add-rate-limit -y                # archive one change, merge its deltas
openspec archive add-rate-limit -y --skip-specs   # archive without touching the specs

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

Аргументы

Опции

Вывод

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

Task status: ✓ Complete

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

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

С флагами --json --yes:

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

Команда archive сначала выполняет валидацию изменения и отклоняет его при наличии ошибок:

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

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

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

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

Коды возврата

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

openspec newCopy Anchor Link

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

openspec new change add-caching                                # metadata only
openspec new change add-search --goal "Users can search docs"  # record a goal

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

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

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

Аргументы

Опции

Вывод

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

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

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

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

Это уведомление направляется в stdout вместе с остальным текстом для пользователя и никогда не отображается с флагом --json.

С флагом --json в проекте, где уже есть openspec/:

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

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

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

Коды возврата

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

openspec statusCopy Anchor Link

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

openspec status --change add-rate-limit          # checklist view
openspec status --change add-rate-limit --json   # structured report
openspec status --all                            # every active change
openspec status --all --json                     # one batch report

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

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

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

Опции

Вывод

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

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

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

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

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

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

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

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

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

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

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

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

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

Коды возврата

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

openspec instructionsCopy Anchor Link

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

openspec instructions proposal --change add-rate-limit   # how to write one artifact
openspec instructions apply --change add-rate-limit      # how to implement the change
openspec instructions archive --change add-rate-limit    # inputs for archiving

Аргументы

Опции

Вывод

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

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

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

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

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

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

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

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

### Progress
1/3 complete

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

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

No project context or operation guidance configured.

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

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

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

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

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

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

Коды возврата

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

openspec templatesCopy Anchor Link

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

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

Опции

Вывод

Schema: spec-driven
Source: package

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

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

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

Коды возврата

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

openspec schemasCopy Anchor Link

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

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

Опции

Вывод

Available schemas:

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

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

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

Коды возврата

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

openspec schemaCopy Anchor Link

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

openspec schema which spec-driven          # where a schema resolves from
openspec schema fork spec-driven my-flow   # copy a schema into the project
openspec schema init my-schema             # create a schema from scratch

Схемы разрешаются из трёх мест. Используется первое совпадение:

openspec schema whichCopy Anchor Link

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

openspec schema which spec-driven
openspec schema which --all        # every schema, grouped by source

Аргументы

Опции

Вывод

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

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

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

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

openspec schema validateCopy Anchor Link

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

openspec schema validate spec-driven   # one schema, from any source
openspec schema validate               # every project-local schema

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

Опции

Вывод

✓ Schema 'spec-driven' is valid

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

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

openspec schema forkCopy Anchor Link

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

openspec schema fork spec-driven my-flow

Аргументы

Опции

Вывод

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

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

Копия помещается в openspec/schemas/, а поле name: в её файле schema.yaml перезаписывается новым именем:

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

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

openspec schema initCopy Anchor Link

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

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

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

Аргументы

Опции

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

Вывод

✔ Created schema 'my-schema'

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

Artifacts: proposal, tasks

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

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

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

openspec storeCopy Anchor Link

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

openspec store setup team-context --path ~/openspec/team-context   # create and register
openspec store register ~/stores/design-system                     # register an existing checkout
openspec store list                                                # see what's registered

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

openspec store setupCopy Anchor Link

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

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

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

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

Аргументы

Опции

Вывод

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

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

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

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

openspec store registerCopy Anchor Link

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

openspec store register ~/stores/design-system

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

Аргументы

Опции

Вывод

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

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

openspec store unregisterCopy Anchor Link

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

openspec store unregister design-system

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

openspec store removeCopy Anchor Link

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

openspec store remove design-system --yes

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

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

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

Опции

Вывод

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

openspec store listCopy Anchor Link

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

openspec store list

OpenSpec stores (2)

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

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

openspec store doctorCopy Anchor Link

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

openspec store doctor                # every registered store
openspec store doctor team-context  # one store

Вывод

Store doctor

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

Коды возврата

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

openspec doctorCopy Anchor Link

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

openspec doctor                       # nearest openspec/ root above your cwd
openspec doctor --store team-context  # a registered store as the root

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

Опции

Вывод

Doctor

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

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

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

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

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

References
  (none declared)

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

Коды возврата

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

openspec contextCopy Anchor Link

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

openspec context                       # nearest openspec/ root above your cwd
openspec context --store team-context  # a registered store as the root
openspec context --json                # agent brief

Ссылки, которые не удаётся разрешить на этой машине, попадают в раздел Not available on this machine вместе со способом исправления для каждой из них.

Опции

Вывод

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

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

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

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

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

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

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

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

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

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

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

Коды возврата

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

openspec worksetCopy Anchor Link

Формирует, хранит и открывает персональные рабочие наборы. Рабочий набор (workset) — это сохранённый именованный список папок, с которыми вы работаете одновременно.

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

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

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

openspec workset createCopy Anchor Link

Сохраняет именованный рабочий набор папок.

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

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

Аргументы

Опции

Вывод

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

openspec workset listCopy Anchor Link

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

openspec workset list   # alias: ls

Опции

Вывод

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

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

С флагом --json:

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

openspec workset openCopy Anchor Link

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

openspec workset open checkout                # saved tool, or a prompt
openspec workset open checkout --tool cursor  # this tool just this once

Аргументы

Опции

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

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

Коды возврата

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

openspec workset removeCopy Anchor Link

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

openspec workset remove checkout --yes

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

Опции

Вывод

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

openspec versionCopy Anchor Link

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

openspec version                 # local version and install details
openspec version --json          # structured local report
openspec version --check         # also check the registry for an update
openspec version --check --json  # structured local and update report

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

Опции

Вывод

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

OpenSpec 1.13.2 (npm, global)

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

Флаг --json сохраняет неизвестные детали в виде явных значений null:

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

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

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

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

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

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

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

Коды возврата

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

openspec installCopy Anchor Link

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

openspec install          # newest release
openspec install 1.15.0   # a specific release

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

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

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

Аргументы

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

Коды возврата

• 0: установлено.
• 1: указанная версия не является версией релиза, либо произошёл сбой загрузки или установки. Ваша текущая копия остаётся без изменений.

openspec feedbackCopy Anchor Link

Отправляет обратную связь об OpenSpec.

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

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

Аргументы

Опции

Вывод

При успешной отправке:

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

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

Коды возврата

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

openspec completionCopy Anchor Link

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

openspec completion install        # detect your shell, install, wire up config
openspec completion generate zsh   # print the script to stdout

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

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

openspec completion generateCopy Anchor Link

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

#compdef openspec

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

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

openspec completion installCopy Anchor Link

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

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

Опции

Вывод

✓ Completion script installed and .zshrc configured successfully

Restart your shell or run: exec zsh

openspec completion uninstallCopy Anchor Link

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

Опции

Вывод

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

Коды возврата

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

openspec changeCopy Anchor Link

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

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

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

openspec specCopy Anchor Link

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

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

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