Довідник 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. Див. Підтримувані інструменти для шляхів навичок та команд кожного інструменту.
Приклади:
# Інтерактивна ініціалізація
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 | Примусове оновлення, навіть якщо файли вже актуальні |
Приклад:
# Оновити файли інструкцій після оновлення npm
npm install -g @fission-ai/openspec@latest
openspec updateСпочатку оновіть пакет. Файли інструкцій генеруються встановленим CLI, тому запуск openspec update на застарілій версії повідомляє, що все актуально, не додаючи робочі процеси, які з'явилися в новіших версіях.
Щоб це було видно, openspec update запитує реєстр npm, чи була опублікована новіша версія CLI. Якщо ваша версія відстає, пропонується оновлення:
A newer OpenSpec CLI is available (v1.6.0 → v1.7.0).
Running from: /usr/local/lib/node_modules/@fission-ai/openspec
? Upgrade to v1.7.0 now? (Y/n)Відповідь «так» запускає npm install -g @fission-ai/openspec@latest, потім знову виконує оновлення з новим CLI, щоб нові робочі процеси потрапили в ту ж команду. Він підтверджує оновлення, запитуючи версію встановленого бінарного файлу, а не довіряючи коду виходу npm, тому якщо інша попередня установка у вашому PATH все ще відповідає, він повідомляє про це, замість стверджувати успіх. Відповідь «ні» виводить команду та оновлює з наявним CLI. Ctrl-C зупиняє команду.
Пропозиція з'являється лише в інтерактивному терміналі і лише тоді, коли npm володіє встановленням — єдиний випадок, який справді виправляє npm install -g. Для всього іншого виводиться команда, яка відповідає способу встановлення:
| Як встановлено OpenSpec | Що ви отримуєте |
|---|---|
| Глобальне встановлення npm | Запит та запуск оновлення — в інтерактивному терміналі; при перенаправленому виводі виводиться лише команда |
| Глобальне встановлення pnpm, bun, yarn або volta | Власна команда менеджера: pnpm add -g …@latest, bun add -g …@latest, yarn global add …@latest або volta install …@latest |
| Залежність проекту | Повідомлення про оновлення залежності, оскільки її менеджер пакетів володіє lock-файлом |
Кеш npx / dlx | npx @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.
openspec store setup [id] [options]Параметри:
| Параметр | Опис |
|---|---|
--path <path> | Папка, де має знаходитися сховище (наприклад ~/openspec/<id>) |
--remote <url> | Записати канонічний віддалений репозиторій у store.yaml нового сховища |
--init-git | Ініціалізувати репозиторій Git із початковим комітом (типово) |
--no-init-git | Пропустити всі дії з Git: без ініціалізації, без початкового коміту |
--json | Вивести JSON |
Неінтерактивні запуски (--json, скрипти, агенти) повинні передавати ідентифікатор сховища та --path. У інтерактивному терміналі налаштування запитує розташування з редагованим підказкою у видимому місці, що належить користувачу (наприклад ~/openspec/<id>); воно ніколи не використовує керований каталог даних OpenSpec як типове значення.
Приклади:
openspec store setup
openspec store setup team-context
openspec store setup team-context --path ~/openspec/team-context --no-init-git
openspec store setup team-context --path ~/openspec/team-context --no-init-git --jsonopenspec store register
Реєстрація наявного локального папки сховища. Під час бета-версії сховищ корінь може бути зареєстрований до того, як існують зміни, специфікації застосовані, або зміни заархівовані; у такому випадку openspec/changes/, openspec/specs/ та openspec/changes/archive/ можуть бути відсутні, доки звичайні команди їх не створять. Репозиторій лише з конфігурацією, який оголошує store: <id>, залишається вказівником на інше сховище та не реєструється як корінь сховища, якщо цей вказівник не видалено.
openspec store register [path] [options]Параметри:
| Параметр | Опис |
|---|---|
--id <id> | Ідентифікатор сховища; типово береться з метаданих сховища або назви папки |
--yes | Підтвердити створення метаданих ідентичності сховища для здорового кореня OpenSpec |
--json | Вивести JSON |
openspec store unregister
Видалити локальну реєстрацію сховища без видалення файлів.
openspec store unregister <id> [--json]Використовуйте це, коли сховище було переміщене, клоноване в інше місце або більше не повинно відображатися OpenSpec на цьому комп'ютері.
openspec store remove
Видалитi локальну реєстрацію сховища та видалити його локальну папку.
openspec store remove <id> [--yes] [--json]remove показує точну папку перед видаленням у інтерактивному терміналі. Агенти, скрипти та виклики JSON повинні передавати --yes для підтвердження видалення. OpenSpec відмовляється видалити папку, яка не містить відповідних метаданих сховища.
openspec store list
Перелічити локально зареєстровані сховища.
openspec store list [--json]
openspec store ls [--json]openspec store doctor
Перевірити локальну реєстрацію сховища, метадані та наявність Git.
openspec store doctor [id] [--json]Doctor призначений лише для діагностики; він повідомляє про відсутні корені, невідповідності метаданих та некоректний стан локального реєстру без внесення змін у сховище.
Посилання на сховища з проекту
Репозиторій проекту може оголосити, які сховища використовуються для його роботи, у openspec/config.yaml:
schema: spec-driven
references:
- team-contextЗ цього моменту вихід openspec instructions у цьому репозиторії (як на рівні окремих артефактів, так і на поверхні apply, у JSON- та людському режимах) містить індекс специфікацій кожного посиланого сховища — ідентифікатори специфікацій, однорядкове резюме з розділу Purpose кожної специфікації та команду отримання (openspec show <spec-id> --type spec --store <id>). Індекс будується наживо з зареєстрованого клонування під час кожного запуску; вміст специфікацій ніколи не копіюється у вихідні дані.
Посилання — це контекст лише для читання. Вони ніколи не змінюють місце, де виконуються команди: робота залишається у власному корені репозиторію, а запис у посилане сховище залишається явним дією --store. Посилання, яке не може бути розв'язане (наприклад, сховище не зареєстроване на цьому комп'ютері), перетворюється на попередження в індексі з точним виправленням, а інструкції все одно генеруються. openspec doctor звітує про стан посилань у одному місці.
Запис джерела клонування сховища
Сховище може записати своє канонічне джерело клонування у свій закомічений файл ідентичності, щоб онбординг ніколи не застрягав на етапі «зареєструйте сховище»:
openspec store setup team-context --path ~/openspec/team-context \
--remote git@github.com:acme/team-context.gitВіддалений репозиторій потрапляє у .openspec-store/store.yaml всередині початкового коміту, тому кожне клонування народжується, знаючи це. Для наявного сховища відредагуйте store.yaml вручну та закомітьте. store doctor показує записаний віддалений репозиторій (та спостережений Git origin клонування); підказки щодо спільного використання під час setup/register називають його; а register записує origin клонування у машинно-локальний реєстр.
Оголошення посилання також може містити джерело клонування, щоб колега, який ще не має сховища, отримав повне, готове до вставлення виправлення (git clone <remote> <path> && openspec store register <path> --id <id>):
references:
- { id: team-context, remote: "git@github.com:acme/team-context.git" }Запис віддаленої адреси — це не синхронізація: OpenSpec ніколи не клонує, не тягне та не штовхає самостійно.
Оголошення сховища за замовчуванням
Репозиторій, планування якого повністю зовнішнє — без локальних openspec/specs/ або openspec/changes/ — може оголосити своє сховище один раз замість передачі --store для кожної команди:
# openspec/config.yaml (єдиний файл під openspec/)
store: team-contextЗвичайні команди тоді автоматично розв'язуються до оголошеного сховища; банер кореня та JSON-блок root звітують source: "declared" з ідентифікатором сховища, а виведені підказки все одно містять --store <id>. Оголошення — це резервний варіант, ніколи не перевизначення: явний --store завжди має пріоритет, а каталог із реальними папками планування ігнорує вказівник (з попередженням). Щоб перетворити репозиторій-вказівник на локальний корінь OpenSpec, видаліть рядок store: та виконайте openspec init — init відмовляється створювати каркас, поки оголошення присутнє.
Машинний варіант покриває всі репозиторії одразу: openspec config set defaultStore <id> (дивіться Конфігурацію). Він враховується лише після того, як --store, локальний корінь та проєктний вказівник усі не змогли розв'язатися; банер кореня та JSON-блок root тоді звітують source: "global_default".
Doctor (здоров'я зв'язків)
Одне запитання лише для читання, одне місце: чи є корінь OpenSpec здоровим, і чи доступні сховища (stores), на які він посилається, на цій машині?
openspec doctor [--store <id>] [--json]Звіт розділяє здоров'я кореня, здоров'я метаданих сховища (включно з приміткою, коли записаний віддалений репозиторій і походження checkout розходяться, а також приміткою, коли checkout сховища відстав від свого останнього отриманого upstream-tracking ref), та здоров'я посилань (ті самі діагностичні інструкції, що показує show, з виправленнями клонування для нерозв'язаних посилань). Знахідки про здоров'я будь-якої серйозності завершуються кодом 0 — агенти читають масиви status; лише помилки команд (відсутній корінь, невідоме сховище) завершуються кодом 1. Doctor ніколи не клонує, не синхронізує та не ремонтує. Щоб отримати саму зібрану множину, а не її здоров'я, використовуйте openspec context.
Робочий контекст (зібрана множина)
Все, до чого ця робота стосується через декларації OpenSpec, в одній робочій множині: корінь OpenSpec і сховища, на які він посилається.
openspec context [--store <id>] [--json] [--code-workspace <path> [--force]]JSON-бриф призначений для споживання агентами (кожне доступне посилальне сховище несе свій рецепт отримання; нерозв'язані члени несуть ті самі інструкції з виправленнями, що й doctor show). --code-workspace додатково записує файл робочого простору VS Code, що містить корінь плюс доступні посилальні сховища (папки ref:<id>) — це єдиний запис, який виконує ця команда, і він відмовляється без --force, якщо файл уже існує. Недоступні члени повідомляються, а не вгадуються.
«Робочий контекст» — це зібрана множина; поле context: у openspec/config.yaml — це проектний контекст, впроваджений в інструкції — дві різні речі. openspec doctor відповідає, чи множина здорова; openspec context відповідає, чим є множина.
Персональні робочі набори (worksets)
Бета. Worksets є частиною нової бета-поверхні; команди, прапорці та формати файлів можуть змінювати форму між релізами. Для покрокового проходження див. посібник зі сховищ.
Workset — це персональний, іменований погляд на папки, над якими ви працюєте разом — планувальний корінь плюс усе, що ви оберете додатково — що зберігається на вашій машині та відкривається за назвою у вашому інструменті. Він суто локальний: ніколи не комітиться, ніколи не поширюється, ніколи не виводиться з декларацій, і видалення одного ніколи не торкається папок-членів.
openspec workset create [name] [--member <path> | --member <name>=<path>]... [--tool <id>] [--json]
openspec workset list [--json]
openspec workset open <name> [--tool <id>]
openspec workset remove <name> [--yes] [--json]create виконує короткий керований процес (або приймає прапорці --member без інтерактиву; перший член є основним — сесії починаються там). open запускає вибраний інструмент: редактори (VS Code, Cursor) відкривають вікно з кожним членом і повертаються; CLI-агенти (Claude Code, codex) захоплюють цей термінал як сесію з кожним членом, прикріпленим без попередньо заповненого запиту, завершуючись, коли ви виходите. Папка-член, відсутня під час відкриття, пропускається з приміткою; решта відкривається. Збережену перевагу інструменту можна перевизначити кожним відкриттям за допомогою --tool.
Підтримка нового інструменту — це конфігурація, а не код. Кожен інструмент є одним із двох стилів запуску — workspace-file (запускається зі згенерованим .code-workspace) або attach-dirs (один прапорець прикріплення на члена) — і ключ openers у глобальному config.json (відкрийте його за допомогою openspec config edit) додає інструменти або налаштовує вбудовані за полями:
{
"openers": {
"zed": { "style": "workspace-file" },
"claude": { "attach_flag": "--dir" }
}
}Увесь стан workset зберігається в папці worksets/ глобального каталогу даних (збережені погляди плюс згенеровані файли <name>.code-workspace, які перегенеруються при кожному відкритті); видалення цієї папки видаляє всі сліди.
Команди перегляду
openspec list
Перелічіть зміни або специфікації у вашому проєкті.
openspec list [options]Опції:
| Опція | Опис |
|---|---|
--specs | Перелічити специфікації замість змін |
--changes | Перелічити зміни (за замовчуванням) |
--sort <order> | Сортувати за recent (за замовчуванням) або name |
--json | Вивести у форматі JSON |
Приклади:
# Перелічити всі активні зміни
openspec list
# Перелічити всі специфікації
openspec list --specs
# JSON-вивід для скриптів
openspec list --jsonВивід (текст):
Changes:
add-dark-mode No tasks just nowopenspec 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) |
Приклади:
# Інтерактивний вибір
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, і завершується з ненульовим кодом, якщо знайдено незавершені. Це дозволяє виявити зміни, заархівовані з незакінченою роботою — зручно використовувати в хуку перед комітом.
Приклади:
# Інтерактивна валідація
openspec validate
# Перевірити конкретну зміну
openspec validate add-dark-mode
# Перевірити всі зміни
openspec validate --changes
# Перевірити все з виводом у JSON (для CI/скриптів)
openspec validate --all --json
# Сувора валідація зі збільшеним паралелізмом
openspec validate --all --strict --concurrency 12
# Помилка, якщо будь-яка архівована зміна все ще має непозначені завдання
openspec validate --archivedВивід (текст):
Validating add-dark-mode...
✓ proposal.md valid
✓ specs/ui/spec.md valid
⚠ design.md: missing "Technical Approach" section
1 warning foundВивід (JSON):
{
"version": "1.0.0",
"results": {
"changes": [
{
"name": "add-dark-mode",
"valid": true,
"warnings": ["design.md: missing 'Technical Approach' section"]
}
]
},
"summary": {
"total": 1,
"valid": 1,
"invalid": 0
}
}Команди життєвого циклу
openspec archive
Архівує завершену зміну та вливає дельта-специфікації в основні специфікації.
openspec archive [change-name] [options]Аргументи:
| Аргумент | Обов’язковий | Опис |
|---|---|---|
change-name | Ні | Назва зміни для архівації (якщо не вказано — буде запропоновано вибрати; обов’язковий, коли підказка не може бути оброблена) |
Опції:
| Опція | Опис |
|---|---|
-y, --yes | Пропустити підтвердження. Обов’язкова, коли на підказки немає кому відповідати — агент ШІ, завдання CI або будь-який запуск із закритим stdin |
--skip-specs | Пропустити оновлення специфікацій для одного запуску архівації. Зміна, яка постійно не має дельт специфікацій, повинна містити skip_specs: true у своєму .openspec.yaml — тоді вона архівується без прапора |
--no-validate | Пропустити валідацію (потребує підтвердження). Також вимикає виведення можливостей з експлуатації — без вердикту валідатора нічого не виводиться |
Приклади:
# Інтерактивна архівація (запитує, яку зміну, потім підтверджує)
openspec archive
# Архівувати конкретну зміну
openspec archive add-dark-mode
# Архівувати без підказок (агенти, CI, скрипти)
openspec archive add-dark-mode --yes
# Архівувати інструментальну зміну, яка не впливає на специфікації
openspec archive update-ci-config --skip-specsВивести можливість з експлуатації: Додайте маркер виведення до метаданих зміни:
# openspec/changes/retire-legacy/.openspec.yaml
schema: spec-driven
retire_capabilities: trueПотім архівуйте зміну звичайним чином:
openspec archive retire-legacy --yesКоли зміна видаляє останню вимогу можливості, OpenSpec видаляє її живий spec.md. Інші дельти можливостей у тій самій зміні все одно оновлюють свої основні специфікації. Без маркера архівація зупиняється перед зміною будь-яких файлів і повідомляє, що його потрібно додати.
Що вона робить:
- Перевіряє зміну (якщо не вказано
--no-validate) - Запитує підтвердження (якщо не вказано
--yes) - Резервує місце призначення в архіві перед зміною будь-якої основної специфікації
- Перевіряє та вливає активні дельта-специфікації в
openspec/specs/— можливість, останню вимогу якої видаляє зміна, виводиться з експлуатації, а її файл специфікації видаляється, але тільки якщо.openspec.yamlзміни поруч ізschema:міститьretire_capabilities: true - Переміщує теку зміни до
openspec/changes/archive/YYYY-MM-DD-<name>/ - Якщо мутація специфікації або остаточне переміщення зазнає невдачі до завершення повної архівації, відновлює специфікації та залишає або повертає зміну на її активний шлях
- Якщо перевірене резервне копіювання завершено, але очищення проміжних джерел не вдалося, зберігає завершений архів та зафіксований стан специфікацій для відновлення
Без терміналу: агент ШІ, завдання CI або будь-який запуск із закритим stdin не можуть відповісти на крок 2, тому архівація зупиняється, не торкаючись нічого, завершується з кодом 1 і називає команду для повторного запуску — openspec archive <name> --yes, зберігаючи інші передані вами прапори. Передайте --yes (та назву зміни) одразу, щоб уникнути зайвого циклу.
Команди робочого процесу
Ці команди підтримують артефакторієнтований робочий процес OPSX. Вони корисні як для людей, які перевіряють прогрес, так і для агентів, які визначають наступні кроки.
openspec new change
Створює каталог зміни та необов'язкові метадані, що перевірені, у визначеному кореневому каталозі OpenSpec.
openspec new change <name> [options]Імена змін повинні використовувати нижній регістр у форматі kebab-case: малі літери, цифри та одинарні дефіси. Вони не можуть містити пробіли, підкреслення, великі літери, послідовні дефіси або дефіси на початку/кінці. Початкова цифра дозволяється, тому ви можете додавати префікси для впорядкування або розподілу змін за рівнями, наприклад 100-add-feature або 00001-add-auth.
Параметри:
| Параметр | Опис |
|---|---|
--description <text> | Опис для додавання до index.md |
--goal <text> | Необов'язкові метадані цілі для збереження зі зміною |
--schema <name> | Схема робочого процесу для використання |
--store <id> | Ідентифікатор сховища для використання як кореневого каталогу OpenSpec (сховище — це незалежний репозиторій OpenSpec, який ви зареєстрували) |
--json | Вивести JSON |
Приклади:
openspec new change add-billing-api
openspec new change add-billing-api --store team-context --jsonopenspec status
Відображає стан завершеності артефактів для зміни.
openspec status [options]Параметри:
| Параметр | Опис |
|---|---|
--change <id> | Ім'я зміни (запитує, якщо не вказано) |
--schema <name> | Перевизначення схеми (визначається автоматично з конфігурації зміни) |
--json | Вивести як JSON |
Приклади:
# Інтерактивна перевірка стану
openspec status
# Стан для конкретної зміни
openspec status --change add-dark-mode
# JSON для використання агентом
openspec status --change add-dark-mode --jsonВивід (текст):
Change: add-dark-mode
Schema: spec-driven
Progress: 2/4 artifacts complete
[x] proposal
[x] specs
[ ] design
[-] tasks (blocked by: design)Зміна, яка оголошує skip_specs: true, відображає свій етап специфікацій як [~] specs (skipped: change declares skip_specs) та виключає його з підрахунку прогресу.
Вивід (JSON):
{
"changeName": "add-dark-mode",
"schemaName": "spec-driven",
"isPlanningComplete": false,
"isComplete": false,
"applyRequires": ["tasks"],
"artifacts": [
{"id": "proposal", "outputPath": "proposal.md", "status": "done", "requires": []},
{"id": "specs", "outputPath": "specs/**/*.md", "status": "done", "requires": ["proposal"]},
{"id": "design", "outputPath": "design.md", "status": "ready", "requires": ["proposal"]},
{"id": "tasks", "outputPath": "tasks.md", "status": "blocked", "requires": ["specs", "design"], "missingDeps": ["design"]}
]
}isPlanningComplete повідомляє, чи існує кожен артефакт планування, який не пропущено; пропущені артефакти вважаються виконаними без створення. Це не повідомляє, чи завершені завдання реалізації. isComplete зберігається як сумісний псевдонім із тим самим значенням.
Артефакти перелічені у порядку залежностей — залежність ніколи не з'являється після чогось, що її потребує, — а артефакти, які стають готовими одночасно (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) для валідної зміни; це не архівує та не змінює нічого.
Приклади:
# Отримати інструкції для наступного артефакта
openspec instructions --change add-dark-mode
# Отримати інструкції для конкретного артефакта
openspec instructions design --change add-dark-mode
# Отримати інструкції для застосування/реалізації
openspec instructions apply --change add-dark-mode
# Отримати поточні вхідні дані операції архівування без архівування
openspec instructions archive --change add-dark-mode --json
# JSON для споживання агентом
openspec instructions design --change add-dark-mode --jsonВивід містить:
- Шаблонний вміст для артефакта
- Контекст проєкту з конфігурації
- Вміст із залежних артефактів
- Правила для кожного артефакта з конфігурації
- Поточний контекст проєкту та відповідні рекомендації операції для
apply/archive
Вхідні дані операції читаються з визначеного репозиторію або вибраного сховища при кожному виклику. Контекст проєкту — обов'язковий вхідний параметр рівня запиту: агенти читають його та застосовують відповідні факти проєкту, конвенції та обмеження. Рекомендації операції — необов'язкова додаткова порада: агенти розглядають кожен запис і дотримуються лише записів, які є застосовними та сумісними зі вбудованим робочим процесом. Обидва поля залишаються окремими від явних виборів користувача, стану, що керується CLI, вбудованих інструкцій та правил артефактів. Конфліктний контекст повідомляється; конфліктні або незастосовні рекомендації не виконуються, і пояснюється причина. Це поведінкові договори для згенерованих агентів, а не примусові перевірки CLI. instructions archive повертає лише вибрану зміну, необов'язкові вхідні дані та кореневі метадані; він не включає статичний робочий процес архівування.
Для артефакта, пропущеного через skip_specs: true, вивід — лише попередження (JSON додає поля skipped/warning) — артефакт не повинен бути створений.
openspec templates
Показати визначені шляхи шаблонів для всіх артефактів у схемі.
openspec templates [options]Параметри:
| Параметр | Опис |
|---|---|
--schema <name> | Схема для огляду (за замовчуванням: spec-driven) |
--json | Вивести як JSON |
Приклади:
# Показати шляхи шаблонів для схеми за замовчуванням
openspec templates
# Показати шаблони для власної схеми
openspec templates --schema my-workflow
# JSON для програмного використання
openspec templates --jsonВивід (текст):
Schema: spec-driven
Templates:
proposal → ~/.openspec/schemas/spec-driven/templates/proposal.md
specs → ~/.openspec/schemas/spec-driven/templates/specs.md
design → ~/.openspec/schemas/spec-driven/templates/design.md
tasks → ~/.openspec/schemas/spec-driven/templates/tasks.mdopenspec schemas
Перелічити доступні схеми робочих процесів з їхніми описами та потоками артефактів.
openspec schemas [options]Параметри:
| Параметр | Опис |
|---|---|
--json | Вивести як JSON |
--store <id> | Використати зареєстроване сховище як кореневий каталог OpenSpec |
Приклад:
openspec schemasВивід:
Available schemas:
spec-driven (package)
The default spec-driven development workflow
Flow: proposal → specs → design → tasks
my-custom (project)
Custom workflow for this project
Flow: research → proposal → tasksКоманди схем
Команди для створення та керування власними схемами робочих процесів.
openspec schema init
Створити нову схему локально для проєкту.
openspec schema init <name> [options]Аргументи:
| Аргумент | Обов'язковий | Опис |
|---|---|---|
name | Так | Назва схеми (kebab-case) |
Опції:
| Опція | Опис |
|---|---|
--description <text> | Опис схеми |
--artifacts <list> | Артефакти через кому (за замовчуванням: proposal,specs,design,tasks) |
--default | Встановити як схему проєкту за замовчуванням |
--no-default | Не питати про встановлення як схему за замовчуванням |
--force | Перезаписати наявну схему |
--json | Вивести результат у форматі JSON |
Приклади:
# Інтерактивне створення схеми
openspec schema init research-first
# Неінтерактивне створення з певними артефактами
openspec schema init rapid \
--description "Робочий процес швидкої ітерації" \
--artifacts "proposal,tasks" \
--defaultЩо створюється:
openspec/schemas/<name>/
├── schema.yaml # Визначення схеми
└── templates/
├── proposal.md # Шаблон для кожного артефакту
├── specs.md
├── design.md
└── tasks.mdopenspec schema fork
Скопіювати наявну схему до свого проєкту для налаштування.
openspec schema fork <source> [name] [options]Аргументи:
| Аргумент | Обов'язковий | Опис |
|---|---|---|
source | Так | Схема для копіювання |
name | Ні | Назва нової схеми (за замовчуванням: <source>-custom) |
Опції:
| Опція | Опис |
|---|---|
--force | Перезаписати наявне призначення |
--json | Вивести результат у форматі JSON |
Приклад:
# Форк вбудованої схеми spec-driven
openspec schema fork spec-driven my-workflowopenspec schema validate
Перевірити структуру схеми та шаблони.
openspec schema validate [name] [options]Аргументи:
| Аргумент | Обов'язковий | Опис |
|---|---|---|
name | Ні | Схема для перевірки (якщо пропущено, перевіряються всі) |
Опції:
| Опція | Опис |
|---|---|
--verbose | Показати детальні кроки перевірки |
--json | Вивести результат у форматі JSON |
Приклад:
# Перевірити конкретну схему
openspec schema validate my-workflow
# Перевірити всі схеми
openspec schema validateopenspec schema which
Показати, звідки береться схема (корисно для налагодження пріоритету).
openspec schema which [name] [options]Аргументи:
| Аргумент | Обов'язковий | Опис |
|---|---|---|
name | Ні | Назва схеми |
Опції:
| Опція | Опис |
|---|---|
--all | Показати всі схеми та їхні джерела |
--json | Вивести результат у форматі JSON |
Приклад:
# Перевірити, звідки береться схема
openspec schema which spec-drivenВивід:
spec-driven resolves from: package
Source: /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-drivenПріоритет схем:
- Проєкт:
openspec/schemas/<name>/ - Користувач:
~/.local/share/openspec/schemas/<name>/ - Пакет: вбудовані схеми
Команди конфігурації
openspec config
Перегляд та зміна глобальної конфігурації OpenSpec.
openspec config <subcommand> [options]Підкоманди:
| Підкоманда | Опис |
|---|---|
path | Показати розташування файлу конфігурації |
list | Показати всі поточні налаштування |
get <key> | Отримати конкретне значення |
set <key> <value> | Встановити значення |
unset <key> | Видалити ключ |
reset | Скинути до налаштувань за замовчуванням |
edit | Відкрити у $EDITOR |
profile [preset] | Налаштувати робочий процес інтерактивно або за допомогою пресету |
Приклади:
# Показати шлях до файлу конфігурації
openspec config path
# Показати всі налаштування
openspec config list
# Отримати конкретне значення
openspec config get telemetry.enabled
# Встановити значення (вимкнути анонімну телеметрію використання)
openspec config set telemetry.enabled false
# Встановити значення рядка явно
openspec config set user.name "My Name" --string
# Видалити користувацьке налаштування
openspec config unset user.name
# Встановити сховище за замовчуванням на рівні машини (резервний корінь, коли немає --store,
# локального кореня або сховища проєкту: вирішує покажчик)
openspec config set defaultStore team-plans
# Скинути всю конфігурацію
openspec config reset --all --yes
# Редагувати конфігурацію у своєму редакторі
openspec config edit
# Налаштувати профіль за допомогою майстра на основі дій
openspec config profile
# Швидкий пресет: перемкнути робочі процеси на core (зберігає режим доставки)
openspec config profile coreВідмова від телеметрії: telemetry.enabled за замовчуванням увімкнено, якщо не встановлено (модель відмови). Встановіть його у false, щоб вимкнути анонімну статистику використання та перевірку версії openspec update. Змінні середовища мають пріоритет над конфігурацією: OPENSPEC_TELEMETRY=0, DO_NOT_TRACK=1, а значення CI (наприклад, true/1/yes) завжди вимикає телеметрію незалежно від значення конфігурації.
openspec config profile починається з підсумку поточного стану, а потім дозволяє вибрати:
- Змінити доставку та робочі процеси
- Змінити лише доставку
- Змінити лише робочі процеси
- Зберегти поточні налаштування (вихід)
Якщо зберегти поточні налаштування, жодних змін не записується і не показується запит на оновлення. Якщо конфігурація не змінюється, але поточні файли проєкту не синхронізовані з глобальним профілем/доставкою, OpenSpec покаже попередження та запропонує openspec update. Натискання Ctrl+C також скасовує процес коректно (без стек-трейсу) і завершується з кодом 130. У контрольному списку робочих процесів [x] означає, що робочий процес вибрано в глобальній конфігурації. Щоб застосувати ці вибори до файлів проєкту, запустіть openspec update (або виберіть «Застосувати зміни до цього проєкту зараз?», коли з'явиться запит у проєкті).
Інтерактивні приклади:
# Оновлення лише доставки
openspec config profile
# виберіть: Змінити лише доставку
# виберіть доставку: Лише навички (Skills only)
# Оновлення лише робочих процесів
openspec config profile
# виберіть: Змінити лише робочі процеси
# перемкніть робочі процеси в контрольному списку, потім підтвердітьКоманди утиліт
openspec feedback
Надіслати відгук про OpenSpec. Створює issue на GitHub.
openspec feedback <message> [options]Аргументи:
| Аргумент | Обов'язковий | Опис |
|---|---|---|
message | Так | Короткий опис відгуку; довгий текст скорочується в назві issue та зберігається в тілі |
Опції:
| Опція | Опис |
|---|---|
--body <text> | Додаткові деталі, що включаються після короткого опису |
Вимоги: GitHub CLI (gh) має бути встановлений та автентифікований.
Приклад:
openspec feedback "Додати підтримку користувацьких типів артефактів" \
--body "Я хочу визначати власні типи артефактів, окрім вбудованих."openspec completion
Керування завершенням команд для CLI OpenSpec.
openspec completion <subcommand> [shell]Підкоманди:
| Підкоманда | Опис |
|---|---|
generate [shell] | Вивести скрипт завершення у stdout |
install [shell] | Встановити завершення для вашої оболонки |
uninstall [shell] | Видалити встановлені завершення |
Підтримувані оболонки: bash, zsh, fish, powershell
Приклади:
# Встановити завершення (автоматичне визначення оболонки)
openspec completion install
# Встановити для конкретної оболонки
openspec completion install zsh
# Згенерувати скрипт для ручного встановлення (bash)
openspec completion generate bash > ~/.bash_completion.d/openspec
# Видалити
openspec completion uninstallWindows (PowerShell): Встановити завершення для поточного хосту PowerShell:
$env:PROFILE = $PROFILE
openspec completion install powershell
. $PROFILE$env:PROFILE вказує OpenSpec, який профіль налаштувати у цій сесії. Інсталятор створює відсутні каталоги профілю та додає керований блок, який завантажує OpenSpecCompletion.ps1. Перезавантаження профілю негайно активує завершення.
Щоб видалити з поточного хосту, виконайте:
$env:PROFILE = $PROFILE
openspec completion uninstall powershellПерезапустіть PowerShell після видалення, щоб очистити завершення з поточної сесії.
Завершення є опціональними. CLI згадує про них один раз, у stderr, під час першого запуску команди в інтерактивному терміналі, і більше ніколи — він також залишається спокійним, якщо завершення вже встановлені. Встановіть OPENSPEC_NO_COMPLETIONS=1, щоб повністю приховати цю підказку.
Коди виходу
| Код | Значення |
|---|---|
0 | Успіх |
1 | Помилка (помилка перевірки, відсутні файли тощо) |
Змінні середовища
| Змінна | Опис |
|---|---|
OPENSPEC_TELEMETRY | Встановіть у 0, щоб вимкнути телеметрію та перевірку версії openspec update (перевизначає telemetry.enabled у глобальній конфігурації) |
DO_NOT_TRACK | Встановіть у 1, щоб вимкнути телеметрію та перевірку версії openspec update (стандартний сигнал DNT; перевизначає конфігурацію) |
OPENSPEC_CONCURRENCY | Кількість паралельних операцій для масової перевірки за замовчуванням (за замовчуванням: 6) |
EDITOR або VISUAL | Редактор для openspec config edit |
NO_COLOR | Вимикає кольоровий вивід, коли встановлено |
OPENSPEC_NO_ANIMATION | Вимикає анімацію привітання openspec init, коли встановлено |
OPENSPEC_NO_COMPLETIONS | Встановіть у 1, щоб приховати одноразову підказку про завершення команд |
OPENSPEC_NO_UPDATE_CHECK | Вимкнути перевірку openspec update на наявність новішої опублікованої версії CLI, коли встановлено (будь-яке значення, включаючи порожнє). Також пропускається, коли CI встановлено (окрім false/0/no/off) або NODE_ENV=test |
npm_config_registry | Реєстр, до якого звертається перевірка версії openspec update. Має бути URL http(s), інакше використовується https://registry.npmjs.org. Файл .npmrc не читається |
Пов'язана документація
- Commands — AI-команди (
/opsx:propose,/opsx:applyтощо) - Workflows — Типові патерни та коли використовувати кожну команду
- Customization — Створення користувацьких схем і шаблонів
- Getting Started — Посібник із першого налаштування