Довідник CLI

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

Огляд

Категорія	Команди	Призначення
Налаштування	`init`, `update`	Ініціалізація та оновлення OpenSpec у вашому проєкті
Перегляд	`list`, `view`, `show`	Дослідження змін та специфікацій
Перевірка	`validate`	Перевірка змін та специфікацій на наявність проблем
Життєвий цикл	`archive`	Завершення завершених змін
Робочий процес	`status`, `instructions`, `templates`, `schemas`	Підтримка робочого процесу на основі артефактів
Схеми	`schema init`, `schema fork`, `schema validate`, `schema which`	Створення та керування користувацькими робочими процесами
Конфігурація	`config`	Перегляд та зміна налаштувань
Утиліти	`feedback`, `completion`	Зворотний зв'язок та інтеграція з оболонкою

Команди для людей та агентів

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

Команди виключно для людей

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

Команда	Призначення
`openspec init`	Ініціалізація проєкту (інтерактивні запити)
`openspec view`	Інтерактивна панель моніторингу
`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` для виявлення схем

Глобальні опції

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

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

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

`openspec init`

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

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

openspec init [path] [options]

Аргументи:

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

Опції:

Опція	Опис
`--tools <list>`	Налаштувати інструменти ШІ без інтерактивного режиму. Використовуйте `all`, `none` або комо-розділений список
`--force`	Автоматичне очищення застарілих файлів без запиту
`--profile <profile>`	Перевизначити глобальний профіль для цього запуску init (`core` або `custom`)

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

Підтримувані ID інструментів (--tools): amazon-q, antigravity, auggie, claude, cline, codex, codebuddy, continue, costrict, crush, cursor, factory, gemini, github-copilot, iflow, kilocode, kiro, opencode, pi, qoder, qwen, roocode, trae, windsurf

Приклади:

bash

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

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

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

# Налаштування для всіх підтримуваних інструментів
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 (якщо доставка включає команди)
... (інші конфігурації інструментів)

`openspec update`

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

openspec update [path] [options]

Аргументи:

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

Опції:

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

Приклад:

bash

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

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

`openspec list`

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

openspec list [options]

Опції:

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

Приклади:

bash

# Вивести всі активні зміни
openspec list

# Вивести всі специфікації
openspec list --specs

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

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

Active changes:
  add-dark-mode     UI theme switching support
  fix-login-bug     Session timeout handling

`openspec view`

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

openspec view

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

`openspec show`

Відображає деталі зміни або специфікації.

openspec show [item-name] [options]

Аргументи:

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

Опції:

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

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

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

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

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

Приклади:

bash

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

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

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

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

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

`openspec validate`

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

openspec validate [item-name] [options]

Аргументи:

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

Опції:

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

Приклади:

bash

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

# Валідувати конкретну зміну
openspec validate add-dark-mode

# Валідувати всі зміни
openspec validate --changes

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

# Строга валідація з підвищеною паралельністю
openspec validate --all --strict --concurrency 12

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

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`	Пропустити запити підтвердження
`--skip-specs`	Пропустити оновлення специфікацій (для змін інфраструктури/інструментів/документації)
`--no-validate`	Пропустити валідацію (потребує підтвердження)

Приклади:

bash

# Інтерактивна архівація
openspec archive

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

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

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

Що робиться:

Валідує зміну (якщо не використано --no-validate)
Запитує підтвердження (якщо не використано --yes)
Зливає дельта-специфікації з openspec/specs/
Переміщує папку зміни до openspec/changes/archive/YYYY-MM-DD-<name>/

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

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

`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
[ ] design
[x] specs
[-] tasks (blocked by: design)

Вивід (JSON):

json

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

`openspec instructions`

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

openspec instructions [artifact] [options]

Аргументи:

Аргумент	Обов'язковий	Опис
`artifact`	Ні	ID артефакту: `proposal`, `specs`, `design`, `tasks` або `apply`

Опції:

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

Особливий випадок: Використовуйте apply як артефакт для отримання інструкцій із реалізації завдань.

Приклади:

bash

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

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

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

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

Вивід включає:

Вміст шаблону для артефакту
Контекст проєкту з конфігурації
Вміст від залежних артефактів
Правила для кожного артефакту з конфігурації

`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

Приклад:

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 "Rapid iteration workflow" \
  --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

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

Проєкт: 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]`	Інтерактивно або за допомогою пресету налаштувати профіль робочого процесу

Приклади:

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

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

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

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

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

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

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

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

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

bash

# Оновлення лише доставки
openspec config profile
# вибрати: Change delivery only
# вибрати доставку: Skills only

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

Допоміжні команди

`openspec feedback`

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

openspec feedback <message> [options]

Аргументи:

Аргумент	Обов'язковий	Опис
`message`	Так	Повідомлення зворотного зв'язку

Параметри:

Параметр	Опис
`--body <text>`	Детальний опис

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

Приклад:

bash

openspec feedback "Add support for custom artifact types" \
  --body "I'd like to define my own artifact types beyond the built-in ones."

`openspec completion`

Керує доповненнями для оболонки CLI OpenSpec.

openspec completion <subcommand> [shell]

Підкоманди:

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

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

Приклади:

bash

# Встановити доповнення (автовизначення оболонки)
openspec completion install

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

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

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

Коди виходу

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

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

Змінна	Опис
`OPENSPEC_TELEMETRY`	Встановити на `0`, щоб вимкнути телеметрію
`DO_NOT_TRACK`	Встановити на `1`, щоб вимкнути телеметрію (стандартний сигнал DNT)
`OPENSPEC_CONCURRENCY`	Замовчування кількості потоків для масової валідації (за замовчуванням: 6)
`EDITOR` або `VISUAL`	Редактор для `openspec config edit`
`NO_COLOR`	Вимикає кольоровий вивід, якщо встановлено

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

Команди - Команди штучного інтелекту (/opsx:propose, /opsx:apply тощо)
Робочі процеси - Загальні шаблони та коли використовувати кожну команду
Налаштування - Створення користувацьких схем та шаблонів
Початок роботи - Посібник з першого налаштування

Довідник CLI ​

Огляд ​

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

Команди виключно для людей ​

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

Глобальні опції ​

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

openspec init ​

openspec update ​

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

openspec list ​

openspec view ​

openspec show ​

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

openspec validate ​

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

openspec archive ​

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

openspec status ​

openspec instructions ​

openspec templates ​

openspec schemas ​

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

openspec schema init ​

openspec schema fork ​

openspec schema validate ​

openspec schema which ​

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

openspec config ​

Допоміжні команди ​

openspec feedback ​

openspec completion ​

Коди виходу ​

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

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

Довідник CLI

Огляд

Команди для людей та агентів

Команди виключно для людей

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

Глобальні опції

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

`openspec init`

`openspec update`

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

`openspec list`

`openspec view`

`openspec show`

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

`openspec validate`

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

`openspec archive`

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

`openspec status`

`openspec instructions`

`openspec templates`

`openspec schemas`

Команди схем

`openspec schema init`

`openspec schema fork`

`openspec schema validate`

`openspec schema which`

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

`openspec config`

Допоміжні команди

`openspec feedback`

`openspec completion`

Коди виходу

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

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