OpenSpec

markdown

# CLI

> Polecenia terminalowe `openspec`.

<!-- Instalacja, aktualizacja i odinstalowanie samego interfejsu CLI znajdują się w installation.md. -->

## Polecenia

**Konfiguracja**

| Polecenie | Co robi |
|---|---|
| [`openspec init`](#openspec-init) | Zainicjuj OpenSpec w projekcie. |
| [`openspec update`](#openspec-update) | Zaktualizuj zainstalowane pliki instrukcji OpenSpec. |
| [`openspec config`](#openspec-config) | Wyświetl i zmień konfigurację globalną. |

**Zmiany i specyfikacje**

| Polecenie | Co robi |
|---|---|
| [`openspec list`](#openspec-list) | Wyświetl listę zmian lub specyfikacji za pomocą `--specs`. |
| [`openspec show`](#openspec-show) | Wydrukuj zmianę lub specyfikację jako markdown lub JSON. |
| [`openspec view`](#openspec-view) | Jednoekranowy panel specyfikacji i zmian. |
| [`openspec validate`](#openspec-validate) | Sprawdź zmiany i specyfikacje pod kątem problemów strukturalnych. |
| [`openspec archive`](#openspec-archive) | Przenieś ukończoną zmianę do archiwum i zaktualizuj główne specyfikacje. |

**Przepływy pracy i schematy**

Twój agent wykonuje większość z nich podczas przepływu pracy.

| Polecenie | Co robi |
|---|---|
| [`openspec new`](#openspec-new) | Utwórz nowy katalog zmian. |
| [`openspec status`](#openspec-status) | Status ukończenia artefaktu dla jednej lub każdej aktywnej zmiany. |
| [`openspec instructions`](#openspec-instructions) | Instrukcje tworzenia artefaktu, stosowania lub archiwizacji. |
| [`openspec templates`](#openspec-templates) | Rozwiązane ścieżki szablonów dla artefaktów schematu. |
| [`openspec schemas`](#openspec-schemas) | Wyświetl listę dostępnych schematów przepływu pracy. |
| [`openspec schema`](#openspec-schema) | Zbadaj, rozgałęź lub utwórz schemat (eksperymentalne). |

**Multi-repo (beta)**

| Polecenie | Co robi |
|---|---|
| [`openspec store`](#openspec-store) | Twórz i zarządzaj magazynami: samodzielnymi repozytoriami OpenSpec zarejestrowanymi na twojej maszynie. |
| [`openspec doctor`](#openspec-doctor) | Raportuj stan relacji dla rozwiązanego katalogu głównego OpenSpec. |
| [`openspec context`](#openspec-context) | Wydrukuj kontekst pracy dla rozwiązanego katalogu głównego OpenSpec. |
| [`openspec workset`](#openspec-workset) | Twórz, przechowuj i otwieraj osobiste widoki robocze. |

**Narzędzia**

| Polecenie | Co robi |
|---|---|
| [`openspec version`](#openspec-version) | Zgłoś zainstalowaną wersję i opcjonalnie sprawdź aktualizacje. |
| [`openspec install`](#openspec-install) | Zainstaluj samodzielny `openspec`, który działa bez Node.js. |
| [`openspec feedback`](#openspec-feedback) | Prześlij opinię o OpenSpec. |
| [`openspec completion`](#openspec-completion) | Zainstaluj lub wygeneruj uzupełnienia powłoki. |

**Przestarzałe**

| Polecenie | Co robi |
|---|---|
| [`openspec change`](#openspec-change) | Forma rzeczownikowa poleceń show, list i validate dla zmian. CLI ostrzega i wskazuje polecenia z czasownikiem na początku. |
| [`openspec spec`](#openspec-spec) | Forma rzeczownikowa poleceń show, list i validate dla specyfikacji, z tym samym ostrzeżeniem. |

Każde polecenie przyjmuje `-h, --help`. Polecenie `openspec` bez argumentów również przyjmuje:

- `-V, --version`: wydrukuj wersję CLI.
- `--no-color`: wyłącz kolorowe wyjście.

openspec init

Inicjalizuje OpenSpec w projekcie.

bash

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

Bez --tools init wyświetla pytanie o wybór narzędzi w interaktywnym terminalu. Poza terminalem konfiguruje narzędzia wykryte w projekcie. Jeśli żadne nie zostaną wykryte, kończy działanie z kodem 1 i wyświetla listę prawidłowych identyfikatorów.

Repozytoria tylko z magazynem

Gdy openspec/config.yaml zawiera linię store: a repozytorium nie ma lokalnych specyfikacji ani zmian, uruchom init z katalogu głównego repozytorium:

bash

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

Pliki integracyjne: zapisywane w repozytorium kodu.
openspec/config.yaml: zachowywany bajt w bajt.
openspec/specs/ i openspec/changes/: nie są tworzone w repozytorium kodu.

Uruchomienie init z podkatalogu kończy działanie z kodem 1 i informuje o konieczności uruchomienia go z katalogu głównego repozytorium. --language również kończy działanie z kodem 1, ponieważ język należy do konfiguracji zewnętrznego magazynu. Uruchom init w katalogu głównym magazynu lub edytuj tę konfigurację bezpośrednio.

Argumenty

Argument	Opis
`path`	Katalog projektu do zainicjalizowania. Domyślnie: bieżący katalog. Tworzony, jeśli nie istnieje.

Opcje

Flaga	Efekt
`--tools <tools>`	Rozdzielone przecinkami identyfikatory narzędzi, `all` lub `none`. Pomija wybor narzędzi. Identyfikatory wymienione w Obsługiwane narzędzia.
`--language <language>`	Dodaje instrukcję językową do nowej konfiguracji projektu. Odrzucane, gdy linia `store:` repozytorium wskazuje na zewnętrzny magazyn.
`--force`	Usuwa pliki ze starszych układów OpenSpec bez pytania. W przypadku uruchomień interaktywnych użytkownik jest najpierw pytany o potwierdzenie czyszczenia.
`--profile <profile>`	Nadpisuje globalny profil konfiguracji dla tego uruchomienia: `core` (standardowy zestaw przepływów pracy) lub `custom` (przepływy pracy zapisane w globalnej konfiguracji).
`--no-animation`	Wyświetla statyczny ekran powitalny zamiast animowanego.

Wynik

Każde wybrane narzędzie otrzymuje umiejętności i polecenia OpenSpec w swoim własnym katalogu:

▌ OpenSpec structure created
✔ Setup complete for Claude Code

OpenSpec Setup Complete

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

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

Restart your IDE for the new commands to take effect.

--tools none tworzy tylko openspec/config.yaml. W przypadku już zainicjalizowanego projektu init nadpisuje zainstalowane pliki w miejscu, a podsumowanie zawiera Refreshed: Claude Code z Config: openspec/config.yaml (exists).

Kody wyjścia

0: konfiguracja zakończona.
1: nieprawidłowa wartość --tools lub --profile, nieinteraktywne uruchomienie bez wykrytych narzędzi i bez --tools, lub nieprawidłowe wywołanie tylko z magazynem.

openspec update

Aktualizuje zainstalowane pliki instruktażowe OpenSpec.

bash

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

update wyszukuje narzędzia skonfigurowane przez init i porównuje ich wygenerowane pliki z wersją CLI. Gdy istnieje nowsze wydanie OpenSpec, najpierw proponuje aktualizację CLI, a następnie ponawia uruchomienie z zaktualizowaną wersją. Ustaw OPENSPEC_NO_UPDATE_CHECK=1, aby pominąć sprawdzanie.

Argumenty

Argument	Opis
`path`	Katalog projektu do zaktualizowania. Domyślnie: bieżący katalog.

Opcje

Flaga	Efekt
`--force`	Nadpisuje pliki każdego skonfigurowanego narzędzia, nawet gdy są aktualne.
`--dry-run`	Raportuje każdy plik, który aktualizacja doda, zmieni lub usunie, niczego nie zapisując. Bez sprawdzania aktualizacji CLI, bez pytań. Połącz z `--force`, aby podgląnąć wymuszoną aktualizację.
`--json`	Z `--dry-run` drukuje plan jako JSON. Bez `--dry-run` kończy działanie z kodem 1.

Podgląd aktualizacji

--dry-run planuje aktualizację, jaką wykonałoby nieinteraktywne uruchomienie: ta sama ścieżka kodu, z każdym zapisem i usunięciem zarejestrowanym zamiast wykonanym. Wymieniany jest każdy plik, którego dotknęłaby rzeczywista aktualizacja, w tym:

przenoszenie plików OpenSpec z byłego katalogu narzędzia (.kimi/ do .kimi-code/, .windsurf/ do .devin/, .codex/ i .agent/ do .agents/);
zapisywanie globalnej konfiguracji, gdy instalacja pochodzi z czasów przed profilami;
synchronizacja plików chmurowego agenta GitHub Copilot;
z --force, konfigurowanie narzędzi znalezionych tylko w starszych artefaktach i czyszczenie tych artefaktów, w tym wycofanych globalnych promptów Codex.

bash

openspec update --dry-run

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

--dry-run --json drukuje ten sam plan jako jeden dokument JSON:

json

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

Pole	Zawartość
`changes[].path`	Ścieżka względem projektu. Plik poza projektem, taki jak globalna umiejętność lub globalna konfiguracja, jest wyświetlany od katalogu domowego jako `~/...` lub jako ścieżka bezwzględna, gdy jest również poza katalogiem domowym.
`changes[].action`	`add`, `update` lub `delete`. Plik, którego nowe bajty pasują do starych, nie jest wymieniany.
`changes[].tool`	Skonfigurowane narzędzie, do którego należy plik, na przykład `claude`. Pliki należące do samego OpenSpec, a nie do jednego narzędzia — globalna konfiguracja i czyszczenie starszych artefaktów — mają wartość `openspec`.
`notes[]`	`{ code, message }` dla kroku, o który użytkownik terminala zostałby zapytany. `legacy-tool-directories`: przeniesienie, o które interaktywne uruchomienie pyta najpierw; `changes` wymienia je jako wykonane. `legacy-artifacts`: znaleziono pliki ze starszego układu OpenSpec, takie jak polecenia slash `openspec-proposal.md` lub bloki znaczników OpenSpec w `AGENTS.md`. Bez `--force` nieinteraktywna aktualizacja zostawia je w spokoju, więc `changes` również; `--dry-run --force` wymienia ich czyszczenie. Puste dla zwykłego odświeżenia.
`failures[]`	`{ tool, error }` dla każdego narzędzia, na którym rzeczywista aktualizacja by się nie powiodła, w tym zapis, którego nie można wykonać: katalog, gdzie powinien być plik, plik, gdzie powinien być katalog, lub plik lub folder bez uprawnień do zapisu. Dla tego narzędzia `changes` zatrzymuje się tam, gdzie zatrzymuje się rzeczywista aktualizacja; pozostałe narzędzia są nadal planowane. Błędów, które dysk zgłasza dopiero podczas zapisywania, takich jak brak miejsca, nie można przewidzieć.

Błąd przed planowaniem, na przykład brak katalogu OpenSpec, nadal drukuje dokładnie jeden dokument JSON: pusty plan plus tablicę status z severity, code (update_error) i message. Kod wyjścia to 1.

Wynik

Gdy pliki wszystkich narzędzi pasują do wersji CLI:

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

Use --force to refresh files anyway.

Gdy pliki narzędzia pochodzą ze starszego CLI (lub z --force, które drukuje Force updating 1 tool(s): claude):

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

✔ Updated Claude Code

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

Restart your IDE for changes to take effect.

W katalogu bez OpenSpec update odmawia:

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

Kody wyjścia

0: pliki zaktualizowane lub wszystko już aktualne.
1: brak katalogu OpenSpec w podanej ścieżce lub aktualizacja nie powiodła się.

openspec config

Wyświetla i zmienia globalną konfigurację.

bash

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

Podpolecenie	Opis
`path`	Drukuje lokalizację pliku konfiguracji.
`list`	Wyświetla wszystkie bieżące ustawienia.
`get <key>`	Drukuje jedną wartość, surową i nadającą się na skrypty.
`set <key> <value>`	Ustawia wartość, dokonując konwersji typu.
`unset <key>`	Usuwa klucz, aby zastosować jego wartość domyślną.
`reset`	Przywraca całą konfigurację do wartości domyślnych.
`edit`	Otwiera plik konfiguracji w `$EDITOR`.
`profile [preset]`	Konfiguruje tryb dostarczania i przepływy pracy.

Konfiguracja jest globalna dla Twojej maszyny, przechowywana jako JSON w miejscu wskazanym przez config path: $XDG_CONFIG_HOME/openspec/config.json, jeśli ustawione, w przeciwnym razie ~/.config/openspec/config.json (macOS, Linux) lub %APPDATA%\openspec\config.json (Windows). Każde podpolecenie akceptuje --scope <scope>, ale działa dziś tylko global. Dowolny inny zakres kończy działanie z kodem 1 z komunikatem Error: Project-local config is not yet implemented.

openspec config path

bash

openspec config path

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

openspec config list

bash

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

Opcje

Flaga	Efekt
`--json`	Drukuje obiekt konfiguracji jako JSON.

Wynik

Każde ustawienie, a następnie podsumowanie profilu oznaczające wartości jako jawnie ustawione lub domyślne:

featureFlags: {}
profile: core
delivery: both

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

openspec config get

bash

openspec config get delivery

Argumenty

Argument	Opis
`key`	Klucz do odczytu. Kropki sięgają wartości zagnieżdżonych (`featureFlags.workspaces`).

Wynik

Wartość w postaci surowej, gotowa do skryptów. Obiekty drukowane jako zwięzły JSON:

both

Kody wyjścia

0: wartość wydrukowana.
1: klucz nie ma wartości i nic nie jest drukowane.

openspec config set

bash

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

Argumenty

Argument	Opis
`key`	Klucz do zapisu, z kropkami dla wartości zagnieżdżonych.
`value`	Nowa wartość. `true`/`false` stają się wartościami logicznymi, ciągi numeryczne stają się liczbami.

Opcje

Flaga	Efekt
`--string`	Przechowuje wartość jako ciąg, pomijając konwersję typu.
`--allow-unknown`	Zezwala na klucze nieznane schematowi.

Wynik

Set featureFlags.workspaces = true

Nieznane klucze i nieprawidłowe wartości kończą się błędem z kodem 1, zanim cokolwiek zostanie zapisane:

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

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

Jeśli plik konfiguracji istnieje, ale nie zawiera obiektu JSON, czy to dlatego, że nie jest to w ogóle prawidłowy JSON, czy dlatego, że jego korzeń jest czymś innym, takim jak null lub tablica, config set, config unset i config profile kończą działanie z kodem 1 i zostawiają plik bez zmian. Napisz to za pomocą openspec config edit lub zastąp za pomocą openspec config reset --all:

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

Dopóki to nie zostanie naprawione, telemetria i sprawdzanie aktualizacji pozostają wyłączone.

openspec config unset

bash

openspec config unset delivery

Usuwa klucz, aby ponownie zastosować wartość domyślną. Klucze z wbudowanymi wartościami domyślnymi zawsze liczą się jako ustawione, więc to raportuje sukces, nawet jeśli nigdy ich nie ustawiałeś:

Unset delivery (reverted to default)

Klucz, który nie ma żadnej wartości, drukuje Key "featureFlags.nothere" was not set. Oba przypadki kończą się kodem 0. Plik konfiguracji, którego nie można przeanalizować, kończy się kodem 1, tak jak w przypadku config set.

openspec config reset

bash

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

Opcje

Flaga	Efekt
`--all`	Wymagane. Resetuje wszystko.
`-y, --yes`	Pomija pytanie o potwierdzenie.

Wynik

Configuration reset to defaults

Bez --all kończy działanie z kodem 1 i drukuje linię użycia.

Kody wyjścia

0: reset wykonany lub odpowiedziałeś nie na pytanie.
1: brak --all.
130: pytanie anulowane za pomocą Ctrl-C.

openspec config edit

bash

openspec config edit

Otwiera plik konfiguracji w $EDITOR (z powrotem do $VISUAL), tworząc go najpierw z wartościami domyślnymi, jeśli nie istnieje. Po zamknięciu edytora plik jest walidowany. Nieprawidłowy JSON lub nieprawidłowa konfiguracja kończą działanie z kodem 1.

Wartość edytora może zawierać argumenty i ścieżki w cudzysłowach, na przykład code --wait lub "/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl" -w. Jest ona dzielona na słowa bez powłoki, więc $VAR, ~ i ; są przekazywane dosłownie. Edytor, który nie może się uruchomić lub kończy działanie z kodem niezerowym, drukuje jednolinijkowy błąd i kończy działanie z kodem 1.

Bez skonfigurowanego edytora kończy działanie z kodem 1:

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

openspec config profile

bash

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

Argumenty

Argument	Opis
`preset`	Opcjonalna nazwa presetu. Istnieje tylko `core`. Wybiera podstawowe przepływy pracy i zachowuje Twoje ustawienie dostarczania.

Bez presetu interaktywny wybierak pokazuje bieżące dostarczanie i przepływy pracy, pozwala zmienić każde lub oba (dostarczanie: both, tylko umiejętności lub tylko polecenia; przepływy pracy: lista pól wyboru), drukuje różnicę, a wewnątrz projektu OpenSpec proponuje uruchomienie openspec update dla Ciebie. Poza terminalem kończy działanie z kodem 1:

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

Wynik

Zmieniona konfiguracja nie dociera do projektów, dopóki nie zostaną zaktualizowane:

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

Kody wyjścia

0: profil zapisany lub zachowałeś bieżące ustawienia.
1: nieznany preset, brak terminala lub zaoferowane openspec update nie powiodło się.
130: wybierak anulowany za pomocą Ctrl-C.

openspec list

Wyświetla zmiany lub specyfikacje (--specs).

bash

openspec list                    # aktywne zmiany, najpierw ostatnio modyfikowane
openspec list --archived         # zarchiwizowane zmiany
openspec list --all              # aktywne i zarchiwizowane zmiany
openspec list --specs            # specyfikacje z liczbą wymagań
openspec list --json             # format czytelny dla maszyn, zawiera rozwiązaną ścieżkę główną

Wiersze pochodzą z katalogów openspec/changes/ oraz openspec/specs/ w ramach rozwiązanego katalogu głównego. Domyślna lista zmian pomija katalog openspec/changes/archive/.

Opcje

Flaga	Efekt
`--specs`	Wyświetl specyfikacje zamiast zmian.
`--changes`	Wyświetl zmiany. To jest domyślne zachowanie.
`--archived`	Wyświetl tylko zarchiwizowane zmiany. Nie można łączyć z `--specs`.
`--all`	Wyświetl aktywne i zarchiwizowane zmiany. Nie można łączyć z `--specs`. Ma pierwszeństwo przed `--archived`.
`--sort <order>`	`recent` (ostatnio modyfikowane jako pierwsze) lub `name`. Domyślnie: `recent`. Specyfikacje zawsze sortowane są według nazwy.
`--json`	Zamiast tabeli wypisz dane w formacie JSON.
`--store <id>`	Użyj zarejestrowanego magazynu jako katalogu głównego OpenSpec zamiast bieżącego projektu.

Wyjście

Jeden wiersz na zmianę: nazwa, status zadań, ostatnia modyfikacja. Kolumna statusu wyświetla No tasks, 2/5 tasks lub ✓ Complete.

Changes:
  add-rate-limit     No tasks      just now

--all grupuje aktywne i zarchiwizowane zmiany pod osobnymi nagłówkami. Każda grupa używa wybranego porządku sortowania:

Changes:
  add-rate-limit     No tasks      just now

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

Specs:
  api     requirements 1

--json dodaje liczniki zadań oraz pole status przyjmujące wartości no-tasks, in-progress lub complete:

json

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

Z flagami --archived lub --all, każdy obiekt zmiany zawiera booleanowe pole archived. Połączona tablica jest sortowana zgodnie z wybranym porządkiem. Zarchiwizowana zmiana może nadal mieć status in-progress, jeśli jej plik śledzenia zadań zawiera niezaznaczone zadania. Bez tych flag struktura JSON pozostaje niezmieniona.

Pusta lista wypisuje komunikat No active changes found., No archived changes found., No changes found. lub No specs found. i kończy działanie kodem 0.

Zmiana to katalog bezpośrednio pod openspec/changes/. W przeciwieństwie do specyfikacji, zmiany nie mogą być zagnieżdżone w folderach przestrzeni nazw. Folder taki jak changes/mobile/, który jedynie otacza zmianę (changes/mobile/refresh-token/), zostanie wyświetlony ze statusem not a change, wraz z ostrzeżeniem wskazującym zagnieżdżone katalogi. Opcja --json oznacza ten wpis tablicą nested i dodaje tablicę warnings na poziomie najwyższym. Komendy show, status, validate oraz archive odrzucają taki folder z tym samym komunikatem. Aby to naprawić, przenieś zmianę wyżej i połącz przestrzeń nazw z jej nazwą:

bash

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

Kody wyjścia

0: lista została wypisana, nawet jeśli była pusta.
1: nie znaleziono katalogu głównego OpenSpec (poza projektem, bez --store).

openspec show

Wyświetla zmianę lub specyfikację w formacie Markdown lub JSON.

bash

openspec show add-rate-limit              # zmiana: wypisuje proposal.md
openspec show add-rate-limit --diff       # zmiana: dołącza różnice wymagań
openspec show api                         # specyfikacja: wypisuje spec.md
openspec show api --json --no-scenarios   # JSON specyfikacji bez tekstu scenariuszy

Bez podania nazwy polecenie show pyta o typ (zmiana lub specyfikacja), a następnie wyświetla listę elementów do wyboru. Poza interaktywnym terminalem kończy działanie kodem 1 i wypisuje bezpośrednie formy zamiast tego.

Argumenty

Argument	Opis
`item-name`	Nazwa zmiany lub specyfikacji do wyświetlenia, określona nazwą folderu (`add-rate-limit`, `api`).

Opcje

Flaga	Efekt
`--json`	Zamiast surowego Markdown wypisz strukturyzowany JSON.
`--type <change\|spec>`	Wybierz typ, gdy zmiana i specyfikacja mają tę samą nazwę.
`--no-interactive`	Nigdy nie pytaj: brakująca nazwa staje się błędem.
`--deltas-only`	JSON, zmiana: ogranicz wyjście do delt. JSON zmian jest już delta-only, więc wyjście jest identyczne jak przy zwykłym `--json`.
`--requirements-only`	Przestarzały alias dla `--deltas-only`. Wyświetla ostrzeżenie na stderr.
`--diff`	Zmiana: dołącz różnice delt dla każdego wymagania. Ignorowane z ostrzeżeniem dla specyfikacji.
`--requirements`	JSON, specyfikacja: zachowaj tekst wymagań, opróżnij tablice `scenarios`.
`--no-scenarios`	JSON, specyfikacja: to samo wyjście co `--requirements`.
`-r, --requirement <id>`	JSON, specyfikacja: wypisz jedno wymaganie na podstawie jego pozycji (od 1). Nie można łączyć z `--requirements`.
`--store <id>`	Użyj zarejestrowanego magazynu jako katalogu głównego OpenSpec zamiast bieżącego projektu.

Flagi, które nie dotyczą rozpoznanego typu, są ignorowane z ostrzeżeniem na stderr.

Wyjście

Tryb tekstowy to surowe przekierowanie: zmiana wypisuje swój plik proposal.md, a specyfikacja wypisuje spec.md.

# Add rate limiting

## Why
Niezautoryzowani klienci mogą wyczerpać API.

## Co się zmienia
- Dodaj ograniczanie szybkości per-klienta do publicznego API.

For a change, `--diff` prints the proposal first, then a `Specifications Changed (diffs)` section. ADDED requirements include their full text. REMOVED requirements retain the authored Reason and Migration. RENAMED requirements show FROM and TO. MODIFIED requirements show a unified diff against the matching main requirement.

If a MODIFIED header matches only after folding case or whitespace, the output includes both the diff and a warning that archive matching is exact. If the main spec or requirement is missing, the output warns and prints the full delta block. A MODIFIED block with no textual difference prints `(no textual changes)`.

A change with `--json` is delta-shaped:

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

Each requirement carries its name, the header text after Requirement:. This is the name archive matches MODIFIED, REMOVED and RENAMED entries against. Each scenario carries its name, the header text after Scenario:. A closing # run on either header is not part of the name.

--json --diff keeps this top-level shape. A MODIFIED delta gains a diff string, a warning string, or both. Other operations are unchanged. An empty diff string means the main and delta blocks are textually identical.

A spec with --json lists its requirements with scenarios. Requirements and scenarios carry the same name fields as change JSON:

json

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

An unknown name suggests near matches: Unknown item 'does-not-exist'. Did you mean: add-rate-limit, api?. A name that matches both a change and a spec errors and asks for --type.

Exit codes

0: item printed.
1: unknown or ambiguous name, no name outside a terminal, an out-of-range -r index, --requirements combined with -r, or a delta or main spec cannot be read for --diff.

openspec view

Prints a one-screen dashboard of specs and changes.

bash

openspec view   # project summary in one screen

view prints the dashboard once and exits. It reads no keystrokes. Changes group by task progress: Draft (no tasks yet), Active (tasks underway, with a progress bar and percent), Completed (every task checked). Specs list with requirement counts, largest first.

Options

Flag	Effect
`--store <id>`	Use a registered store as the OpenSpec root instead of the current project.

Output

OpenSpec Dashboard

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

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

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

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

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

A Task Progress summary line appears when any change has tasks underway.

Each active change also shows its schema and artifact states below its task progress bar:

text

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

Marker	Artifact state
`✓`	Its output exists. An existing tasks artifact is done even when its checklist is unfinished.
`→`	It is ready to create.
No marker	It is blocked by a missing dependency.
`(skipped)`	The change skips it.

If a workflow cannot be loaded, view prints a warning and keeps that change's task progress visible. Run openspec status --change <name> to inspect the workflow separately. After openspec view --store <id>, pass the same --store <id> to status.

Exit codes

0: dashboard printed.
1: no OpenSpec root found (outside a project, no --store).

openspec validate

Checks changes and specs for structural issues.

bash

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

With no name and no bulk flag, validate prompts you to pick items. Outside an interactive terminal it exits 1 and prints the bulk flags instead.

Arguments

Argument	What it is
`item-name`	The change or spec to validate, by folder name (`add-rate-limit`, `api`).

Options

Flag	Effect
`--all`	Validate every change and spec.
`--changes`	Validate every change.
`--specs`	Validate every spec.
`--archived`	Check task completion in archived changes, without validating their applied spec deltas.
`--strict`	Treat warnings as failures.
`--type <change\|spec>`	Pick the type when a change and a spec share a name.
`--json`	Print a structured report instead of text.
`--report <mode>`	Bulk output: `full` (default) or `findings`. Requires an explicit bulk scope.
`--concurrency <n>`	Max parallel validations in bulk runs. Default: `OPENSPEC_CONCURRENCY`, else 6.
`--no-interactive`	Never prompt: a missing or ambiguous name becomes an error.
`--store <id>`	Use a registered store as the OpenSpec root instead of the current project.

Output

Bulk runs print one status line per item, followed by any findings, and end with totals:

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

Task checkbox findings

Progress counts checkboxes and nothing else, so a task file written as plain bullets reads as zero tasks: openspec list and openspec status report no work, and openspec archive has nothing to flag as incomplete. Validate reports a WARNING on each tracked task file that lists work without a checkbox:

text

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

The warning fires only when the change's whole tracked set holds no checkbox at all. One file of prose beside a real checklist is not reported, and a change mid-authoring keeps its progress the moment a single checkbox exists. --strict turns the warning into a failure. The line number is in the --json report.

Fenced blocks, HTML comments, YAML front matter and indented code are not scanned, so a pasted terminal sample is never mistaken for a task list.

Archive merge findings

For changes, validate runs archive's merge builder against the current main specs without writing files. It reports merge conflicts, such as a missing MODIFIED target or a conflicting ADDED requirement, as INFO:

text

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

These findings appear even when validation passes, in both text and JSON output. INFO never changes the exit code, including under --strict: a missing target may belong to a sibling change that has not archived yet. Deltas already synced into the main specs follow archive's existing merge rules.

This check does not run archive's later merged-spec validation or retirement checks. A clean report does not guarantee that archive will succeed.

If the merge preflight cannot start, an INFO finding explains why. Existing validation findings and the exit code stay unchanged.

A failing item lists each issue and the fix:

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

--json prints one report for the run:

json

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

issues entries carry a level of ERROR, WARNING, or INFO.

Exit codes

0: every validated item passed, including an empty bulk scope.
1: an item failed, the report request is invalid, openspec/config.yaml cannot be read or is not valid YAML, or the run failed (for example an unknown name or no OpenSpec root). A config that cannot be read or parsed stops the run before any item is checked; with --json it is reported as a single status entry with the code unreadable_config or unparseable_config.

--report full|findings

Selects the output for an explicit bulk validation scope:

full: every item. This is the default. Explicit --report full keeps the existing output shape without adding report metadata.
findings: only items with issues, including passing items with warnings or information. Every item is still validated. Totals, strict-mode behavior, and exit codes are unchanged.

bash

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

Scopes

Flags	Findings `report.scope`
`--all`	`all`
`--changes`	`changes`
`--specs`	`specs`
`--changes --specs`, or `--all` with either flag	`all`
`--archived`	`archived`

Both explicit report modes reject a positional item name, a missing bulk scope, or archive and active scopes combined.

Findings text output

Human output: stdout prints Scope: <scope> (<count> items), then totals. With no issue-bearing items:

text

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

Issue-bearing item labels, severity labels, paths, and messages print to stderr. Active-scope failures keep the Details: rerun hint after totals. The existing root banner and progress output may precede the report.

Findings JSON output

--report findings --json prints one document. This example has two clean items:

json

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

report.kind and report.version: identify the validation-findings shape, version 1.0. There is no top-level version or items.
report.returnedItems and report.totalItems: count the returned records and all validated items, respectively.
itemFindings: complete item records whose issues array is nonempty. Includes ERROR, WARNING, and INFO issues. Each record retains id, type, valid, issues, and durationMs. Archived items use type: "change".
summary: full-run totals and per-type counts, not counts of the returned subset. An empty scope has zero totals and exits 0.
root: the same selected-root metadata as the full report.

Record preservation: returned items keep their full-report order and any additive fields on items or issues. Filtering does not rewrite messages or locations, including optional line and column fields.

Command failures: root-selection or item-discovery failures retain the existing status diagnostic and exit 1. They do not return a completed findings report or a successful empty report.

Invalid report requests

Both explicit report modes reject these requests before root selection or item discovery:

An unsupported report value, including an empty string.
A positional item name, even with a bulk flag.
No explicit bulk scope.
--archived combined with --all, --changes, or --specs.

In JSON mode, a rejected request exits 1 with only a single-element status array. It has no root or report payload:

bash

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

json

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

Human mode prints the error to stderr. A bare --report with no value is a Commander syntax error on stderr, including with --json; it does not use this diagnostic envelope.

Filter a full report externally

For a custom JSON view, filter the full report with jq or PowerShell. These script examples preserve the validation exit code and leave command-error documents intact.

In Bash with jq:

bash

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

In PowerShell:

powershell

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

These custom views keep the full report's keys but omit clean items. They are neither complete full-v1 reports nor the versioned --report findings shape.

openspec archive

Przenosi ukończoną zmianę do archiwum i aktualizuje główne specyfikacje.

bash

openspec archive add-rate-limit -y                # archiwizuj jedną zmianę, scal jej delta
openspec archive add-rate-limit -y --skip-specs   # archiwizuj bez dotykania specyfikacji

Bez podania nazwy archive prosi o wybranie zmiany. Poza interaktywnym terminalem zwraca kod wyjścia 1 i wyświetla polecenie ponownego uruchomienia.

Argumenty

Argument	Opis
`change-name`	Nazwa zmiany do archiwizacji, zgodna z nazwą folderu (`add-rate-limit`).

Opcje

Flaga	Efekt
`-y, --yes`	Odpowiada „tak” na każde potwierdzenie: aktualizacje specyfikacji, niezakończone zadania, pominięta walidacja.
`--skip-specs`	Archiwizuj bez dotykania głównych specyfikacji (zmiany infrastruktury, narzędziowe lub tylko dokumentacyjne).
`--no-validate`	Pomija walidację. `Archive` pyta o potwierdzenie wcześniej, a `-y` odpowiada za Ciebie.
`--json`	Zwraca wynik w formacie strukturalnym zamiast tekstu. Wymaga `-y` do potwierdzenia aktualizacji specyfikacji.
`--store <id>`	Używa zarejestrowanego magazynu jako katalogu głównego OpenSpec zamiast bieżącego projektu.

Wyjście

Pomyślne wykonanie raportuje status zadań, pokazuje podgląd aktualizacji specyfikacji, stosuje je oraz nadaje nazwę folderowi archiwum:

Task status: ✓ Complete

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

Folder ze zmianą jest przenoszony w całości do openspec/changes/archive/2026-08-11-add-rate-limit/, z datą dzisiejszą dodaną na początku nazwy. Każda delta zostaje scalona z odpowiednią główną specyfikacją: powyższe wymaganie ADDED zostało dopisane do pliku openspec/specs/api/spec.md. Bez flagi -y, archive pokazuje podgląd i pyta przed aktualizacją. Odrzucenie aktualizacji nadal archiwizuje zmianę, pozostawiając specyfikacje bez zmian.

Z opcją --json --yes:

json

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

Archive najpierw waliduje zmianę i odrzuca tę, która nie przejdzie walidacji:

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

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

Nieukończone zadania generują ostrzeżenia, ale nie blokują procesu. W trybie interaktywnym archive pyta, czy kontynuować, a -y powoduje kontynuację automatycznie:

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

Kody wyjścia

0: zmiana została zarchiwizowana, z lub bez aktualizacji specyfikacji.
1: walidacja nie powiodła się, nazwa zmiany jest nieznana lub wymagane było potwierdzenie, ale nie udało się odczytać odpowiedzi.

openspec new

Tworzy nowy katalog dla zmiany.

bash

openspec new change add-caching                                # tylko metadane
openspec new change add-search --goal "Users can search docs"  # zapisuje cel

Komenda new ma jedno podpolecenie: new change <name>. Tworzy katalog openspec/changes/<name>/ zawierający pojedynczy plik metadanych .openspec.yaml:

yaml

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

Artefakty (propozycja, specyfikacje, projekt, zadania) nie są tutaj inicjalizowane. Tworzysz je później, a openspec status informuje Cię, który z nich jest następny.

Argumenty

Argument	Opis
`name`	Nazwa folderu dla zmiany (`add-caching`).

Opcje

Flaga	Efekt
`--description <text>`	Tworzy również plik `README.md` w katalogu zmiany z podanym tekstem.
`--goal <text>`	Zapisuje linię `goal:` w pliku `.openspec.yaml`.
`--schema <name>`	Schema przepływu pracy dla zmiany. Domyślnie: `spec-driven`, jedyna schema dostarczana wraz z narzędziem.
`--json`	Zwraca utworzoną zmianę w formacie JSON zamiast tekstu.
`--store <id>`	Używa zarejestrowanego magazynu jako katalogu głównego OpenSpec zamiast bieżącego projektu.

Wyjście

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

Gdy nie znaleziono katalogu openspec/, new change tworzy go w bieżącym miejscu i informuje o tym:

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

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

Ta uwaga jest wypisywana do stdout razem z innymi komunikatami dla użytkownika i nigdy nie pojawia się przy użyciu --json.

Z opcją --json, w projekcie, który już posiada openspec/:

json

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

Gdy nie znaleziono katalogu openspec/ i new change go utworzył, JSON ma tę samą strukturę. root.path to katalog, z którego uruchomiono polecenie, a root.source przyjmuje wartość implicit:

json

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

Kody wyjścia

0: zmiana została utworzona.
1: zmiana już istnieje lub schema jest nieznana.

openspec status

Raportuje status ukończenia artefaktów dla jednej zmiany lub wszystkich aktywnych zmian.

bash

openspec status --change add-rate-limit          # widok listy kontrolnej
openspec status --change add-rate-limit --json   # raport strukturalny
openspec status --all                            # wszystkie aktywne zmiany
openspec status --all --json                     # jeden raport zbiorczy

Jeśli istnieją aktywne zmiany, użyj dokładnie jednej z opcji --change lub --all. Bez żadnej z nich status kończy się kodem 1 i wyświetla listę dostępnych zmian, nawet jeśli istnieje tylko jedna:

text

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

Gdy projekt nie ma aktywnych zmian, status wyświetla No active changes. Create one with: openspec new change <name> i kończy się kodem 0 nawet bez żadnej z tych flag. W przypadku --all --json ten sam pusty stan to { "changes": [], "message": "No active changes.", "root": ... }.

Opcje

Flaga	Efekt
`--change <id>`	Zmiana do zaraportowania, według nazwy folderu.
`--all`	Raportuje wszystkie aktywne zmiany, posortowane według nazwy. Nie można łączyć z `--change`.
`--schema <name>`	Zastępuje schemat automatycznie wykryty z `openspec/config.yaml`. Nieznana nazwa powoduje błąd.
`--json`	Wyświetla raport strukturalny zamiast tekstu.
`--store <id>`	Używa zarejestrowanego store jako katalogu głównego OpenSpec zamiast bieżącego projektu.

Wyjście

Lista kontrolna artefaktów schematu: [x] ukończone, [ ] gotowe do zapisania, [-] zablokowane, dopóki nie istnieją artefakty, od których zależy.

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

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

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

Wiersz Next: wskazuje jedno polecenie, które posuwa zmianę naprzód, więc openspec status wystarczy, aby ponownie podjąć zmianę w nowej sesji. Wskazuje następny gotowy artefakt, gdy planowanie nie jest jeszcze ukończone, a po utworzeniu wszystkich artefaktów planowania wskazuje openspec instructions apply:

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

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

Zawiera --store <id>, gdy rozwiązany katalog główny jest store, i wskazuje to samo polecenie, co zdanie nextSteps w JSON.

--json dodaje zależności dla każdego artefaktu, rozwiązane ścieżki plików i sugerowany następny krok. Skrócono:

json

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

W przypadku --all --json pole changes zawiera ten sam obiekt statusu dla każdej zmiany, bez pola root dla pojedynczej zmiany. Wybrany katalog główny pojawia się raz w obiekcie nadrzędnym. Ten przykład skraca pola statusu pojedynczej zmiany pokazane powyżej:

json

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

Jeśli nie można załadować jednej zmiany, przetwarzanie zbiorcze jest kontynuowane. Jej wpis zawiera changeName oraz diagnostykę status, podczas gdy pozostałe wpisy pozostają dostępne. Polecenie kończy się kodem 1, również w trybie JSON, aby CI nie zaakceptowało niekompletnego raportu jako pomyślnego. Wyjście JSON pozostaje jednym możliwym do przetworzenia dokumentem.

Kody zakończenia

0: wyświetlono każdy żądany status; pusty raport --all również kończy się kodem 0.
1: nie udało się załadować żądanej zmiany, brakuje --change lub --all, połączono obie flagi, zmiana nie istnieje albo zastąpienie schematu jest nieznane.

openspec instructions

Wyświetla instrukcje dotyczące tworzenia artefaktu, stosowania lub archiwizacji. Twój agent uruchamia to polecenie podczas przepływu pracy, aby pobrać tekst instrukcji dla następnego kroku.

bash

openspec instructions proposal --change add-rate-limit   # jak napisać jeden artefakt
openspec instructions apply --change add-rate-limit      # jak zaimplementować zmianę
openspec instructions archive --change add-rate-limit    # dane wejściowe do archiwizacji

Argumenty

Argument	Opis
`artifact`	Identyfikator artefaktu ze schematu (`proposal`, `specs`, `design`, `tasks` w `spec-driven`) albo zastrzeżone słowa `apply` i `archive`.

Opcje

Flaga	Efekt
`--change <id>`	Zmiana, dla której mają zostać wygenerowane instrukcje. Wymagane.
`--schema <name>`	Zastępuje schemat. W przeciwnym razie automatycznie wykrywany z `config.yaml`.
`--json`	Wyświetla obiekt strukturalny zamiast tekstu.
`--store <id>`	Używa zarejestrowanego store jako katalogu głównego OpenSpec zamiast bieżącego projektu.

Wyjście

Forma artefaktu wyświetla jeden blok instrukcji: zadanie, plik do zapisania, sposób jego zapisania, szablon artefaktu oraz to, co odblokowuje jego ukończenie.

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

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

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

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

apply wyświetla pliki kontekstowe, postęp zadań i instrukcję roboczą:

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

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

### Progress
1/3 complete

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

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

No project context or operation guidance configured.

Jeśli brakuje wymaganych artefaktów, apply raportuje ### ⚠️ Blocked i zamiast tego wymienia ich nazwy. archive wyświetla nazwę zmiany oraz ewentualny kontekst projektu i wskazówki operacyjne z konfiguracji. Jeśli nic nie skonfigurowano, informuje o tym i nie wyświetla nic więcej.

W przypadku --json każda forma zwraca jeden obiekt. Forma artefaktu zaczyna się:

json

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

a następnie zawiera outputPath, existingOutputPaths, pełne ciągi instruction i template, dependencies, unlocks oraz root. Forma apply zawiera contextFiles, progress, tasks, taskTrackingConfigured, state (blocked, ready, all_done) oraz instruction.

Każdy wpis tasks zawiera id, description, done, sourcePath i line. sourcePath to bezwzględna ścieżka do śledzonego pliku, z którego pochodzi zadanie. line to numer wiersza pola wyboru zadania w tym pliku, liczony od 1.

taskTrackingConfigured jest zawsze wartością logiczną: true, gdy schemat ustawia wartość apply.tracks inną niż null, nawet jeśli żaden plik nie pasuje, w przeciwnym razie false. Jeśli dopasowanego pliku śledzenia nie można odczytać, unavailableTrackingFiles zawiera jego bezwzględne path oraz reason błędu. To pole jest pomijane, gdy każdy dopasowany plik jest czytelny. Czytelne pliki nadal są uwzględniane w tasks i progress, ale state nie może być all_done, dopóki nie zostaną odczytane wszystkie dopasowane pliki.

Kody zakończenia

0: instrukcje zostały wyświetlone.
1: nieznany artefakt, nieznana zmiana, nieznany schemat lub brak --change. Każdy błąd wymienia prawidłowe wartości.

openspec templates

Wyświetla rozwiązane ścieżki szablonów dla artefaktów schematu.

bash

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

Opcje

Flaga	Działanie
`--schema <name>`	Schemat do rozwiązania. Domyślnie: `spec-driven`.
`--json`	Wyświetla mapę JSON identyfikatorów artefaktów na ścieżki szablonów.

Wyjście

Schema: spec-driven
Source: package

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

Source wskazuje, skąd schemat został rozwiązany: project (openspec/schemas/ w twoim projekcie), user (globalne nadpisanie) lub package (wbudowany w CLI). Projekt ma pierwszeństwo przed użytkownikiem, użytkownik przed pakietem.

json

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

Kody wyjścia

0: ścieżki zostały wyświetlone.
1: nieznany schemat. Błąd wyświetla listę dostępnych schematów.

openspec schemas

Wyświetla listę dostępnych schematów przepływu pracy.

bash

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

Opcje

Flaga	Działanie
`--json`	Wyjście w formacie JSON (do użycia przez agenta).

Wyjście

Available schemas:

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

Schematy z twojego projektu są oznaczone jako (project), a globalne nadpisania jako (user override).

json

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

Kody wyjścia

0: schematy zostały wyświetlone.
1: nie można odczytać listy schematów.

openspec schema

Przegląda, rozgałęzia lub tworzy schemat (eksperymentalne). Każde podpolecenie najpierw wypisuje Note: Schema commands are experimental and may change. na stderr.

bash

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

Podpolecenie	Co robi
`which`	Pokazuje, skąd schemat jest rozwiązywany.
`validate`	Sprawdza strukturę schematu i szablony.
`fork`	Kopiuje istniejący schemat do projektu w celu dostosowania.
`init`	Tworzy nowy schemat lokalny dla projektu.

Schematy są rozwiązywane z trzech lokalizacji. Pierwsze dopasowanie wygrywa:

Źródło	Lokalizacja
`project`	`openspec/schemas/` w bieżącym projekcie.
`user`	`~/.local/share/openspec/schemas/` (`XDG_DATA_HOME` i Windows `%LOCALAPPDATA%` honorowane).
`package`	Schematy dostarczane z CLI. `spec-driven` znajduje się tutaj.

openspec schema which

Pokazuje, którą kopię schematu CLI będzie używać.

bash

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

Argumenty

Argument	Czym jest
`name`	Schemat do wyszukania. Wymagany, chyba że ustawiono `--all`. Bez żadnego z nich which kończy działanie z kodem 1.

Opcje

Flaga	Efekt
`--all`	Wyświetla listę wszystkich schematów z ich źródłem rozwiązywania.
`--json`	Wypisuje rozwiązanie w formacie JSON.

Output

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

Gdy kopia o wyższym priorytecie ukrywa inną, sekcja Shadows: wyświetla listę ukrytych kopii. Z --json:

json

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

Nieznana nazwa powoduje zakończenie z kodem 1 i wyświetla listę dostępnych schematów.

openspec schema validate

Sprawdza strukturę schematu i szablony.

bash

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

Weryfikuje, czy schema.yaml istnieje i jest poprawny składniowo, czy struktura odpowiada formatowi schematu, czy plik szablonu każdego artefaktu istnieje w katalogu templates/ schematu oraz czy graf zależności nie zawiera cykli ani nieznanych referencji, w tym w apply.requires. Wartość apply.tracks, która nie jest dokładnie równa wartości generates żadnego artefaktu, wypisuje linię warning:, ale nie powoduje niepowodzenia walidacji, ponieważ OpenSpec wtedy nie może określić, do postępu którego artefaktu należy ten plik.

Opcje

Flaga	Efekt
`--json`	Wypisuje ustrukturyzowany raport zamiast tekstu.
`--verbose`	Wypisuje każdy krok walidacji.

Output

✓ Schema 'spec-driven' is valid

Bez nazwy każdy schemat projektu otrzymuje jedną linię pod nagłówkiem Validation Results:. Schemat z błędami wyświetla listę problemów, a uruchomienie kończy się kodem 1:

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

openspec schema fork

Kopiuje istniejący schemat do projektu, aby można go było dostosować.

bash

openspec schema fork spec-driven my-flow

Argumenty

Argument	Czym jest
`source`	Schemat do skopiowania, z dowolnej lokalizacji źródłowej.
`name`	Nazwa kopii. Kebab-case (`my-workflow`). Domyślnie: `<source>-custom`.

Opcje

Flaga	Efekt
`--force`	Nadpisuje istniejący schemat docelowy.
`--json`	Wypisuje wynik w formacie JSON.

Output

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

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

Rozgałęzienie trafia do openspec/schemas/, a pole name: w jego schema.yaml jest przepisywane na nową nazwę:

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

Istniejące miejsce docelowe jest błędem, chyba że przekazano --force. Rozgałęzienie zachowujące nazwę źródła ukrywa oryginał.

openspec schema init

Tworzy nowy schemat lokalny dla projektu z szablonami startowymi.

bash

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

Bez --description i --artifacts w interaktywnym terminalu init pyta o opis, listę artefaktów i czy ustawić schemat jako domyślny dla projektu. Poza terminalem używa domyślnych wartości poniżej.

Argumenty

Argument	Czym jest
`name`	Nazwa nowego schematu. Kebab-case (`my-workflow`).

Opcje

Flaga	Efekt
`--description <text>`	Opis schematu. Domyślnie: `Custom workflow schema for <name>`.
`--artifacts <list>`	Lista identyfikatorów artefaktów oddzielonych przecinkami z `proposal`, `specs`, `design`, `tasks`. Domyślnie: wszystkie cztery.
`--default`	Zapisuje `schema: <name>` do istniejącego `openspec/config.yaml` lub `openspec/config.yml`. Tworzy `openspec/config.yaml`, jeśli żaden nie istnieje. Nowe zmiany używają tego schematu.
`--no-default`	Pomija pytanie o domyślny schemat.
`--force`	Nadpisuje istniejący schemat o tej samej nazwie.
`--json`	Wypisuje wynik w formacie JSON.

Tworzenie schematu i aktualizacja konfiguracji --default stanowią jedną operację. Jeśli OpenSpec nie może zweryfikować ani zapisać konfiguracji, pozostawia zarówno konfigurację, jak i istniejący schemat bez zmian.

Output

✔ Created schema 'my-schema'

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

Artifacts: proposal, tasks

Układ na dysku:

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

schema.yaml łączy wybrane artefakty z ich zależnościami. Gdy dołączono tasks, otrzymuje również fazę apply, która śledzi tasks.md. Użyj schematu przez openspec new --schema my-schema.

openspec store

Tworzy i zarządza magazynami: niezależnymi repozytoriami OpenSpec zarejestrowanymi na Twojej maszynie.

bash

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

Rejestracje znajdują się w rejestrze per maszyna: ~/.local/share/openspec/stores/registry.yaml, lub $XDG_DATA_HOME/openspec/stores/registry.yaml, gdy ustawiono XDG_DATA_HOME. Każde podpolecenie przyjmuje --json, aby wypisać ustrukturyzowany raport zamiast tekstu. Uruchomienie openspec store z brakującym lub nieznanym podpoleceniem powoduje zakończenie z kodem 1 i wyświetla listę podpoleceń.

Podpolecenie	Co robi
`setup [id]`	Tworzy folder magazynu i rejestruje go.
`register [path]`	Rejestruje istniejący folder magazynu.
`unregister <id>`	Zapomina rejestrację. Folder pozostaje na dysku.
`remove <id>`	Zapomina rejestrację i usuwa folder.
`list` (alias `ls`)	Wyświetla listę zarejestrowanych magazynów.
`doctor [id]`	Sprawdza rejestrację, metadane i stan Git dla zarejestrowanych magazynów.

openspec store setup

Tworzy folder magazynu i rejestruje go.

bash

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

W interaktywnym terminalu setup pyta o brakującą nazwę i lokalizację oraz prosi o potwierdzenie przed utworzeniem czegokolwiek. Poza terminalem brak nazwy lub --path powoduje zakończenie z kodem 1 z podpowiedzią jaką flagę przekazać. Ponowne uruchomienie setup dla zarejestrowanego magazynu zgłasza Registry: already registered.

Setup kończy działanie z kodem 1 i błędem store_setup_inside_git_repo, gdy --path znajduje się wewnątrz innego repozytorium Git, ponieważ inicjalizacja magazynu tam powodziłaby zagnieżdżenie jednego repozytorium w drugim. --no-init-git nie tworzy repozytorium, więc pomija to sprawdzenie. Użyj go, aby utrzymać magazyn w ~/openspec/<id>, gdy Twój katalog domowy sam jest repozytorium Git, na przykład repozytorium dotfiles.

Argumenty

Argument	Czym jest
`id`	Nazwa magazynu. Staje się identyfikatorem przekazywanym do `--store`.

Opcje

Flaga	Efekt
`--path <path>`	Folder, w którym magazyn ma się znajdować (`~` jest rozwijany).
`--init-git`	Inicjalizuje repozytorium Git z początkowym commitem. Domyślnie.
`--no-init-git`	Pomija wszystkie akcje Git: brak inicjalizacji, brak początkowego commita.
`--remote <url>`	Kanoniczne źródło klonowania zapisywane w `store.yaml`.

Output

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

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

--json raportuje, co zostało utworzone i gdzie zostało zarejestrowane:

json

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

openspec store register

Rejestruje istniejący folder magazynu, na przykład sklonowany magazyn kolegi z zespołu.

bash

openspec store register ~/stores/design-system

Folder musi zawierać zdrowy katalog główny openspec/. Gdy .openspec-store/store.yaml jest obecny, register ponownie używa zapisanego identyfikatora. Bez niego register pyta przed utworzeniem tych metadanych. Poza interaktywnym terminalem przekaż --yes. Maszyna może zarejestrować jedną kopię roboczą na identyfikator magazynu. Druga ścieżka pod tym samym identyfikatorem lub ta sama ścieżka pod drugim identyfikatorem powoduje zakończenie z kodem 1.

Argumenty

Argument	Czym jest
`path`	Folder magazynu do zarejestrowania (`~` jest rozwijany). Wymagany.

Opcje

Flaga	Efekt
`--id <id>`	Identyfikator magazynu. Domyślnie metadane lub nazwa folderu.
`--yes`	Potwierdza utworzenie metadanych tożsamości magazynu dla zdrowego katalogu głównego OpenSpec.

Output

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

--json wypisuje ten sam kształt dokumentu co store setup --json.

openspec store unregister

Zapomina rejestrację. Folder pozostaje na dysku.

bash

openspec store unregister design-system

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

openspec store remove

Zapomina rejestrację i usuwa folder.

bash

openspec store remove design-system --yes

W trybie interaktywnym remove pyta przed usunięciem. Z --json lub poza interaktywnym terminalem usunięcie wymaga --yes:

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

Remove kończy działanie z kodem 1 i nie usuwa nic, gdy folder nie zawiera pasujących metadanych magazynu lub gdy zawiera inny zarejestrowany magazyn (na przykład magazyn dołączony jako submoduł Git). W takim przypadku błąd to store_remove_contains_registered_store: najpierw uruchom openspec store unregister <nested-id> lub openspec store unregister <id>, aby zapomnieć magazyn bez usuwania plików.

Opcje

Flaga	Efekt
`--yes`	Potwierdza usunięcie lokalnego folderu magazynu.

Output

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

openspec store list

Wyświetla listę zarejestrowanych magazynów. ls jest aliasem.

bash

openspec store list

OpenSpec stores (2)

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

Gdy nic nie jest zarejestrowane, list wypisuje No stores registered. oraz polecenia setup i register do uruchomienia następnie.

openspec store doctor

Sprawdza rejestrację, metadane i stan Git dla zarejestrowanych magazynów.

bash

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

Output

Store doctor

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

Kody wyjścia

0: raport został wypisany, nawet gdy magazyn zgłasza problemy.
1: raport nie mógł zostać uruchomiony (na przykład nieznany identyfikator magazynu).

openspec doctor

Raportuje kondycję relacji dla ustalonego katalogu głównego OpenSpec.

bash

openspec doctor                       # najbliższy katalog główny openspec/ powyżej bieżącego katalogu roboczego
openspec doctor --store team-context  # zarejestrowany magazyn jako katalog główny

Doctor działa w trybie tylko do odczytu: nigdy nie klonuje, nie synchronizuje ani niczego nie naprawia. Raportuje, czy katalog główny jest sprawny oraz czy każde odwołanie zadeklarowane w openspec/config.yaml można odnaleźć na tej maszynie. Jeśli nie ma katalogu głównego powyżej bieżącego katalogu roboczego i nie podano --store, polecenie kończy działanie kodem 1 i wymienia nazwy zarejestrowanych magazynów.

Opcje

Flaga	Działanie
`--store <id>`	Używa zarejestrowanego magazynu jako katalogu głównego OpenSpec zamiast bieżącego projektu.
`--json`	Wypisuje raport kondycji w formacie JSON.

Dane wyjściowe

Doctor

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

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

Z opcją --store katalogiem głównym jest magazyn, a raport zawiera dodatkową linię dotyczącą magazynu:

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

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

References
  (none declared)

json

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

Kody wyjścia

0: raport został wypisany, również wtedy, gdy wyświetla problemy.
1: nie udało się ustalić katalogu głównego (brak openspec/ powyżej bieżącego katalogu roboczego i brak --store) lub podano nieznany identyfikator --store.

openspec context

Wypisuje kontekst roboczy dla ustalonego katalogu głównego OpenSpec: sam katalog główny oraz każdy odwoływany magazyn zadeklarowany w openspec/config.yaml, każdy wraz z poleceniem pobrania.

bash

openspec context                       # najbliższy katalog główny openspec/ powyżej bieżącego katalogu roboczego
openspec context --store team-context  # zarejestrowany magazyn jako katalog główny
openspec context --json                # brief dla agenta

Odwołania, których nie można odnaleźć na tej maszynie, trafiają do sekcji Not available on this machine, każde wraz ze wskazówką, jak je naprawić.

Opcje

Flaga	Działanie
`--store <id>`	Używa zarejestrowanego magazynu jako katalogu głównego OpenSpec zamiast bieżącego projektu.
`--json`	Wypisuje brief dla agenta w formacie JSON.
`--code-workspace <path>`	Zapisuje dodatkowo plik obszaru roboczego VS Code dla tego zestawu.
`--force`	Nadpisuje istniejący plik `--code-workspace`.

Dane wyjściowe

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

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

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

Z opcją --store magazyn stanowi cały zestaw:

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

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

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

json

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

Zapisywanie pliku obszaru roboczego

--code-workspace zapisuje plik obszaru roboczego VS Code pod wskazaną ścieżką: jeden folder dla katalogu głównego oraz jeden folder ref:<id> dla każdego dostępnego odwoływanego magazynu. Niedostępne odwołania są pomijane i wymieniane w linii podsumowania (Wrote /Users/you/projects/my-app/openspec.code-workspace (2 folders)). Podsumowanie jest wypisywane na stderr, dzięki czemu stdout opcji --json pozostaje pojedynczym dokumentem JSON. Jeśli plik już istnieje, polecenie kończy działanie kodem 1, chyba że podasz --force.

json

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

Kody wyjścia

0: raport został wypisany.
1: nie udało się ustalić katalogu głównego (brak openspec/ powyżej bieżącego katalogu roboczego i brak --store) lub odmówiono zapisu pliku --code-workspace.

openspec workset

Tworzy, przechowuje i otwiera osobiste widoki robocze. Workset to zapisana, nazwana lista folderów, z których pracujesz razem.

bash

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

Podkomenda	Co robi
`create [name]`	Tworzy i zapisuje nazwany widok roboczy wybranych folderów.
`list`, `ls`	Pokazuje zapisane worksety wraz z ich składowymi.
`open <name>`	Otwiera zapisany workset w Twoim narzędziu (oknie edytora lub sesji agenta).
`remove <name>`	Usuwa zapisany workset (foldery składowe nigdy nie są dotykane).

Workset jest czysto lokalny:

Jego stan znajduje się w jednym folderze: ~/.local/share/openspec/worksets/ ($XDG_DATA_HOME/openspec/worksets/ gdy ustawione; %LOCALAPPDATA%\openspec\worksets\ w systemie Windows).
Nic nie jest zapisywane w folderach składowych, a nic nie jest commitowane ani udostępniane.
Usunięcie tego jednego folderu usuwa każdy ślad.

openspec workset create

Zapisuje nazwany widok roboczy folderów.

bash

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

W interaktywnym terminalu create pyta o to, czego nie dostarczyły flagi: nazwę, foldery po jednym, narzędzie, a następnie oferuje otwarcie worksetu teraz. Poza terminalem brak nazwy lub składowego jest błędem. Nazwa, która jest już zapisana, zawsze jest błędem. Usuń ją najpierw.

Argumenty

Argument	Co to jest
`name`	Nazwa worksetu. Kebab-case: małe litery, cyfry, pojedyncze myślniki. Wymagane poza interaktywnym terminalem.

Opcje

Flaga	Działanie
`--member <member>`	Folder składowy jako `<path>` lub `<name>=<path>`, można powtarzać. Pierwszy jest głównym. Ścieżka musi być istniejącym folderem, a etykieta domyślnie przyjmuje nazwę folderu.
`--tool <id>`	Preferowane narzędzie do otwarcia tego worksetu. Wbudowane id: `code` (VS Code), `cursor` (Cursor). `claude` i `codex` są tymczasowo wyłączone.
`--json`	Wypisuje zapisany workset jako JSON.

Wyjście

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

openspec workset list

Pokazuje zapisane worksety wraz z ich składowymi, posortowane po nazwie.

bash

openspec workset list   # alias: ls

Opcje

Flaga	Działanie
`--json`	Wypisuje worksety jako JSON.

Wyjście

Jeden blok na workset: nazwa, jego narzędzie (jeśli ma jedno), a następnie jeden wiersz name path na każdy składowy. Gdy nic nie jest zapisane, list wypisuje No worksets saved. Create one with: openspec workset create.

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

Z --json:

json

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

openspec workset open

Otwiera zapisany workset w Twoim narzędziu. Narzędzia edytora (code, cursor) otrzymują wygenerowany plik .code-workspace. Otwiera się okno i polecenie kończy się. Narzędzia agenta CLI (claude, codex) przejęłyby ten terminal z każdym dołączonym składowym. Są tymczasowo wyłączone podczas przerabiania tego przepływu, więc worksety otwierają się w IDE na razie.

bash

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

Argumenty

Argument	Co to jest
`name`	Workset do otwarcia.

Opcje

Flaga	Działanie
`--tool <id>`	Otwórz tym narzędziem tylko raz.

Bez --tool i bez zapisanego narzędzia, open prosi o wybranie zainstalowanego narzędzia. Poza interaktywnym terminalem kończy się kodem 1 zamiast tego.

Folder składowy, który już nie istnieje, jest pomijany z ostrzeżeniem. Gdy główny nie istnieje, następny dostępny składowy staje się głównym dla tego otwarcia. Gdy nie istnieje żaden folder składowy, otwarcie kończy się niepowodzeniem.
--json jest odrzucane: open oddaje terminal narzędziu i nie ma trybu JSON.
Gdy uruchomienie się nie powiedzie, błąd kończy się informacjami o ręcznym uruchomieniu: ścieżką do pliku obszaru roboczego i listą składowych.

Kody wyjścia

Kod wyjścia odzwierciedla narzędzie: polecenie kończy się własnym kodem wyjścia narzędzia, a sygnał staje się 128+n (130 po Ctrl-C).
1: nieznany workset, brak dostępnego folderu składowego lub brak używalnego narzędzia.

openspec workset remove

Usuwa zapisany workset i jego wygenerowany plik .code-workspace. Foldery składowe nigdy nie są dotykane.

bash

openspec workset remove checkout --yes

W interaktywnym terminalu remove pokazuje workset i prosi o potwierdzenie. Z --json, lub poza terminalem, wymaga --yes i kończy się kodem 1 bez niego.

Opcje

Flaga	Działanie
`--yes`	Potwierdź usunięcie nieinteraktywnie.
`--json`	Wypisuje usunięcie jako JSON.

Wyjście

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

openspec version

Raportuje wersję uruchomionego OpenSpec oraz sposób instalacji tej kopii.

bash

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

Bez --check to polecenie jest lokalne i nie kontaktuje się z rejestrem. Działa poza projektem OpenSpec. Istniejąca flaga openspec --version pozostaje najkrótszą formą i wypisuje sam numer wersji.

Opcje

Flaga	Działanie
`--json`	Wypisuje jeden wersjonowany dokument JSON zamiast tekstu.
`--check`	Sprawdza skonfigurowany rejestr pod kątem nowszego wydania.

Wyjście

Dla globalnej instalacji npm:

text

OpenSpec 1.13.2 (npm, global)

Zakres instalacji to global, project, temporary dla efemerycznego uruchomiacza takiego jak npx, source dla check-outu, lub standalone dla samodzielnej instalacji. OpenSpec pomija szczegóły, których nie może zidentyfikować, zamiast zgadywać.

--json zachowuje nieznane szczegóły jako jawne wartości null:

json

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

Z --check, dostępna aktualizacja dodaje najnowszą wersję i polecenie, gdy OpenSpec może zidentyfikować bezpieczne polecenie dla tej instalacji:

text

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

json

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

Wartości statusu aktualizacji:

Status	Znaczenie
`available`	Rejestr zwrócił bezpieczną wersję nowszą niż wersja uruchomiona.
`current`	Sprawdzenie zakończone, nie znaleziono nowszej wersji.
`disabled`	Istniejące ustawienie prywatności lub sprawdzania aktualizacji zablokowało dostęp do rejestru. `latest` jest `null`.
`offline`	Rejestr był niedostępny lub zwrócił nieuzużywalną odpowiedź. `latest` jest `null`.

Dla instalacji samodzielnej poleceniem aktualizacji jest openspec install.

DO_NOT_TRACK, rezygnacje z telemetrii, OPENSPEC_NO_UPDATE_CHECK, wykrywanie CI oraz odrzucone nadpisania rejestru nie-HTTPS wyłączają sprawdzanie. Sprawdzanie wyłączone i offline nadal kończy się kodem 0, ponieważ dostępność aktualizacji ma charakter informacyjny. To polecenie nigdy nie aktualizuje OpenSpec; canSelfUpgrade tylko donosi, czy istniejąca ścieżka openspec update mogłaby bezpiecznie zaktualizować tę kopię.

Kody wyjścia

0: wydrukowano raport lokalny, w tym sprawdzanie aktualizacji wyłączone lub offline.
1: składnia polecenia była nieprawidłowa, np. nieobsługiwana opcja --upgrade.

openspec install

Instaluje samodzielny openspec. Uruchom go z instalacji npm lub Homebrew, aby go przełączyć, lub z instalacji samodzielnej, aby uaktualnić go w miejscu.

bash

openspec install          # najnowsze wydanie
openspec install 1.15.0   # konkretne wydanie

Uruchamia skrypt instalacyjny, który wybiera najnowsze wydanie, którego pliki są wszystkie dołączone, oraz plik dla twojej maszyny, i sprawdza go względem SHA256SUMS tego wydania:

Z menedżera pakietów: instaluje do ~/.local/bin (Windows: %LOCALAPPDATA%\Programs\openspec) i wyświetla polecenie, które usuwa starą kopię, na przykład npm uninstall -g @fission-ai/openspec. Nigdy nie usuwa tej kopii samodzielnie.
Z instalacji samodzielnej: zastępuje uruchomiony plik w jego miejscu, pod własną nazwą.

Następnie informuje, która kopia openspec teraz działa, ponieważ kopia z menedżera pakietów wcześniej w twoim PATH nadal działa, dopóki jej nie usuniesz.

Argumenty

Argument	Co to jest
`version`	Wydanie do zainstalowania, na przykład `1.15.0`. Opcjonalne; domyślnie najnowsze.

OPENSPEC_INSTALL_DIR i OPENSPEC_INSTALL_NAME wybierają inny folder lub nazwę pliku.

Kody wyjścia

0: zainstalowano.
1: wersja nie jest wersją wydania lub pobieranie lub instalacja nie powiodły się. Twoja obecna kopia pozostaje bez zmian.

openspec feedback

Przesyła opinię o OpenSpec.

bash

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

CLI zgłasza twoją wiadomość jako issue na GitHubie w repozytorium Fission-AI/OpenSpec za pośrednictwem twojego gh CLI. Tytuł staje się Feedback: <wiadomość>. Treść używa nagłówków formularza błędu: twoja wiadomość pod What happened, twój tekst --body pod Details oraz sekcja Minimal steps to reproduce prosząca o dodanie kroków, ponieważ CLI nie może ich wypełnić. Stopka dodaje wersję CLI, platformę i znacznik czasu. Issue otrzymuje etykietę feedback. Jeśli repozytorium nie definiuje tej etykiety, CLI ponawia próbę bez niej i informuje o tym.

Argumenty

Argument	Co to jest
`message`	Jednowierszowe podsumowanie. Staje się tytułem issue. Wymagane.

Opcje

Flaga	Efekt
`--body <text>`	Dłuższy opis dodawany do treści issue.

Dane wyjściowe

Po sukcesie:

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

Bez zainstalowanego gh lub z gh niezalogowanym, nic nie jest przesyłane. CLI wyświetla twoje sformatowane opinie między znacznikami --- FORMATTED FEEDBACK ---, a następnie link, który otwiera formularz zgłaszania błędu z wypełnionym tytułem, tym, co się stało (twoja wiadomość i tekst --body), wersją CLI i środowiskiem (platformą i wersją Node). Reszty formularza dokonujesz w przeglądarce. Ścieżka niezalogowana dodaje To auto-submit in the future: gh auth login.

Kody wyjścia

0: issue utworzone lub zadziałał fallback ręcznego przesyłania (brak gh lub gh niezalogowane).
1: nie podano wiadomości.
Własny kod gh: gh nie powiódł się po uwierzytelnieniu (sieć, limit szybkości, wyłączone issues). CLI najpierw ponownie wyświetla twoje opinie i URL ręcznego przesyłania.

openspec completion

Instaluje lub generuje uzupełnianie powłoki.

bash

openspec completion install        # wykryj powłokę, zainstaluj, podłącz konfigurację
openspec completion generate zsh   # wyświetl skrypt na stdout

Obsługiwane powłoki: zsh, bash, fish, powershell. Każde polecenie podrzędne przyjmuje opcjonalny argument powłoki. Pomiń go, a CLI wykryje twoją powłokę ze środowiska.

Polecenie podrzędne	Co robi
`generate [shell]`	Wyświetla skrypt uzupełniania na stdout.
`install [shell]`	Zapisuje skrypt i konfiguruje plik startowy powłoki.
`uninstall [shell]`	Usuwa skrypt i blok konfiguracyjny.

Zainstalowane z Nix, uzupełnianie jest już na miejscu: pakiet flake dostarcza skrypty Bash, Fish i Zsh w standardowych lokalizacjach, więc install nie jest potrzebne (Instalacja).

openspec completion generate

Wyświetla skrypt i niczego nie zapisuje.

#compdef openspec

# Skrypt uzupełniania Zsh dla OpenSpec CLI
# Auto-generowany - nie edytuj ręcznie

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

openspec completion install

Zapisuje skrypt i edytuje konfigurację powłoki. Edycje konfiguracji znajdują się między znacznikami # OPENSPEC:START i # OPENSPEC:END. Istniejący skrypt jest najpierw kopiią zapasową (kopia .backup-<timestamp>).

Powłoka	Lokalizacja skryptu	Edytowana konfiguracja
zsh	`~/.zsh/completions/_openspec`	`$ZDOTDIR/.zshrc` gdy `ZDOTDIR` jest ścieżką bezwzględną, w przeciwnym razie `~/.zshrc`
bash	`~/.local/share/bash-completion/completions/openspec`	`~/.bashrc`
fish	`~/.config/fish/completions/openspec.fish`	Brak: fish automatycznie go ładuje.
powershell	`OpenSpecCompletion.ps1` obok twojego profilu	`$PROFILE`

Z zainstalowanym Oh My Zsh, skrypt trafia do $ZSH_CUSTOM/completions/_openspec (domyślnie ~/.oh-my-zsh/custom/completions/_openspec).

Względne lub z prefiksem ~ ZDOTDIR jest ignorowane, a edytowane jest ~/.zshrc. Ponowne uruchomienie instalacji, gdy skrypt jest już aktualny, nadal dodaje blok do .zshrc, który zsh czyta.

Opcje

Flaga	Efekt
`--verbose`	Wyświetla również zainstalowaną ścieżkę, wszelkie ścieżki kopii zapasowej i który plik konfiguracyjny był edytowany.

Dane wyjściowe

✓ Completion script installed and .zshrc configured successfully

Restart your shell or run: exec zsh

openspec completion uninstall

Usuwa skrypt i oznaczony blok konfiguracyjny. Pyta przed dotknięciem konfiguracji (domyślnie: Nie).

Dla zsh, czyści .zshrc, który instaluje edycje, a także ~/.zshrc, gdy starsza instalacja zostawiła tam blok pod ZDOTDIR. Jeśli blok nie może zostać usunięty, odinstalowanie nazywa plik i kończy działanie z kodem 1.

Opcje

Flaga	Efekt
`-y, --yes`	Pomija monity o potwierdzenie.

Dane wyjściowe

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

Kody wyjścia

0: skrypt wygenerowany, zainstalowany lub usunięty. Anulowane odinstalowanie również kończy działanie z kodem 0.
1: powłoka nieobsługiwana lub niewykryta lub krok instalacji lub odinstalowania nie powiódł się.

openspec change

Przestarzała forma rzeczownikowa show, list i validate. Każde uruchomienie ostrzega i wskazuje polecenia z czasownikiem na początku, a następnie i tak je uruchamia:

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

Przestarzałe	Użyj zamiast
`openspec change show <name>`	`openspec show <name>`
`openspec change list`	`openspec list`
`openspec change validate <name>`	`openspec validate <name>` (wszystkie zmiany: `openspec validate --changes`)

Sekcje z czasownikiem na początku dokumentują flagi.

openspec spec

Przestarzała forma rzeczownikowa show, list i validate. Każde uruchomienie ostrzega i wskazuje polecenia z czasownikiem na początku, a następnie i tak je uruchamia:

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

Przestarzałe	Użyj zamiast
`openspec spec show <id>`	`openspec show <id>`
`openspec spec list`	`openspec list --specs`
`openspec spec validate <id>`	`openspec validate <id>` (wszystkie specyfikacje: `openspec validate --specs`)

Sekcje z czasownikiem na początku dokumentują flagi.

openspec init ​

openspec update ​

openspec config ​

openspec config path ​

openspec config list ​

openspec config get ​

openspec config set ​

openspec config unset ​

openspec config reset ​

openspec config edit ​

openspec config profile ​

openspec list ​

openspec show ​

openspec view ​

openspec validate ​

--report full|findings ​

Findings text output ​

Findings JSON output ​

Invalid report requests ​

Filter a full report externally ​

openspec archive ​

openspec new ​

openspec status ​

openspec instructions ​

openspec templates ​

openspec schemas ​

openspec schema ​

openspec schema which ​

openspec schema validate ​

openspec schema fork ​

openspec schema init ​

openspec store ​

openspec store setup ​

openspec store register ​

openspec store unregister ​

openspec store remove ​

openspec store list ​

openspec store doctor ​

openspec doctor ​

openspec context ​

openspec workset ​

openspec workset create ​

openspec workset list ​

openspec workset open ​

openspec workset remove ​

openspec version ​

openspec install ​

openspec feedback ​

openspec completion ​

openspec completion generate ​

openspec completion install ​

openspec completion uninstall ​

openspec change ​

openspec spec ​

openspec init

openspec update

openspec config

openspec config path

openspec config list

openspec config get

openspec config set

openspec config unset

openspec config reset

openspec config edit

openspec config profile

openspec list

openspec show

openspec view

openspec validate

--report full|findings

Findings text output

Findings JSON output

Invalid report requests

Filter a full report externally

openspec archive

openspec new

openspec status

openspec instructions

openspec templates

openspec schemas

openspec schema

openspec schema which

openspec schema validate

openspec schema fork

openspec schema init

openspec store

openspec store setup

openspec store register

openspec store unregister

openspec store remove

openspec store list

openspec store doctor

openspec doctor

openspec context

openspec workset

openspec workset create

openspec workset list

openspec workset open

openspec workset remove

openspec version

openspec install

openspec feedback

openspec completion

openspec completion generate

openspec completion install

openspec completion uninstall

openspec change

openspec spec