Skip to content

Довідник CLI ​

CLI OpenSpec (openspec) надає термінальні команди для налаштування проєкту, валідації, перевірки статусу та керування. Ці команди доповнюють AI слеш-команди (наприклад, /opsx:propose), описані в Команди.

Огляд ​

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

Команди для людини та для агента ​

Більшість команд CLI призначені для використання людиною в терміналі. Деякі команди також підтримують використання агентом/скриптами через вивід у форматі JSON.

Команди лише для людини ​

Ці команди інтерактивні та призначені для використання в терміналі:

КомандаПризначення
openspec initІніціалізувати проект (інтерактивні підказки)
openspec viewІнтерактивна інформаційна панель
openspec workset open <name>Відкрити збережений робочий набір (вікно редактора або сеанс термінального агента)
openspec config editВідкрити конфігурацію в редакторі
openspec feedbackНадіслати відгук через GitHub
openspec completion installВстановити автодоповнення для оболонки

Команди, сумісні з агентами ​

Ці команди підтримують вивід --json для програмного використання агентами ШІ та скриптами:

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

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

Ці параметри працюють з усіма командами:

ПараметрОпис
--version, -VПоказати номер версії
--no-colorВимкнути кольоровий вивід
--help, -hПоказати довідку для команди

Команди налаштування ​

openspec init ​

Ініціалізувати OpenSpec у вашому проекті. Створює структуру папок та налаштовує інтеграцію з інструментами ШІ.

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

openspec init [path] [options]

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

Аргументи:

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

Параметри:

ПараметрОпис
--tools <list>Налаштувати інструменти ШІ без інтерактивного режиму. Використовуйте all, none або список, розділений комами
--language <language>Записувати артефакти цією мовою при створенні нової конфігурації
--forceАвтоматично очищати застарілі файли без підтвердження
--profile <profile>Перевизначити глобальний профіль для цього запуску ініціалізації (core або custom)
--no-animationПоказати статичний екран привітання замість анімованого
--copilot-cloudНалаштувати GitHub Copilot файли хмарного агента кодування без підтвердження
--no-copilot-cloudПропустити налаштування файлів хмарного агента кодування GitHub Copilot без підтвердження

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

Анімація привітання також пропускається, якщо встановлено змінну середовища OPENSPEC_NO_ANIMATION (будь-яке значення, включаючи порожнє), якщо NO_COLOR встановлено в непорожнє значення, або якщо ввімкнено налаштування зменшення руху в ОС (macOS Reduce Motion, вимкнені анімації GNOME).

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

Цей список відповідає AI_TOOLS у src/core/config.ts. Див. Підтримувані інструменти для шляхів навичок та команд кожного інструменту.

Приклади:

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

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

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

# Неінтерактивно: налаштувати глобальні навички MiniMax Code
openspec init --tools minimax-code

# Налаштувати для всіх підтримуваних інструментів
openspec init --tools all

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

# Пропустити підказки та автоматично очистити застарілі файли
openspec init --force

Що створюється:

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

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

openspec update ​

Оновити файли інструкцій OpenSpec після оновлення CLI. Перегенерувати файли конфігурації інструментів ШІ, використовуючи ваш поточний глобальний профіль, вибрані робочі процеси та режим доставки.

openspec update [path] [options]

Аргументи:

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

Параметри:

ПараметрОпис
--forceПримусове оновлення, навіть якщо файли вже актуальні

Приклад:

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

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

Щоб це було видно, openspec update запитує реєстр npm, чи була опублікована новіша версія CLI. Якщо ваша версія відстає, пропонується оновлення:

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

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

Пропозиція з'являється лише в інтерактивному терміналі і лише тоді, коли npm володіє встановленням — єдиний випадок, який справді виправляє npm install -g. Для всього іншого виводиться команда, яка відповідає способу встановлення:

Як встановлено OpenSpecЩо ви отримуєте
Глобальне встановлення npmЗапит та запуск оновлення — в інтерактивному терміналі; при перенаправленому виводі виводиться лише команда
Глобальне встановлення pnpm, bun, yarn або voltaВласна команда менеджера: pnpm add -g …@latest, bun add -g …@latest, yarn global add …@latest або volta install …@latest
Залежність проектуПовідомлення про оновлення залежності, оскільки її менеджер пакетів володіє lock-файлом
Кеш npx / dlxnpx @fission-ai/openspec@latest update — ця команда і є оновленням, тому другого кроку немає
Клон gitНічого — ваша версія визначається гілкою

Коли щось виводиться, вказується директорія, з якої було завантажено запущений CLI — місце, яке слід перевірити, якщо ви оновилися, але застарілий проксі все ще володіє вашим PATH.

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

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


Сховища (окремі репозиторії OpenSpec) ​

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

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

openspec store setup ​

Створення та реєстрація локального сховища. Без аргументів у терміналі OpenSpec веде користувача через процес налаштування. Агенти та скрипти повинні передавати явні вхідні дані та використовувати --json.

bash
openspec store setup [id] [options]

Параметри:

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

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

Приклади:

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

openspec store register ​

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

bash
openspec store register [path] [options]

Параметри:

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

openspec store unregister ​

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

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

Використовуйте це, коли сховище було переміщене, клоноване в інше місце або більше не повинно відображатися OpenSpec на цьому комп'ютері.

openspec store remove ​

Видалитi локальну реєстрацію сховища та видалити його локальну папку.

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

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

openspec store list ​

Перелічити локально зареєстровані сховища.

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

openspec store doctor ​

Перевірити локальну реєстрацію сховища, метадані та наявність Git.

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

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

Посилання на сховища з проекту ​

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

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

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

Посилання — це контекст лише для читання. Вони ніколи не змінюють місце, де виконуються команди: робота залишається у власному корені репозиторію, а запис у посилане сховище залишається явним дією --store. Посилання, яке не може бути розв'язане (наприклад, сховище не зареєстроване на цьому комп'ютері), перетворюється на попередження в індексі з точним виправленням, а інструкції все одно генеруються. openspec doctor звітує про стан посилань у одному місці.

Запис джерела клонування сховища ​

Сховище може записати своє канонічне джерело клонування у свій закомічений файл ідентичності, щоб онбординг ніколи не застрягав на етапі «зареєструйте сховище»:

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

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

Оголошення посилання також може містити джерело клонування, щоб колега, який ще не має сховища, отримав повне, готове до вставлення виправлення (git clone <remote> <path> && openspec store register <path> --id <id>):

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

Запис віддаленої адреси — це не синхронізація: OpenSpec ніколи не клонує, не тягне та не штовхає самостійно.

Оголошення сховища за замовчуванням ​

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

yaml
# openspec/config.yaml (єдиний файл під openspec/)
store: team-context

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

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

Doctor (здоров'я зв'язків) ​

Одне запитання лише для читання, одне місце: чи є корінь OpenSpec здоровим, і чи доступні сховища (stores), на які він посилається, на цій машині?

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

Звіт розділяє здоров'я кореня, здоров'я метаданих сховища (включно з приміткою, коли записаний віддалений репозиторій і походження checkout розходяться, а також приміткою, коли checkout сховища відстав від свого останнього отриманого upstream-tracking ref), та здоров'я посилань (ті самі діагностичні інструкції, що показує show, з виправленнями клонування для нерозв'язаних посилань). Знахідки про здоров'я будь-якої серйозності завершуються кодом 0 — агенти читають масиви status; лише помилки команд (відсутній корінь, невідоме сховище) завершуються кодом 1. Doctor ніколи не клонує, не синхронізує та не ремонтує. Щоб отримати саму зібрану множину, а не її здоров'я, використовуйте openspec context.

Робочий контекст (зібрана множина) ​

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

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

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

«Робочий контекст» — це зібрана множина; поле context: у openspec/config.yaml — це проектний контекст, впроваджений в інструкції — дві різні речі. openspec doctor відповідає, чи множина здорова; openspec context відповідає, чим є множина.

Персональні робочі набори (worksets) ​

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

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

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

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

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

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

Увесь стан workset зберігається в папці worksets/ глобального каталогу даних (збережені погляди плюс згенеровані файли <name>.code-workspace, які перегенеруються при кожному відкритті); видалення цієї папки видаляє всі сліди.


Команди перегляду ​

openspec list ​

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

openspec list [options]

Опції:

ОпціяОпис
--specsПерелічити специфікації замість змін
--changesПерелічити зміни (за замовчуванням)
--sort <order>Сортувати за recent (за замовчуванням) або name
--jsonВивести у форматі JSON

Приклади:

bash
# Перелічити всі активні зміни
openspec list

# Перелічити всі специфікації
openspec list --specs

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

Вивід (текст):

Changes:
  add-dark-mode     No tasks      just now

openspec view ​

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

openspec view

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


openspec show ​

Показати деталі зміни або специфікації.

openspec show [item-name] [options]

Аргументи:

АргументОбов'язковийОпис
item-nameНіНазва зміни або специфікації (запитує, якщо пропущено)

Опції:

ОпціяОпис
--type <type>Вказати тип: change або spec (автовизначається, якщо неоднозначно)
--jsonВивести у форматі JSON
--no-interactiveВимкнути запити

Опції, специфічні для змін:

ОпціяОпис
--deltas-onlyПоказати лише delta-специфікації (режим JSON)

Опції, специфічні для специфікацій:

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

Приклади:

bash
# Інтерактивний вибір
openspec show

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

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

# JSON-вивід для парсингу
openspec show add-dark-mode --json

Команди валідації ​

openspec validate ​

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

openspec validate [item-name] [options]

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

Аргументи:

АргументОбов’язковийОпис
item-nameНіКонкретний елемент для валідації (якщо не вказано — буде запропоновано вибрати)

Опції:

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

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

Приклади:

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

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

# Перевірити всі зміни
openspec validate --changes

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

# Сувора валідація зі збільшеним паралелізмом
openspec validate --all --strict --concurrency 12

# Помилка, якщо будь-яка архівована зміна все ще має непозначені завдання
openspec validate --archived

Вивід (текст):

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

1 warning found

Вивід (JSON):

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

Команди життєвого циклу ​

openspec archive ​

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

openspec archive [change-name] [options]

Аргументи:

АргументОбов’язковийОпис
change-nameНіНазва зміни для архівації (якщо не вказано — буде запропоновано вибрати; обов’язковий, коли підказка не може бути оброблена)

Опції:

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

Приклади:

bash
# Інтерактивна архівація (запитує, яку зміну, потім підтверджує)
openspec archive

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

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

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

Вивести можливість з експлуатації: Додайте маркер виведення до метаданих зміни:

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

Потім архівуйте зміну звичайним чином:

bash
openspec archive retire-legacy --yes

Коли зміна видаляє останню вимогу можливості, OpenSpec видаляє її живий spec.md. Інші дельти можливостей у тій самій зміні все одно оновлюють свої основні специфікації. Без маркера архівація зупиняється перед зміною будь-яких файлів і повідомляє, що його потрібно додати.

Що вона робить:

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

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

Команди робочого процесу ​

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

openspec new change ​

Створює каталог зміни та необов'язкові метадані, що перевірені, у визначеному кореневому каталозі OpenSpec.

bash
openspec new change <name> [options]

Імена змін повинні використовувати нижній регістр у форматі kebab-case: малі літери, цифри та одинарні дефіси. Вони не можуть містити пробіли, підкреслення, великі літери, послідовні дефіси або дефіси на початку/кінці. Початкова цифра дозволяється, тому ви можете додавати префікси для впорядкування або розподілу змін за рівнями, наприклад 100-add-feature або 00001-add-auth.

Параметри:

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

Приклади:

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

openspec status ​

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

openspec status [options]

Параметри:

ПараметрОпис
--change <id>Ім'я зміни (запитує, якщо не вказано)
--schema <name>Перевизначення схеми (визначається автоматично з конфігурації зміни)
--jsonВивести як JSON

Приклади:

bash
# Інтерактивна перевірка стану
openspec status

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

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

Вивід (текст):

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

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

Зміна, яка оголошує skip_specs: true, відображає свій етап специфікацій як [~] specs (skipped: change declares skip_specs) та виключає його з підрахунку прогресу.

Вивід (JSON):

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

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

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


openspec instructions ​

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

openspec instructions [artifact] [options]

Аргументи:

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

Параметри:

ПараметрОпис
--change <id>Ім'я зміни (обов'язковий у неінтерактивному режимі)
--schema <name>Перевизначення схеми
--jsonВивести як JSON

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

Приклади:

bash
# Отримати інструкції для наступного артефакта
openspec instructions --change add-dark-mode

# Отримати інструкції для конкретного артефакта
openspec instructions design --change add-dark-mode

# Отримати інструкції для застосування/реалізації
openspec instructions apply --change add-dark-mode

# Отримати поточні вхідні дані операції архівування без архівування
openspec instructions archive --change add-dark-mode --json

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

Вивід містить:

  • Шаблонний вміст для артефакта
  • Контекст проєкту з конфігурації
  • Вміст із залежних артефактів
  • Правила для кожного артефакта з конфігурації
  • Поточний контекст проєкту та відповідні рекомендації операції для apply/archive

Вхідні дані операції читаються з визначеного репозиторію або вибраного сховища при кожному виклику. Контекст проєкту — обов'язковий вхідний параметр рівня запиту: агенти читають його та застосовують відповідні факти проєкту, конвенції та обмеження. Рекомендації операції — необов'язкова додаткова порада: агенти розглядають кожен запис і дотримуються лише записів, які є застосовними та сумісними зі вбудованим робочим процесом. Обидва поля залишаються окремими від явних виборів користувача, стану, що керується CLI, вбудованих інструкцій та правил артефактів. Конфліктний контекст повідомляється; конфліктні або незастосовні рекомендації не виконуються, і пояснюється причина. Це поведінкові договори для згенерованих агентів, а не примусові перевірки CLI. instructions archive повертає лише вибрану зміну, необов'язкові вхідні дані та кореневі метадані; він не включає статичний робочий процес архівування.

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


openspec templates ​

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

openspec templates [options]

Параметри:

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

Приклади:

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

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

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

Вивід (текст):

Schema: spec-driven

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

openspec schemas ​

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

openspec schemas [options]

Параметри:

ПараметрОпис
--jsonВивести як JSON
--store <id>Використати зареєстроване сховище як кореневий каталог OpenSpec

Приклад:

bash
openspec schemas

Вивід:

Available schemas:

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

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

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

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

openspec schema init ​

Створити нову схему локально для проєкту.

openspec schema init <name> [options]

Аргументи:

АргументОбов'язковийОпис
nameТакНазва схеми (kebab-case)

Опції:

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

Приклади:

bash
# Інтерактивне створення схеми
openspec schema init research-first

# Неінтерактивне створення з певними артефактами
openspec schema init rapid \
  --description "Робочий процес швидкої ітерації" \
  --artifacts "proposal,tasks" \
  --default

Що створюється:

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

openspec schema fork ​

Скопіювати наявну схему до свого проєкту для налаштування.

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

Аргументи:

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

Опції:

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

Приклад:

bash
# Форк вбудованої схеми spec-driven
openspec schema fork spec-driven my-workflow

openspec schema validate ​

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

openspec schema validate [name] [options]

Аргументи:

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

Опції:

ОпціяОпис
--verboseПоказати детальні кроки перевірки
--jsonВивести результат у форматі JSON

Приклад:

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

# Перевірити всі схеми
openspec schema validate

openspec schema which ​

Показати, звідки береться схема (корисно для налагодження пріоритету).

openspec schema which [name] [options]

Аргументи:

АргументОбов'язковийОпис
nameНіНазва схеми

Опції:

ОпціяОпис
--allПоказати всі схеми та їхні джерела
--jsonВивести результат у форматі JSON

Приклад:

bash
# Перевірити, звідки береться схема
openspec schema which spec-driven

Вивід:

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

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

  1. Проєкт: openspec/schemas/<name>/
  2. Користувач: ~/.local/share/openspec/schemas/<name>/
  3. Пакет: вбудовані схеми

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

openspec config ​

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

openspec config <subcommand> [options]

Підкоманди:

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

Приклади:

bash
# Показати шлях до файлу конфігурації
openspec config path

# Показати всі налаштування
openspec config list

# Отримати конкретне значення
openspec config get telemetry.enabled

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

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

# Видалити користувацьке налаштування
openspec config unset user.name

# Встановити сховище за замовчуванням на рівні машини (резервний корінь, коли немає --store,
# локального кореня або сховища проєкту: вирішує покажчик)
openspec config set defaultStore team-plans

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

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

# Налаштувати профіль за допомогою майстра на основі дій
openspec config profile

# Швидкий пресет: перемкнути робочі процеси на core (зберігає режим доставки)
openspec config profile core

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

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

  • Змінити доставку та робочі процеси
  • Змінити лише доставку
  • Змінити лише робочі процеси
  • Зберегти поточні налаштування (вихід)

Якщо зберегти поточні налаштування, жодних змін не записується і не показується запит на оновлення. Якщо конфігурація не змінюється, але поточні файли проєкту не синхронізовані з глобальним профілем/доставкою, OpenSpec покаже попередження та запропонує openspec update. Натискання Ctrl+C також скасовує процес коректно (без стек-трейсу) і завершується з кодом 130. У контрольному списку робочих процесів [x] означає, що робочий процес вибрано в глобальній конфігурації. Щоб застосувати ці вибори до файлів проєкту, запустіть openspec update (або виберіть «Застосувати зміни до цього проєкту зараз?», коли з'явиться запит у проєкті).

Інтерактивні приклади:

bash
# Оновлення лише доставки
openspec config profile
# виберіть: Змінити лише доставку
# виберіть доставку: Лише навички (Skills only)

# Оновлення лише робочих процесів
openspec config profile
# виберіть: Змінити лише робочі процеси
# перемкніть робочі процеси в контрольному списку, потім підтвердіть

Команди утиліт ​

openspec feedback ​

Надіслати відгук про OpenSpec. Створює issue на GitHub.

openspec feedback <message> [options]

Аргументи:

АргументОбов'язковийОпис
messageТакКороткий опис відгуку; довгий текст скорочується в назві issue та зберігається в тілі

Опції:

ОпціяОпис
--body <text>Додаткові деталі, що включаються після короткого опису

Вимоги: GitHub CLI (gh) має бути встановлений та автентифікований.

Приклад:

bash
openspec feedback "Додати підтримку користувацьких типів артефактів" \
  --body "Я хочу визначати власні типи артефактів, окрім вбудованих."

openspec completion ​

Керування завершенням команд для CLI OpenSpec.

openspec completion <subcommand> [shell]

Підкоманди:

ПідкомандаОпис
generate [shell]Вивести скрипт завершення у stdout
install [shell]Встановити завершення для вашої оболонки
uninstall [shell]Видалити встановлені завершення

Підтримувані оболонки: bash, zsh, fish, powershell

Приклади:

bash
# Встановити завершення (автоматичне визначення оболонки)
openspec completion install

# Встановити для конкретної оболонки
openspec completion install zsh

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

# Видалити
openspec completion uninstall

Windows (PowerShell): Встановити завершення для поточного хосту PowerShell:

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

$env:PROFILE вказує OpenSpec, який профіль налаштувати у цій сесії. Інсталятор створює відсутні каталоги профілю та додає керований блок, який завантажує OpenSpecCompletion.ps1. Перезавантаження профілю негайно активує завершення.

Щоб видалити з поточного хосту, виконайте:

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

Перезапустіть PowerShell після видалення, щоб очистити завершення з поточної сесії.

Завершення є опціональними. CLI згадує про них один раз, у stderr, під час першого запуску команди в інтерактивному терміналі, і більше ніколи — він також залишається спокійним, якщо завершення вже встановлені. Встановіть OPENSPEC_NO_COMPLETIONS=1, щоб повністю приховати цю підказку.


Коди виходу ​

КодЗначення
0Успіх
1Помилка (помилка перевірки, відсутні файли тощо)

Змінні середовища ​

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

Пов'язана документація ​

  • Commands — AI-команди (/opsx:propose, /opsx:apply тощо)
  • Workflows — Типові патерни та коли використовувати кожну команду
  • Customization — Створення користувацьких схем і шаблонів
  • Getting Started — Посібник із першого налаштування