CLI

Команди терміналу openspec.

Команди

Налаштування

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

Зміни та специфікації

Команда	Призначення
`openspec list`	Перелічити зміни або специфікації за допомогою прапорця `--specs`.
`openspec show`	Вивести зміну або специфікацію у форматі Markdown або JSON.
`openspec view`	Панель приладів на один екран для перегляду специфікацій та змін.
`openspec validate`	Перевірити зміни та специфікації на наявність структурних проблем.
`openspec archive`	Перемістити завершену зміну до архіву та оновити основні специфікації.

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

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

Команда	Призначення
`openspec new`	Створити новий каталог для зміни.
`openspec status`	Статус завершеності артефактів для однієї або всіх активних змін.
`openspec instructions`	Інструкції щодо створення артефакту, його застосування або архівування.
`openspec templates`	Розгорнуті шляхи шаблонів для артефактів схеми.
`openspec schemas`	Перелік доступних схем робочих процесів.
`openspec schema`	Дослідити, розгалужити або створити схему (експериментально).

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

Команда	Призначення
`openspec store`	Створювати та керувати сховищами: окремими репозиторіями OpenSpec, зареєстрованими на вашому комп'ютері.
`openspec doctor`	Звіт про стан зв'язків для визначеного кореневого каталогу OpenSpec.
`openspec context`	Вивести поточний контекст роботи для визначеного кореневого каталогу OpenSpec.
`openspec workset`	Формувати, зберігати та відкривати особисті робочі представлення.

Утиліти

Команда	Призначення
`openspec version`	Повідомити про встановлену версію та за бажанням перевірити наявність оновлень.
`openspec install`	Встановити автономну версію `openspec`, яка працює без Node.js.
`openspec feedback`	Надіслати відгук про OpenSpec.
`openspec completion`	Встановити або згенерувати автодоповнення для оболонки.

Застарілі

Команда	Призначення
`openspec change`	Іменникова форма команд show, list та validate для змін. CLI видає попередження та вказує на команди, що починаються зі дієслова.
`openspec spec`	Іменникова форма команд show, list та validate для специфікацій, із таким самим попередженням.

Кожна команда підтримує прапорці -h, --help. Базова команда openspec також підтримує:

-V, --version: вивести версію CLI.
--no-color: вимкнути кольоровий вивід.

openspec init

Ініціалізує OpenSpec у проєкті.

bash

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 з кореня репозиторію:

bash

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

Файли інтеграції: записані в репозиторій коду.
openspec/config.yaml: збережено байт у байт.
openspec/specs/ та openspec/changes/: не створюються в репозиторії коду.

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

Аргументи

Аргумент	Що це таке
`path`	Каталог проєкту для ініціалізації. За замовчуванням: поточний каталог. Створюється, якщо відсутній.

Параметри

Прапорець	Ефект
`--tools <tools>`	Ідентифікатори інструментів через кому, `all` або `none`. Пропускає вибір. Ідентифікатори наведені в Supported tools.
`--language <language>`	Додати мовну вказівку до конфігурації нового проєкту. Відхиляється, коли рядок `store:` репозиторію вказує на зовнішнє сховище.
`--force`	Видалити файли зі старіших макетів OpenSpec без запитання. Інтерактивні запуски в іншому випадку спочатку підтверджують очищення.
`--profile <profile>`	Перевизначити профіль глобальної конфігурації для цього запуску: `core` (стандартний набір робочих процесів) або `custom` (робочі процеси, збережені у глобальній конфігурації).
`--no-animation`	Показати статичний екран привітання замість анімованого.

Вивід

Кожен вибраний інструмент отримує навички та команди OpenSpec у власному каталозі:

▌ OpenSpec structure created
✔ Setup complete for Claude Code

OpenSpec Setup Complete

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

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

Restart your IDE for the new commands to take effect.

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

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

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

openspec update

Оновлює встановлені файли інструкцій OpenSpec.

bash

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, щоб пропустити перевірку.

Аргументи

Аргумент	Що це таке
`path`	Каталог проєкту для оновлення. За замовчуванням: поточний каталог.

Параметри

Прапорець	Ефект
`--force`	Перезаписати файли кожного налаштованого інструменту, навіть коли вони актуальні.
`--dry-run`	Повідомити про кожен файл, який оновлення додало б, змінило або видалило, і нічого не записувати. Без перевірки оновлення CLI, без запитів. Поєднайте з `--force`, щоб переглянути примусове оновлення.
`--json`	З `--dry-run` виводить план як JSON. Без `--dry-run` завершується з кодом 1.

Попередній перегляд оновлення

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

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

bash

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:

json

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

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

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

Вивід

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

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

Use --force to refresh files anyway.

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

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

✔ Updated Claude Code

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

Restart your IDE for changes to take effect.

У каталозі без OpenSpec update відмовляє:

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

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

0: файли оновлено, або все вже актуальне.
1: немає каталогу OpenSpec за вказаним шляхом, або оновлення не вдалося.

openspec config

Переглядає та змінює глобальну конфігурацію.

bash

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

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

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

openspec config path

bash

openspec config path

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

openspec config list

bash

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

Параметри

Прапорець	Ефект
`--json`	Вивести об'єкт конфігурації як JSON.

Вивід

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

featureFlags: {}
profile: core
delivery: both

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

openspec config get

bash

openspec config get delivery

Аргументи

Аргумент	Що це таке
`key`	Ключ для читання. Крапки досягають вкладених значень (`featureFlags.workspaces`).

Вивід

Голе значення, придатне для скриптів. Об'єкти виводяться як компактний JSON:

both

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

0: значення виведено.
1: ключ не має значення, і нічого не виводиться.

openspec config set

bash

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

Аргументи

Аргумент	Що це таке
`key`	Ключ для запису, з крапками для вкладених значень.
`value`	Нове значення. `true`/`false` стають булевими, числові рядки стають числами.

Параметри

Прапорець	Ефект
`--string`	Зберігти значення як рядок, пропускаючи приведення типу.
`--allow-unknown`	Дозволити ключі, яких немає в схемі.

Вивід

Set featureFlags.workspaces = true

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

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

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

Якщо файл конфігурації існує, але не містить об'єкт JSON, чи то тому, що він взагалі не є дійсним JSON, чи тому, що його корінь — щось інше, наприклад null або масив, config set, config unset та config profile завершуються з кодом 1 і залишають файл без змін. Виправте його за допомогою openspec config edit або замініть за допомогою openspec config reset --all:

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

Поки це не виправлено, телеметрія та перевірка оновлень вимкнені.

openspec config unset

bash

openspec config unset delivery

Видаляє ключ, щоб знову застосувалося значення за замовчуванням. Ключі з вбудованими значеннями за замовчуванням завжди вважаються встановленими, тому це повідомляє про успіх, навіть якщо ви ніколи їх не встановлювали:

Unset delivery (reverted to default)

Ключ, який взагалі не має значення, виводить Key "featureFlags.nothere" was not set. Обидва випадки завершуються з кодом 0. Файл конфігурації, який не вдалося розібрати, натомість завершується з кодом 1, як і для config set.

openspec config reset

bash

openspec config reset --all      # запитує підтвердження
openspec config reset --all -y   # без запиту

Параметри

Прапорець	Ефект
`--all`	Обов'язковий. Скидає все.
`-y, --yes`	Пропустити запит підтвердження.

Вивід

Configuration reset to defaults

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

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

0: скидання виконано, або ви відповіли "ні" на запит.
1: відсутній --all.
130: запит скасовано за допомогою Ctrl-C.

openspec config edit

bash

openspec config edit

Відкриває файл конфігурації в $EDITOR (з відкатом до $VISUAL), попередньо створюючи його зі значеннями за замовчуванням, якщо він відсутній. Коли редактор закривається, файл перевіряється. Недійсний JSON або неприпустима конфігурація завершуються з кодом 1.

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

Без налаштованого редактора завершується з кодом 1:

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

openspec config profile

bash

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

Аргументи

Аргумент	Що це таке
`preset`	Необов'язкова назва пресета. Існує лише `core`. Він вибирає базові робочі процеси та зберігає ваше налаштування доставки.

Без пресета інтерактивний вибір показує вашу поточну доставку та робочі процеси, дозволяє змінити одне або обидва (доставка: обидва, лише навички або лише команди; робочі процеси: список із прапорцями), виводить різницю, а всередині проєкту OpenSpec пропонує запустити для вас openspec update. Поза терміналом завершується з кодом 1:

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

Вивід

Змінена конфігурація не досягає проєктів, доки вони не оновляться:

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

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

0: профіль збережено, або ви зберегли поточні налаштування.
1: невідомий пресет, немає терміналу, або запропонований openspec update не вдався.
130: вибір скасовано за допомогою Ctrl-C.

openspec list

Виводить список змін або специфікацій з прапорцем --specs.

bash

openspec list                    # активні зміни, сортування за датою останнього змінювання
openspec list --archived         # архівовані зміни
openspec list --all              # активні та архівовані зміни
openspec list --specs            # специфікації з кількістю вимог
openspec list --json             # машиночитаний формат, включає визначений кореневий каталог

Рядки беруться з каталогів openspec/changes/ та openspec/specs/ у межах визначеного кореневого каталогу. За замовчуванням перелік змін пропускає каталог openspec/changes/archive/.

Опції

Прапорець	Ефект
`--specs`	Виводити специфікації замість змін.
`--changes`	Виводити зміни. Це значення за замовчуванням.
`--archived`	Виводити лише архівовані зміни. Не можна поєднувати з `--specs`.
`--all`	Виводити активні та архівовані зміни. Не можна поєднувати з `--specs`. Має пріоритет над `--archived`.
`--sort <order>`	`recent` (спочатку останні за змінюванням) або `name`. За замовчуванням: `recent`. Специфікації завжди сортуються за назвою.
`--json`	Виводити JSON замість таблиці.
`--store <id>`	Використовувати зареєстроване сховище як кореневий каталог OpenSpec замість поточного проєкту.

Вивід

Один рядок на зміну: назва, стан завдань, останнє змінювання. У стовпці стану виводиться No tasks, 2/5 tasks або ✓ Complete.

Changes:
  add-rate-limit     No tasks      щойно

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

Changes:
  add-rate-limit     No tasks      щойно

Archived Changes:
  2026-08-10-add-login     ✓ Complete    2 дн тому

Specs:
  api     requirements 1

Опція --json додає кількість завдань та поле status зі значенням no-tasks, in-progress або complete:

json

{
  "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 відхиляють папку з тим самим повідомленням. Щоб виправити це, перемістіть зміну вище та інтегруйте простір імен до її назви:

bash

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

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

0: перелік виведено, навіть якщо він порожній.
1: кореневий каталог OpenSpec не знайдено (за межами проєкту, без --store).

openspec show

Виводить зміну або специфікацію у форматі markdown або JSON.

bash

openspec show add-rate-limit              # зміна: виводить proposal.md
openspec show add-rate-limit --diff       # зміна: додає дифи вимог
openspec show api                         # специфікація: виводить spec.md
openspec show api --json --no-scenarios   # JSON специфікації без тексту сценаріїв

Якщо не вказано назву, команда show запитує, що виводити (зміну чи специфікацію), а потім перелічує елементи для вибору. Поза інтерактивним терміналом вона завершує роботу з кодом 1 і виводить прямі форми команд.

Аргументи

Аргумент	Опис
`item-name`	Зміна або специфікація для виведення, за назвою каталогу (`add-rate-limit`, `api`).

Опції

Прапорець	Ефект
`--json`	Виводити структурований JSON замість сирого markdown.
`--type <change\|spec>`	Визначити тип, якщо зміна та специфікація мають однакову назву.
`--no-interactive`	Ніколи не запитувати: відсутня назва призводить до помилки.
`--deltas-only`	JSON, зміна: обмежити вивід дельтами. JSON зміни вже містить лише дельти, тому вивід відповідає звичайному `--json`.
`--requirements-only`	Застарілий псевдонім для `--deltas-only`. Виводить попередження у stderr.
`--diff`	Зміна: додає дифи дельт за кожним вимогою. Для специфікацій ігнорується з попередженням.
`--requirements`	JSON, специфікація: зберігає текст вимог, очищує масиви `scenarios`.
`--no-scenarios`	JSON, специфікація: такий самий вивід, як у `--requirements`.
`-r, --requirement <id>`	JSON, специфікація: виводить одну вимогу за позицією (індексація з 1). Не можна поєднувати з `--requirements`.
`--store <id>`	Використовувати зареєстроване сховище як кореневий каталог OpenSpec замість поточного проєкту.

Прапорці, які не застосовуються до визначеного типу, ігноруються з попередженням у stderr.

Вивід

Текстовий режим є прямим пропуском: зміна виводить свій proposal.md, специфікація виводить свій spec.md.

# Add rate limiting

## Чому
Неавтентифіковані клієнти можуть вичерпати ресурси API.

## Що змінюється
- Додати обмеження частоти запитів для кожного клієнта до публічного API.

Для зміни `--diff` спочатку друкує пропозицію, а потім розділ `Specifications Changed (diffs)`. ДОДАНІ вимоги включають їхній повний текст. ВИДАЛЕНІ вимоги зберігають авторські Reason та Migration. ПЕРЕЙМЕНОВАНІ вимоги показують FROM та TO. ЗМІНЕНІ вимоги показують уніфікований diff проти відповідної основної вимоги.

Якщо заголовок MODIFIED збігається лише після нормалізації регістру або пробілів, вивід містить і diff, і попередження про те, що зіставлення в архіві є точним. Якщо основна специфікація або вимога відсутня, вивід попереджає та друкує повний блок дельти. Блок MODIFIED без текстових відмінностей друкує `(no textual changes)`.

Зміна з `--json` має форму дельти:

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

Кожна вимога має своє name, текст заголовка після Requirement:. Це ім'я, з яким архів зіставляє записи MODIFIED, REMOVED та RENAMED. Кожен сценарій має своє name, текст заголовка після Scenario:. Рядок # у кінці будь-якого заголовка не є частиною імені.

--json --diff зберігає цю верхньорівневу структуру. Дельта MODIFIED отримує рядок diff, рядок warning або обидва. Інші операції не змінюються. Порожній рядок diff означає, що основний блок і блок дельти текстуально ідентичні.

Специфікація з --json перелічує свої вимоги зі сценаріями. Вимоги та сценарії мають ті самі поля name, що й JSON зміни:

json

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

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

Коди виходу

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

openspec view

Друкує односторінкову панель специфікацій і змін.

bash

openspec view   # project summary in one screen

view друкує панель один раз і завершує роботу. Вона не зчитує натискань клавіш. Зміни групуються за прогресом завдань: Draft (ще немає завдань), Active (завдання виконуються, зі смугою прогресу та відсотками), Completed (усі завдання позначено). Специфікації перелічуються з кількістю вимог, спочатку найбільші.

Опції

Прапорець	Ефект
`--store <id>`	Використовувати зареєстроване сховище як корінь OpenSpec замість поточного проєкту.

Вивід

OpenSpec Dashboard

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

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

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

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

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

Рядок підсумку Task Progress з'являється, коли будь-яка зміна має завдання в процесі.

Кожна активна зміна також показує стани своєї схеми та артефактів під смугою прогресу завдань:

text

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

Маркер	Стан артефакту
`✓`	Його вивід існує. Наявний артефакт завдань вважається виконаним, навіть якщо його чек-лист не завершено.
`→`	Він готовий до створення.
Без маркера	Він заблокований відсутньою залежністю.
`(skipped)`	Зміна його пропускає.

Якщо робочий процес не вдається завантажити, view друкує попередження та залишає прогрес завдань цієї зміни видимим. Запустіть openspec status --change <name>, щоб переглянути робочий процес окремо. Після openspec view --store <id> передайте той самий --store <id> до status.

Коди виходу

0: панель надруковано.
1: корінь OpenSpec не знайдено (поза проєктом, без --store).

openspec validate

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

bash

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

Без імені та без масового прапорця validate пропонує вибрати елементи. Поза інтерактивним терміналом він завершується з кодом 1 і друкує масові прапорці замість цього.

Аргументи

Аргумент	Що це
`item-name`	Зміна або специфікація для перевірки, за назвою папки (`add-rate-limit`, `api`).

Опції

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

Вивід

Масові запуски друкують один рядок статусу для кожного елемента, далі будь-які знахідки, і завершуються підсумками:

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

Знахідки щодо прапорців завдань

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

text

⚠ [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-фронтматерія та відступлений код не скануються, тому вставлений зразок терміналу ніколи не сплутати зі списком завдань.

Знахідки злиття архіву

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

text

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

Ці знахідки з'являються навіть коли перевірка проходить успішно, як у текстовому, так і в JSON-виводі. INFO ніколи не змінює код виходу, навіть за --strict: відсутня ціль може належати сусідній зміні, яка ще не архівована. Дельти, вже синхронізовані з основними специфікаціями, дотримуються наявних правил злиття архіву.

Ця перевірка не запускає пізнішу перевірку злитих специфікацій архіву або перевірки виведення з експлуатації. Чистий звіт не гарантує, що архів спрацює успішно.

Якщо попередня перевірка злиття не може запуститися, знахідка 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 друкує один звіт для запуску:

json

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

Записи issues мають level зі значенням ERROR, WARNING або INFO.

Коди виходу

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

--report full|findings

Вибирає вивід для явної масової області перевірки:

full: кожен елемент. Це за замовчуванням. Явний --report full зберігає наявну форму виводу без додавання метаданих звіту.
findings: лише елементи з проблемами, включно з елементами, що пройшли, але мають попередження або інформацію. Кожен елемент все одно перевіряється. Підсумки, поведінка строгого режиму та коди виходу не змінюються.

bash

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

Області

Прапорці	`report.scope` для знахідок
`--all`	`all`
`--changes`	`changes`
`--specs`	`specs`
`--changes --specs`, або `--all` з будь-яким прапорцем	`all`
`--archived`	`archived`

Обидва явні режими звіту відхиляють позиційне ім'я елемента, відсутню масову область або поєднання архівної та активної областей.

Текстовий вивід знахідок

Людський вивід: stdout друкує Scope: <scope> (<count> items), потім підсумки. Якщо немає елементів із проблемами:

text

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

Мітки елементів із проблемами, мітки серйозності, шляхи та повідомлення друкуються до stderr. Помилки активної області зберігають підказку повторного запуску Details: після підсумків. Наявний банер кореня та вивід прогресу можуть передувати звіту.

JSON-вивід знахідок

--report findings --json друкує один документ. Цей приклад має два чисті елементи:

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. Вони не повертають завершений звіт знахідок або успішний порожній звіт.

Неприпустимі запити звіту

Обидва явні режими звіту відхиляють ці запити до вибору кореня або виявлення елементів:

Непідтримуване значення звіту, включно з порожнім рядком.
Позиційне ім'я елемента, навіть із масовим прапорцем.
Відсутня явна масова область.
--archived разом із --all, --changes або --specs.

У JSON-режимі відхилений запит завершується з кодом 1 лише з масивом status з одного елемента. Він не має root або корисного навантаження звіту:

bash

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

json

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

Людський режим друкує помилку до stderr. Голий --report без значення є синтаксичною помилкою Commander у stderr, включно з --json; він не використовує цю діагностичну оболонку.

Зовнішня фільтрація повного звіту

Для власного JSON-перегляду відфільтруйте повний звіт за допомогою jq або PowerShell. Ці приклади скриптів зберігають код виходу перевірки та залишають документи помилок команд незмінними.

У Bash з jq:

bash

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:

powershell

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

Ці власні перегляди зберігають ключі повного звіту, але опускають чисті елементи. Вони не є ані повними звітами full-v1, ані версіонованою формою --report findings.

openspec archive

Переміщує завершену зміну до архіву та оновлює основні специфікації.

bash

openspec archive add-rate-limit -y                # архівувати одну зміну та об'єднати її дельти
openspec archive add-rate-limit -y --skip-specs   # архівувати без зміни специфікацій

Якщо назву не вказано, archive пропонує вибрати зміну. Поза інтерактивним терміналом команда завершується з кодом 1 і натомість виводить команду для повторного запуску.

Аргументи

Аргумент	Що це
`change-name`	Зміна для архівування за назвою папки (`add-rate-limit`).

Опції

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

Вивід

У разі успіху команда повідомляє статус завдань, показує попередній перегляд оновлень специфікацій, застосовує їх і називає папку архіву:

Task status: ✓ Complete

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

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

З --json --yes:

json

{
  "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 new

Створює каталог нової зміни.

bash

openspec new change add-caching                                # лише метадані
openspec new change add-search --goal "Users can search docs"  # записати мету

new має одну підкоманду, new change <name>. Вона створює openspec/changes/<name>/, що містить єдиний файл метаданих .openspec.yaml:

yaml

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

Артефакти (пропозиція, специфікації, дизайн, завдання) тут не створюються. Ви пишете їх пізніше, а openspec status підказує, який з них наступний.

Аргументи

Аргумент	Що це
`name`	Назва папки для зміни (`add-caching`).

Опції

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

Вивід

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

Якщо каталог openspec/ не знайдено, new change створює його в поточному місці й повідомляє про це:

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

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

Це повідомлення виводиться до stdout разом з іншим призначеним для людини виводом і ніколи не з'являється з --json.

З --json у проєкті, який уже має openspec/:

json

{
  "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:

json

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

Коди виходу

0: зміну створено.
1: зміна вже існує або схема невідома.

openspec status

Показує статус завершення артефактів для однієї зміни або всіх активних змін.

bash

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

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

text

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

Якщо в проєкті немає активних змін, команда status виводить No active changes. Create one with: openspec new change <name> і завершується з кодом 0, навіть якщо жоден із цих прапорців не задано. З --all --json той самий порожній стан має вигляд { "changes": [], "message": "No active changes.", "root": ... }.

Параметри

Прапорець	Дія
`--change <id>`	Зміна, про яку формується звіт, вказується за іменем папки.
`--all`	Звітує про всі активні зміни, відсортовані за іменем. Не можна поєднувати з `--change`.
`--schema <name>`	Перевизначає схему, автоматично визначену з `openspec/config.yaml`. Невідома назва спричиняє помилку.
`--json`	Виводить структурований звіт замість тексту.
`--store <id>`	Використовує зареєстроване сховище як корінь OpenSpec замість поточного проєкту.

Вивід

Контрольний список артефактів схеми: [x] — виконано, [ ] — готовий до запису, [-] — заблокований, доки не з'являться артефакти, від яких він залежить.

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

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

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

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

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

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

Він містить --store <id>, щоразу коли визначеним коренем виявляється сховище, і називає ту саму команду, що й речення nextSteps у JSON.

--json додає залежності кожного артефакта, визначені шляхи до файлів і пропонований наступний крок. Скорочено:

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 для кожної зміни. Вибраний корінь вказується один раз у зовнішньому об'єкті відповіді. Цей приклад скорочує поля статусу кожної зміни, показані вище:

json

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

Якщо одну зі змін не вдається завантажити, пакетна обробка продовжується. Її запис містить changeName і діагностику в полі status, тоді як інші записи залишаються доступними. Команда завершується з кодом 1, зокрема в режимі JSON, тож CI не сприйме неповний звіт як успішний. JSON-вивід залишається одним документом, який можна розібрати.

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

0: усі запитані статуси виведено; порожній звіт --all також завершується з кодом 0.
1: запитану зміну не вдалося завантажити, відсутній --change або --all, обидва прапорці поєднано, зміна не існує або вказано невідому схему.

openspec instructions

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

bash

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

Аргументи

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

Параметри

Прапорець	Дія
`--change <id>`	Зміна, для якої потрібно згенерувати інструкції. Обов'язковий параметр.
`--schema <name>`	Перевизначає схему. В іншому разі визначається автоматично з `config.yaml`.
`--json`	Виводить структурований об'єкт замість тексту.
`--store <id>`	Використовує зареєстроване сховище як корінь OpenSpec замість поточного проєкту.

Вивід

Форма артефакта виводить один блок інструкції: завдання, файл для запису, спосіб його написання, шаблон артефакта та те, що відкривається після його завершення.

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

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

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

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

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

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

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

### Progress
1/3 complete

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

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

No project context or operation guidance configured.

Якщо відсутні потрібні артефакти, apply натомість виводить ### ⚠️ Blocked і перелічує їх. archive виводить назву зміни, а також контекст проєкту та вказівки щодо операцій із конфігурації, якщо вони задані. Якщо нічого не налаштовано, він лише про це й повідомляє.

З --json кожна форма повертає один об'єкт. Форма артефакта починається так:

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 — це номер рядка чекбокса завдання в цьому файлі (нумерація починається з 1).

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

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

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

openspec templates

Виводить розв’язані шляхи до шаблонів для артефактів схеми.

bash

openspec templates          # схема за замовчуванням: spec-driven
openspec templates --json   # мапа ідентифікаторів артефактів до шляхів

Опції

Прапорець	Ефект
`--schema <name>`	Схема для розв’язання. За замовчуванням: `spec-driven`.
`--json`	Вивести JSON-мапу ідентифікаторів артефактів до шляхів шаблонів.

Вихідні дані

Schema: spec-driven
Source: package

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

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

json

{
  "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 schemas

Перелічує доступні робочі схеми.

bash

openspec schemas          # назви, описи, порядок артефактів
openspec schemas --json   # машиночитаний формат, для використання агентами

Опції

Прапорець	Ефект
`--json`	Вивести у форматі JSON (для використання агентами).

Вихідні дані

Available schemas:

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

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

json

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

Коди виходу

0: схеми перелічено.
1: не вдалося прочитати список схем.

openspec schema

Перевіряє, копіює або створює схему (експериментально). Кожен підкоманда спочатку виводить Note: Schema commands are experimental and may change. у стермінaль.

bash

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

Subcommand	What it does
`which`	Показати, від якої схеми розв’язується.
`validate`	Перевірити структуру схеми та шаблони.
`fork`	Копіювати існуючу схему у проект для кастомізації.
`init`	Створювати нову схему, локальну для проекту.

Схеми розв’язуються з трьох джерел. Перший збіг виграє:

Source	Location
`project`	`openspec/schemas/` у поточному проекті.
`user`	`~/.local/share/openspec/schemas/` (`XDG_DATA_HOME` та `%LOCALAPPDATA%` Windows урахуються).
`package`	Схеми, що йдуть з CLI. `spec-driven` знаходиться тут.

openspec schema which

Показує, яку копію схеми використає CLI.

bash

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

Arguments

Argument	What it is
`name`	Схема, яку треба знайти. Обов’язкова, якщо не задано `--all`. Без одного з них `which` повертає код 1.

Options

Flag	Effect
`--all`	Перелістити всі схеми з їхнім джерелом розв’язку.
`--json`	Вивести розв’язок у форматі JSON.

Output

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

Коли вища-priority копія приховує іншу, розділ Shadows: перелічує приховані копії. При використанні --json:

json

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

An unknown name exits 1 and lists the available schemas.

openspec schema validate

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

bash

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 не може визначити, до якої артефактної прогресує файл.

Options

Flag	Effect
`--json`	Вивести структурований звіт замість тексту.
`--verbose`	Вивести кожен крок валідації.

Output

✓ Schema 'spec-driven' is valid

With no name, each project schema gets one line under a Validation Results: header. A failing schema lists its issues and the run exits 1:

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

Options

Flag	Effect
`--json`	Вивести результат у форматі JSON.
`--verbose`	Вивести кожен крок валідації.

openspec schema fork

Копіює існуючу схему у проект для кастомізації.

bash

openspec schema fork spec-driven my-flow

Arguments

Argument	What it is
`source`	Схема, яку треба скопіювати, з будь-якого джерела.
`name`	Ім'я для копії. Kebab-case (`my-workflow`). За замовчуванням: `<source>-custom`.

Options

Flag	Effect
`--force`	Замінити існуючу цільову схему.
`--json`	Вивести результат у форматі JSON.

Output

✔ 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

An existing destination is an error unless you pass --force. A fork that keeps the source's name shadows the original.

openspec schema init

Створює нову схему, локальну для проекту, з шаблонами-стастерами.

bash

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

Без --description та без --artifacts у інтерактивному терміналі init запитує опис, список артефактів та запитує, чи робити схему за замовчуванням для проекту. За Outside з терміналом використовуються зазначені нижче значення за замовчуванням.

Arguments

Argument	What it is
`name`	Ім'я для нової схеми. Kebab-case (`my-workflow`).

Options

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

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

Output

✔ Created schema 'my-schema'

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

Artifacts: proposal, tasks

schema.yaml підключає вибрані артефакти до їхніх залежностей. Коли tasks включено, він також отримує фазу apply, яка відстежує tasks.md. Використовуйте схему за допомогою openspec new --schema my-schema.

openspec store

Створює та управляє магазинами: окремими OpenSpec‑репозиторіями, зареєстрованими на вашій машині.

bash

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 і виводить список підкоманд.

Subcommand	What it does
`setup [id]`	Створює папку магазину та реєструє її.
`register [path]`	Реєструє існуючу папку магазину.
`unregister <id>`	Забуває реєстрації. Папка залишається на диску.
`remove <id>`	Забуває реєстрацію та видаляє папку.
`list` (alias `ls`)	Перелістати зареєстровані магазини.
`doctor [id]`	Перевіряє реєстрацію, метадані та стан Git для зареєстрованих магазинів.

openspec store setup

Створює папку магазину та реєструє її.

bash

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

У інтерактивному терміналі setup запитує відсутнє ім'я та місце та підтверджує перед створенням чогось. За Outside з терміналом відсутнє ім'я або --path завершується кодом 1 з прапоримою, яку треба передати. Повторне виконання setup для зареєстрованого магазину повідомляє Registry: already registered.

Arguments

Argument	What it is
`id`	Ім'я магазину. Воно стає id, яким ви передаєте `--store`.

Options

Flag	Effect
`--path <path>`	Папка, в якій має знаходитися магазин (`~` розгортається).
`--init-git`	Ініціалізує Git‑репозиторій з першим комітомом. За замовчуванням.
`--no-init-git`	Пропускає всі дії Git: ініціалізацію, перший коміт.
`--remote <url>`	Канонічний джерело клону, записане в `store.yaml`.

Output

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 reports what was created and where it was registered:

json

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

openspec store register

Реєструє існуючу папку магазину, наприклад, чек‑аут, який ви склонували.

bash

openspec store register ~/stores/design-system

Папка повинна містити здоровий openspec/ корінь. При Current .openspec-store/store.yaml present, register перевикористовує записане ідентифікатор. Без нього register запитує перед створенням метаданих. За Outside з інтерактивного терміналу передайте --yes замість цього. На машині може реєструватися один чек‑аут на кожну ідентифікацію магазину. Друга шляха під тим же id або та ж шляха під іншим id викликає помилку 1.

Arguments

Argument	What it is
`path`	Папка магазину, яку треба реєструвати (`~` розгортається). Обов’язкова.

Options

Flag	Effect
`--id <id>`	Ідентифікатор магазину. За замовчуванням береться з метаданих або назви папки.
`--yes`	Підтверджує створення метаданих ідентичності магазину для здорового коріня OpenSpec.

Output

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

--json prints the same document shape as store setup --json.

openspec store unregister

Забуває реєстрацію. Папка залишається на диску.

bash

openspec store unregister design-system

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

Output

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

openspec store remove

Забуває реєстрацію та видаляє папку.

bash

openspec store remove design-system --yes

Інтерактивно, remove запитує підтвердження перед видаленням. При використанні --json або за Outside з інтерактивного терміналу видалення вимагає --yes:

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

Options

Flag	Effect
`--yes`	Підтверджує видалення локальної папки магазину.

Output

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

openspec store list

Перелістає зареєстровані магазини. ls — псевдонім.

bash

openspec store list

Магазини OpenSpec (2)

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

With nothing registered, list prints No stores registered. and the setup and register commands to run next.

openspec store doctor

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

bash

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

Output

Доктор магазину

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

Exit codes

0: звіт виводиться, навіть якщо магазин повідомляє проблеми.
1: звіт не вдалося вивести (наприклад, невідомий id магазину).

openspec doctor

Світовує стан зв’язків для визначеного кореня OpenSpec.

bash

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

Doctor є реалізацією лише для читання: він ніколи не клонує, не синхронізує та не ремонтуює. Він звітуює, чи є корінь здоровим, та чи кожна посилання, задеклароване в openspec/config.yaml, розв’язується на цьому комп’ютері. Якщо вище вашого cwd немає кореня і не вказано --store, завершується з кодом 1 і називає ваші зареєстровані сховища.

Параметри

Прапор	Ефект
`--store <id>`	Використовує зареєстроване сховище як корінь OpenSpec замість поточного проєкту.
`--json`	Виводить звіт про стан у форматі JSON.

Вивід

Doctor

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

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

З параметром --store корінь є сховищем, а звіт додає рядок сховища:

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

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

References
  (none declared)

json

{
  "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: корінь не розв’язано (вище вашого cwd немає openspec/ і не вказано --store) або невідомий ідентифікатор --store.

openspec context

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

bash

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

Посилання, які не розв’язуються на цьому комп’ютері, потрапляють до розділу Not available on this machine, кожен із виправленням.

Параметри

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

Вивід

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

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

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

З параметром --store сховище є всім набором:

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

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

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

json

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

Запис файла робочої області

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

json

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

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

0: звіт виведено.
1: корінь не розв’язано (вище вашого cwd немає openspec/ і не вказано --store) або запис --code-workspace відхилено.

openspec workset

Створює, зберігає та відкриває персональні робочі представлення. Workset — це збережений іменований список папок, з якими ви працюєте разом.

bash

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

Підкоманда	Що робить
`create [name]`	Створює та зберігає іменоване робоче представлення вибраних папок.
`list`, `ls`	Показує збережені workset'и з їхніми учасниками.
`open <name>`	Відкриває збережений workset у вашому інструменті (вікно редактора або сесія агента).
`remove <name>`	Видаляє збережений workset (папки-учасники не змінюються).

Workset суто локальний:

Його стан зберігається в одній папці: ~/.local/share/openspec/worksets/ ($XDG_DATA_HOME/openspec/worksets/ при встановленні; %LOCALAPPDATA%\openspec\worksets\ на Windows).
У папки-учасники нічого не записується, нічого не фіксується та не поширюється.
Видалення цієї однієї папки видаляє всі сліди.

openspec workset create

Зберігає іменоване робоче представлення папок.

bash

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

В інтерактивному терміналі create запитує все, чого не надали прапорці: назву, папки по черзі, інструмент, а потім пропонує відкрити workset зараз. Поза ним відсутня назва або учасник є помилкою. Назва, яка вже збережена, завжди є помилкою. Спочатку видаліть її.

Аргументи

Аргумент	Що це
`name`	Назва workset'у. Kebab-case: малі літери, цифри, одиничні дефіси. Обов'язково поза інтерактивним терміналом.

Опції

Прапорець	Ефект
`--member <member>`	Папка-учасник як `<path>` або `<name>=<path>`, можна повторювати. Перша є основною. Шлях має бути існуючою папкою, а мітка за замовчуванням — власна назва папки.
`--tool <id>`	Бажаний інструмент для відкриття цього workset'у. Вбудовані ідентифікатори: `code` (VS Code), `cursor` (Cursor). `claude` та `codex` тимчасово вимкнені.
`--json`	Вивести збережений workset у форматі JSON.

Вивід

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

openspec workset list

Показує збережені workset'и з їхніми учасниками, відсортовані за назвою.

bash

openspec workset list   # alias: ls

Опції

Прапорець	Ефект
`--json`	Вивести workset'и у форматі JSON.

Вивід

Один блок на кожен workset: назва, інструмент (якщо є), а потім по одному рядку name path на кожного учасника. Якщо нічого не збережено, list виводить No worksets saved. Create one with: openspec workset create.

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

З --json:

json

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

openspec workset open

Відкриває збережений workset у вашому інструменті. Інструменти-редактори (code, cursor) отримують згенерований файл .code-workspace. Вікно відкривається, і команда повертає керування. CLI-інструменти агентів (claude, codex) перебрали б цей термінал з підключеними всіма учасниками. Вони тимчасово вимкнені, поки цей процес переробляється, тож зараз workset'и відкриваються в IDE.

bash

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

Аргументи

Аргумент	Що це
`name`	Workset для відкриття.

Опції

Прапорець	Ефект
`--tool <id>`	Відкрити цим інструментом лише цього разу.

Без --tool та без збереженого інструменту open запитує вибір встановленого інструменту. Поза інтерактивним терміналом він завершується з кодом 1.

Папка-учасник, яка більше не існує, пропускається з попередженням. Коли основна відсутня, наступний наявний учасник стає основним для цього відкриття. Коли жодна папка-учасник не існує, відкриття завершується невдачею.
--json відхиляється: open передає термінал інструменту і не має JSON-режиму.
Коли запуск не вдається, помилка завершується ручним способом: шлях до файлу workspace та список учасників.

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

Дзеркалить інструмент: команда завершується з власним кодом завершення інструменту, а сигнал стає 128+n (130 після Ctrl-C).
1: невідомий workset, немає доступної папки-учасника або немає придатного інструменту.

openspec workset remove

Видаляє збережений workset та його згенерований файл .code-workspace. Папки-учасники не змінюються.

bash

openspec workset remove checkout --yes

В інтерактивному терміналі remove показує workset і запитує підтвердження. З --json або поза терміналом він потребує --yes і завершується з кодом 1 без нього.

Опції

Прапорець	Ефект
`--yes`	Підтвердити видалення неінтерактивно.
`--json`	Вивести видалення у форматі JSON.

Вивід

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

openspec version

Повідомляє версію запущеного OpenSpec та спосіб встановлення цієї копії.

bash

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 залишається найкоротшою формою та виводить лише простий номер версії.

Опції

Прапорець	Ефект
`--json`	Вивести один версійований JSON-документ замість тексту.
`--check`	Перевірити налаштований реєстр на наявність новішого релізу.

Вивід

Для глобального встановлення npm:

text

OpenSpec 1.13.2 (npm, global)

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

--json зберігає невідомі деталі як явні значення null:

json

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

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

text

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

json

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

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

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

Для автономного встановлення команда оновлення — openspec install.

DO_NOT_TRACK, відмови від телеметрії, OPENSPEC_NO_UPDATE_CHECK, визначення CI та відхилені не-HTTPS перевизначення реєстру вимикають перевірку. Вимкнені та офлайн-перевірки все одно завершуються з кодом 0, оскільки доступність оновлень є рекомендаційною. Ця команда ніколи не оновлює OpenSpec; canSelfUpgrade лише повідомляє, чи існуючий шлях openspec update може безпечно оновити цю копію.

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

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

openspec install

Встановлює автономну версію openspec. Запустіть цю команду з інсталяції npm або Homebrew, щоб перемкнутися, або з автономної інсталяції, щоб оновити її на місці.

bash

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, продовжує запускатися, доки ви її не видалите.

Аргументи

Аргумент	Що це
`version`	Реліз для встановлення, наприклад `1.15.0`. Необов’язковий; за замовчуванням — найновіший.

OPENSPEC_INSTALL_DIR і OPENSPEC_INSTALL_NAME вибирають інший каталог або ім’я файлу.

Коди виходу

0: встановлено.
1: версія не є версією релізу, або не вдалося завантажити чи встановити. Ваша поточна копія залишається без змін.

openspec feedback

Надсилає відгук про OpenSpec.

bash

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

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

Аргументи

Аргумент	Що це
`message`	Однорядкове резюме. Стає заголовком issue. Обов’язковий.

Опції

Прапорець	Ефект
`--body <text>`	Довший опис, що додається до тіла issue.

Вивід

У разі успіху:

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

Якщо gh не встановлено або ви не ввійшли в gh, нічого не надсилається. CLI виводить ваш відформатований відгук між маркерами --- FORMATTED FEEDBACK ---, а потім посилання, яке відкриває форму звіту про баг із заповненими заголовком, полем «що сталося» (ваше повідомлення й текст --body), версією CLI та середовищем (платформа й версія Node). Решту форми ви заповнюєте в браузері. У сценарії без входу додається To auto-submit in the future: gh auth login.

Коди виходу

0: issue створено або запущено резервний варіант ручного надсилання (немає gh або ви не ввійшли в gh).
1: повідомлення не надано.
власний код gh: gh завершився з помилкою після автентифікації (мережа, обмеження частоти запитів, вимкнено Issues). CLI спершу повторно виводить ваш відгук і URL для ручного надсилання.

openspec completion

Встановлює або генерує доповнення для оболонки.

bash

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

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

Підкоманда	Що робить
`generate [shell]`	Виводить скрипт доповнення у stdout.
`install [shell]`	Записує скрипт і налаштовує файл запуску вашої оболонки.
`uninstall [shell]`	Видаляє скрипт і блок конфігурації.

Якщо встановлено через Nix, доповнення вже на місці: flake-пакет постачає скрипти Bash, Fish і Zsh у стандартних розташуваннях, тому install не потрібен (Встановлення).

openspec completion generate

Виводить скрипт і нічого не записує.

#compdef openspec

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

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

openspec completion install

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

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

Якщо встановлено Oh My Zsh, скрипт натомість потрапляє в $ZSH_CUSTOM/completions/_openspec (типово ~/.oh-my-zsh/custom/completions/_openspec).

Відносний ZDOTDIR або ZDOTDIR із префіксом ~ ігнорується, і натомість редагується ~/.zshrc. Повторний запуск команди встановлення, коли скрипт уже актуальний, усе одно додає блок до .zshrc, який читає zsh.

Опції

Прапорець	Ефект
`--verbose`	Також виводить шлях встановлення, шлях резервної копії (якщо є) і який конфігураційний файл було відредаговано.

Вивід

✓ Completion script installed and .zshrc configured successfully

Restart your shell or run: exec zsh

openspec completion uninstall

Видаляє скрипт і позначений блок конфігурації. Перед зміненням конфігурації запитує підтвердження (за замовчуванням: Ні).

Для zsh він очищує .zshrc, який редагує команда встановлення, а також ~/.zshrc, якщо старіша інсталяція залишила там блок для ZDOTDIR. Якщо блок не вдається видалити, команда видалення називає файл і завершується з кодом 1.

Опції

Прапорець	Ефект
`-y, --yes`	Пропускати запити підтвердження.

Вивід

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

Коди виходу

0: скрипт згенеровано, встановлено або видалено. Скасоване видалення також завершується з кодом 0.
1: оболонка не підтримується або не визначена, чи крок встановлення або видалення завершився невдало.

openspec change

Застаріла іменникова форма команд show, list і validate. Під час кожного запуску виводиться попередження й вказівка на команди з дієсловом на початку, після чого команда все одно виконується:

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

Застаріла команда	Використовуйте натомість
`openspec change show <name>`	`openspec show <name>`
`openspec change list`	`openspec list`
`openspec change validate <name>`	`openspec validate <name>` (усі зміни: `openspec validate --changes`)

Прапорці описано в розділах про команди з дієсловом на початку.

openspec spec

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

Застаріла команда	Використовуйте натомість
`openspec spec show <id>`	`openspec show <id>`
`openspec spec list`	`openspec list --specs`
`openspec spec validate <id>`	`openspec validate <id>` (усі специфікації: `openspec validate --specs`)

Прапорці описано в розділах про команди з дієсловом на початку.

CLI ​

Команди ​

openspec init ​

openspec update ​

openspec config ​

openspec config path ​

openspec config list ​

openspec config get ​

openspec config set ​

openspec config unset ​

openspec config reset ​

openspec config edit ​

openspec config profile ​

openspec list ​

openspec show ​

openspec view ​

openspec validate ​

--report full|findings ​

Текстовий вивід знахідок ​

JSON-вивід знахідок ​

Неприпустимі запити звіту ​

Зовнішня фільтрація повного звіту ​

openspec archive ​

openspec new ​

openspec status ​

openspec instructions ​

openspec templates ​

openspec schemas ​

openspec schema ​

openspec schema which ​

openspec schema validate ​

openspec schema fork ​

openspec schema init ​

openspec store ​

openspec store setup ​

openspec store register ​

openspec store unregister ​

openspec store remove ​

openspec store list ​

openspec store doctor ​

openspec doctor ​

openspec context ​

openspec workset ​

openspec workset create ​

openspec workset list ​

openspec workset open ​

openspec workset remove ​

openspec version ​

openspec install ​

openspec feedback ​

openspec completion ​

openspec completion generate ​

openspec completion install ​

openspec completion uninstall ​

openspec change ​

openspec spec ​

CLI

Команди

openspec init

openspec update

openspec config

openspec config path

openspec config list

openspec config get

openspec config set

openspec config unset

openspec config reset

openspec config edit

openspec config profile

openspec list

openspec show

openspec view

openspec validate

--report full|findings

Текстовий вивід знахідок

JSON-вивід знахідок

Неприпустимі запити звіту

Зовнішня фільтрація повного звіту

openspec archive

openspec new

openspec status

openspec instructions

openspec templates

openspec schemas

openspec schema

openspec schema which

openspec schema validate

openspec schema fork

openspec schema init

openspec store

openspec store setup

openspec store register

openspec store unregister

openspec store remove

openspec store list

openspec store doctor

openspec doctor

openspec context

openspec workset

openspec workset create

openspec workset list

openspec workset open

openspec workset remove

openspec version

openspec install

openspec feedback

openspec completion

openspec completion generate

openspec completion install

openspec completion uninstall

openspec change

openspec spec