Skip to content

Referencja CLI

CLI OpenSpec (openspec) udostępnia polecenia terminalowe do konfiguracji projektu, walidacji, inspekcji stanu i zarządzania. Polecenia te uzupełniają komendy AI slash (takie jak /opsx:propose) opisane w sekcji Komendy.

Podsumowanie

KategoriaPoleceniaPrzeznaczenie
Konfiguracjainit, updateInicjalizacja i aktualizacja OpenSpec w projekcie
Przeglądanielist, view, showEksploracja zmian i specyfikacji
WalidacjavalidateSprawdzanie zmian i specyfikacji pod kątem problemów
Cykl życiaarchiveFinalizacja zakończonych zmian
Przepływ pracystatus, instructions, templates, schemasWsparcie przepływu pracy opartego na artefaktach
Schematyschema init, schema fork, schema validate, schema whichTworzenie i zarządzanie niestandardowymi przepływami pracy
KonfiguracjaconfigPrzeglądanie i modyfikacja ustawień
Narzędziafeedback, completionInformacje zwrotne i integracja z powłoką

Polecenia dla ludzi a polecenia dla agentów

Większość poleceń CLI jest zaprojektowana do użycia przez ludzi w terminalu. Niektóre polecenia obsługują również użycie przez agenty/skrypty za pomocą wyjścia w formacie JSON.

Polecenia tylko dla ludzi

Te polecenia są interaktywne i przeznaczone do użytku w terminalu:

PolecenieCel
openspec initInicjalizacja projektu (interaktywne monity)
openspec viewInteraktywny panel sterowania
openspec config editOtwórz konfigurację w edytorze
openspec feedbackWyślij opinię przez GitHub
openspec completion installZainstaluj uzupełnienia powłoki

Polecenia kompatybilne z agentami

Te polecenia obsługują wyjście --json do programistycznego użycia przez agentów AI i skrypty:

PolecenieUżycie przez ludziUżycie przez agentów
openspec listPrzeglądanie zmian/specyfikacji--json dla ustrukturyzowanych danych
openspec show <element>Odczyt treści--json do parsowania
openspec validateSprawdzanie problemów--all --json do masowej walidacji
openspec statusPodgląd postępu artefaktów--json dla ustrukturyzowanego statusu
openspec instructionsUzyskanie kolejnych kroków--json dla instrukcji dla agenta
openspec templatesZnalezienie ścieżek szablonów--json do rozwiązywania ścieżek
openspec schemasLista dostępnych schematów--json do odkrywania schematów

Opcje globalne

Te opcje działają ze wszystkimi poleceniami:

OpcjaOpis
--version, -VWyświetl numer wersji
--no-colorWyłącz kolorowe wyjście
--help, -hWyświetl pomoc dla polecenia

Polecenia konfiguracyjne

openspec init

Inicjalizuje OpenSpec w Twoim projekcie. Tworzy strukturę folderów i konfiguruje integracje z narzędziami AI.

Domyślne zachowanie używa globalnych ustawień domyślnych: profil core, dostarczanie both, przepływy pracy propose, explore, apply, archive.

openspec init [ścieżka] [opcje]

Argumenty:

ArgumentWymaganyOpis
ścieżkaNieKatalog docelowy (domyślnie: bieżący katalog)

Opcje:

OpcjaOpis
--tools <lista>Konfiguruj narzędzia AI w sposób nieinteraktywny. Użyj all, none lub listy oddzielonej przecinkami
--forceAutomatycznie usuń przestarzałe pliki bez monitowania
--profile <profil>Nadpisz globalny profil dla tego uruchomienia inicjalizacji (core lub custom)

--profile custom używa przepływów pracy aktualnie wybranych w globalnej konfiguracji (openspec config profile).

Obsługiwane identyfikatory narzędzi (--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

Przykłady:

bash
# Interaktywna inicjalizacja
openspec init

# Inicjalizacja w określonym katalogu
openspec init ./mój-projekt

# Nieinteraktywna: konfiguracja dla Claude i Cursor
openspec init --tools claude,cursor

# Konfiguracja dla wszystkich obsługiwanych narzędzi
openspec init --tools all

# Nadpisanie profilu dla tego uruchomienia
openspec init --profile core

# Pominięcie monitów i automatyczne usunięcie przestarzałych plików
openspec init --force

Co tworzy:

openspec/
├── specs/              # Twoje specyfikacje (źródło prawdy)
├── changes/            # Proponowane zmiany
└── config.yaml         # Konfiguracja projektu

.claude/skills/         # Umiejętności Claude Code (jeśli wybrano claude)
.cursor/skills/         # Umiejętności Cursor (jeśli wybrano cursor)
.cursor/commands/       # Polecenia OPSX dla Cursor (jeśli dostarczanie obejmuje polecenia)
... (inne konfiguracje narzędzi)

openspec update

Aktualizuje pliki instrukcji OpenSpec po uaktualnieniu CLI. Ponownie generuje pliki konfiguracyjne narzędzi AI, używając Twojego aktualnego globalnego profilu, wybranych przepływów pracy i trybu dostarczania.

openspec update [ścieżka] [opcje]

Argumenty:

ArgumentWymaganyOpis
ścieżkaNieKatalog docelowy (domyślnie: bieżący katalog)

Opcje:

OpcjaOpis
--forceWymuś aktualizację nawet wtedy, gdy pliki są aktualne

Przykład:

bash
# Aktualizacja plików instrukcji po uaktualnieniu npm
npm update @fission-ai/openspec
openspec update

Polecenia przeglądania

openspec list

Wyświetla listę zmian lub specyfikacji w Twoim projekcie.

openspec list [opcje]

Opcje:

OpcjaOpis
--specsWyświetl specyfikacje zamiast zmian
--changesWyświetl zmiany (domyślnie)
--sort <kolejność>Sortuj według recent (domyślnie) lub name
--jsonWyjście w formacie JSON

Przykłady:

bash
# Wyświetlenie wszystkich aktywnych zmian
openspec list

# Wyświetlenie wszystkich specyfikacji
openspec list --specs

# Wyjście JSON dla skryptów
openspec list --json

Wyjście (tekst):

Aktywne zmiany:
  add-dark-mode     Obsługa przełączania motywu interfejsu
  fix-login-bug     Obsługa przekroczenia czasu sesji

openspec view

Wyświetla interaktywny panel do przeglądania specyfikacji i zmian.

openspec view

Otwiera interfejs oparty na terminalu do nawigacji po specyfikacjach i zmianach Twojego projektu.


openspec show

Wyświetla szczegóły zmiany lub specyfikacji.

openspec show [nazwa-elementu] [opcje]

Argumenty:

ArgumentWymaganyOpis
nazwa-elementuNieNazwa zmiany lub specyfikacji (monituje, jeśli pominięto)

Opcje:

OpcjaOpis
--type <typ>Określ typ: change lub spec (wykrywany automatycznie, jeśli jednoznaczny)
--jsonWyjście w formacie JSON
--no-interactiveWyłącz monity

Opcje specyficzne dla zmian:

OpcjaOpis
--deltas-onlyWyświetl tylko specyfikacje delta (tryb JSON)

Opcje specyficzne dla specyfikacji:

OpcjaOpis
--requirementsWyświetl tylko wymagania, wyklucz scenariusze (tryb JSON)
--no-scenariosWyklucz treść scenariuszy (tryb JSON)
-r, --requirement <id>Wyświetl konkretne wymaganie według indeksu od 1 (tryb JSON)

Przykłady:

bash
# Interaktywny wybór
openspec show

# Wyświetlenie konkretnej zmiany
openspec show add-dark-mode

# Wyświetlenie konkretnej specyfikacji
openspec show auth --type spec

# Wyjście JSON do parsowania
openspec show add-dark-mode --json

Polecenia walidacji

openspec validate

Waliduje zmiany i specyfikacje pod kątem problemów strukturalnych.

openspec validate [nazwa-elementu] [opcje]

Argumenty:

ArgumentWymaganyOpis
nazwa-elementuNieKonkretny element do walidacji (monituje, jeśli pominięto)

Opcje:

OpcjaOpis
--allWaliduj wszystkie zmiany i specyfikacje
--changesWaliduj wszystkie zmiany
--specsWaliduj wszystkie specyfikacje
--type <typ>Określ typ, gdy nazwa jest niejednoznaczna: change lub spec
--strictWłącz tryb ścisłej walidacji
--jsonWyjście w formacie JSON
--concurrency <n>Maksymalna liczba równoległych walidacji (domyślnie: 6 lub zmienna środowiskowa OPENSPEC_CONCURRENCY)
--no-interactiveWyłącz monity

Przykłady:

bash
# Interaktywna walidacja
openspec validate

# Walidacja konkretnej zmiany
openspec validate add-dark-mode

# Walidacja wszystkich zmian
openspec validate --changes

# Walidacja wszystkiego z wyjściem JSON (dla CI/skryptów)
openspec validate --all --json

# Ścisła walidacja ze zwiększonym równoległością
openspec validate --all --strict --concurrency 12

Wyjście (tekst):

Walidacja add-dark-mode...
  ✓ proposal.md prawidłowy
  ✓ specs/ui/spec.md prawidłowy
  ⚠ design.md: brak sekcji "Technical Approach"

Znaleziono 1 ostrzeżenie

Wyjście (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
  }
}

Polecenia cyklu życia

openspec archive

Archiwizuje zakończoną zmianę i scala specyfikacje delta z głównymi specyfikacjami.

openspec archive [nazwa-zmiany] [opcje]

Argumenty:

ArgumentWymaganyOpis
nazwa-zmianyNieZmiana do zarchiwizowania (monituje, jeśli pominięto)

Opcje:

OpcjaOpis
-y, --yesPomiń monity potwierdzające
--skip-specsPomiń aktualizacje specyfikacji (dla zmian dotyczących tylko infrastruktury/narzędzi/dokumentacji)
--no-validatePomiń walidację (wymaga potwierdzenia)

Przykłady:

bash
# Interaktywna archiwizacja
openspec archive

# Archiwizacja konkretnej zmiany
openspec archive add-dark-mode

# Archiwizacja bez monitów (CI/skrypty)
openspec archive add-dark-mode --yes

# Archiwizacja zmiany narzędziowej, która nie wpływa na specyfikacje
openspec archive update-ci-config --skip-specs

Co robi:

  1. Waliduje zmianę (chyba że --no-validate)
  2. Monituje o potwierdzenie (chyba że --yes)
  3. Scala specyfikacje delta do openspec/specs/
  4. Przenosi folder zmiany do openspec/changes/archive/YYYY-MM-DD-<nazwa>/

Polecenia przepływu pracy

Te polecenia obsługują przepływ pracy OPSX oparty na artefaktach. Są przydatne zarówno dla ludzi sprawdzających postęp, jak i agentów określających kolejne kroki.

openspec status

Wyświetla status ukończenia artefaktów dla zmiany.

openspec status [opcje]

Opcje:

OpcjaOpis
--change <id>Nazwa zmiany (monituje, jeśli pominięto)
--schema <nazwa>Nadpisanie schematu (wykrywane automatycznie z konfiguracji zmiany)
--jsonWyjście w formacie JSON

Przykłady:

bash
# Interaktywne sprawdzanie statusu
openspec status

# Status dla konkretnej zmiany
openspec status --change add-dark-mode

# JSON dla użycia przez agenta
openspec status --change add-dark-mode --json

Wyjście (tekst):

Zmiana: add-dark-mode
Schemat: spec-driven
Postęp: 2/4 artefaktów ukończonych

[x] proposal
[ ] design
[x] specs
[-] tasks (zablokowane przez: design)

Wyjście (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

Uzyskuje wzbogacone instrukcje tworzenia artefaktu lub realizacji zadań. Używane przez agentów AI do zrozumienia, co należy stworzyć dalej.

openspec instructions [artefakt] [opcje]

Argumenty:

ArgumentWymaganyOpis
artefaktNieID artefaktu: proposal, specs, design, tasks lub apply

Opcje:

OpcjaOpis
--change <id>Nazwa zmiany (wymagana w trybie nieinteraktywnym)
--schema <nazwa>Nadpisanie schematu
--jsonWyjście w formacie JSON

Przypadek specjalny: Użyj apply jako artefaktu, aby uzyskać instrukcje realizacji zadań.

Przykłady:

bash
# Uzyskanie instrukcji dla następnego artefaktu
openspec instructions --change add-dark-mode

# Uzyskanie instrukcji dla konkretnego artefaktu
openspec instructions design --change add-dark-mode

# Uzyskanie instrukcji realizacji/zastosowania
openspec instructions apply --change add-dark-mode

# JSON dla zużycia przez agenta
openspec instructions design --change add-dark-mode --json

Wyjście obejmuje:

  • Treść szablonu dla artefaktu
  • Kontekst projektu z konfiguracji
  • Treść z artefaktów zależnych
  • Zasady dla poszczególnych artefaktów z konfiguracji

openspec templates

Wyświetla rozstrzygnięte ścieżki szablonów dla wszystkich artefaktów w schemacie.

openspec templates [opcje]

Opcje:

OpcjaOpis
--schema <nazwa>Schemat do sprawdzenia (domyślnie: spec-driven)
--jsonWyjście w formacie JSON

Przykłady:

bash
# Wyświetlenie ścieżek szablonów dla domyślnego schematu
openspec templates

# Wyświetlenie szablonów dla niestandardowego schematu
openspec templates --schema mój-przepływ

# JSON do użycia programistycznego
openspec templates --json

Wyjście (tekst):

Schemat: spec-driven

Szablony:
  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

Wyświetla listę dostępnych schematów przepływu pracy z ich opisami i przepływami artefaktów.

openspec schemas [opcje]

Opcje:

OpcjaOpis
--jsonWyjście w formacie JSON

Przykład:

bash
openspec schemas

Wyjście:

Dostępne schematy:

  spec-driven (pakiet)
    Domyślny przepływ pracy oparty na specyfikacjach
    Przepływ: proposal → specs → design → tasks

  mój-niestandardowy (projekt)
    Niestandardowy przepływ pracy dla tego projektu
    Przepływ: research → proposal → tasks

Polecenia schematów

Polecenia do tworzenia i zarządzania niestandardowymi schematami przepływów pracy.

openspec schema init

Tworzy nowy, lokalny dla projektu schemat.

openspec schema init <nazwa> [opcje]

Argumenty:

ArgumentWymaganyOpis
nazwaTakNazwa schematu (format kebab-case)

Opcje:

OpcjaOpis
--description <tekst>Opis schematu
--artifacts <lista>Lista identyfikatorów artefaktów oddzielona przecinkami (domyślnie: proposal,specs,design,tasks)
--defaultUstaw jako domyślny schemat projektu
--no-defaultNie pytaj o ustawienie jako domyślny
--forceNadpisz istniejący schemat
--jsonWyjście w formacie JSON

Przykłady:

bash
# Interaktywne tworzenie schematu
openspec schema init research-first

# Nieinteraktywne z określonymi artefaktami
openspec schema init rapid \
  --description "Schemat szybkiej iteracji" \
  --artifacts "proposal,tasks" \
  --default

Co zostaje utworzone:

openspec/schemas/<nazwa>/
├── schema.yaml           # Definicja schematu
└── templates/
    ├── proposal.md       # Szablon dla każdego artefaktu
    ├── specs.md
    ├── design.md
    └── tasks.md

openspec schema fork

Kopiuje istniejący schemat do Twojego projektu w celu dostosowania.

openspec schema fork <źródło> [nazwa] [opcje]

Argumenty:

ArgumentWymaganyOpis
źródłoTakSchemat do skopiowania
nazwaNieNowa nazwa schematu (domyślnie: <źródło>-custom)

Opcje:

OpcjaOpis
--forceNadpisz istniejący cel
--jsonWyjście w formacie JSON

Przykład:

bash
# Skopiuj wbudowany schemat spec-driven
openspec schema fork spec-driven my-workflow

openspec schema validate

Waliduje strukturę i szablony schematu.

openspec schema validate [nazwa] [opcje]

Argumenty:

ArgumentWymaganyOpis
nazwaNieSchemat do walidacji (jeśli pominięto, waliduje wszystkie)

Opcje:

OpcjaOpis
--verbosePokaż szczegółowe kroki walidacji
--jsonWyjście w formacie JSON

Przykład:

bash
# Walidacja konkretnego schematu
openspec schema validate my-workflow

# Walidacja wszystkich schematów
openspec schema validate

openspec schema which

Wyświetla, skąd rozwiązuje się dany schemat (przydatne do debugowania priorytetów).

openspec schema which [nazwa] [opcje]

Argumenty:

ArgumentWymaganyOpis
nazwaNieNazwa schematu

Opcje:

OpcjaOpis
--allWylistuj wszystkie schematy wraz z ich źródłami
--jsonWyjście w formacie JSON

Przykład:

bash
# Sprawdź, skąd pochodzi schemat
openspec schema which spec-driven

Wyjście:

spec-driven rozwiązuje się z: package
  Źródło: /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven

Priorytet schematów:

  1. Projekt: openspec/schemas/<nazwa>/
  2. Użytkownik: ~/.local/share/openspec/schemas/<nazwa>/
  3. Pakiet: Wbudowane schematy

Polecenia konfiguracji

openspec config

Wyświetla i modyfikuje globalną konfigurację OpenSpec.

openspec config <podpolecenie> [opcje]

Podpolecenia:

PodpolecenieOpis
pathPokaż lokalizację pliku konfiguracyjnego
listPokaż wszystkie bieżące ustawienia
get <klucz>Pobierz wartość dla konkretnego klucza
set <klucz> <wartość>Ustaw wartość
unset <klucz>Usuń klucz
resetPrzywróć ustawienia domyślne
editOtwórz w $EDITOR
profile [preset]Konfiguruj profil przepływu pracy interaktywnie lub za pomocą presetu

Przykłady:

bash
# Pokaż ścieżkę do pliku konfiguracyjnego
openspec config path

# Wylistuj wszystkie ustawienia
openspec config list

# Pobierz wartość konkretnego klucza
openspec config get telemetry.enabled

# Ustaw wartość
openspec config set telemetry.enabled false

# Jawne ustawienie wartości tekstowej
openspec config set user.name "Moja Nazwa" --string

# Usuń niestandardowe ustawienie
openspec config unset user.name

# Resetuj całą konfigurację
openspec config reset --all --yes

# Edytuj konfigurację w edytorze
openspec config edit

# Konfiguruj profil za pomocą kreatora opartego na akcjach
openspec config profile

# Szybki preset: przełącz przepływy pracy na core (zachowuje tryb dostarczania)
openspec config profile core

openspec config profile rozpoczyna się od podsumowania stanu bieżącego, a następnie pozwala wybrać:

  • Zmień tryb dostarczania + przepływy pracy
  • Zmień tylko tryb dostarczania
  • Zmień tylko przepływy pracy
  • Zachowaj bieżące ustawienia (zakończ)

Jeśli zachowasz bieżące ustawienia, żadne zmiany nie zostaną zapisane i nie pojawi się monit o aktualizację. Jeśli nie ma zmian w konfiguracji, ale bieżące pliki projektu są niespójne z Twoim globalnym profilem/trybem dostarczania, OpenSpec wyświetli ostrzeżenie i zasugeruje uruchomienie openspec update. Naciśnięcie Ctrl+C również czysto przerywa przepływ (bez śladu stosu) i kończy z kodem wyjścia 130. Na liście kontrolnej przepływów pracy, [x] oznacza, że przepływ pracy jest wybrany w konfiguracji globalnej. Aby zastosować te wybory do plików projektu, uruchom openspec update (lub wybierz Zastosuj zmiany do tego projektu teraz? gdy pojawi się monit wewnątrz projektu).

Przykłady interaktywne:

bash
# Aktualizacja tylko trybu dostarczania
openspec config profile
# wybierz: Zmień tylko tryb dostarczania
# wybierz tryb dostarczania: Tylko umiejętności

# Aktualizacja tylko przepływów pracy
openspec config profile
# wybierz: Zmień tylko przepływy pracy
# przełącz przepływy pracy na liście kontrolnej, a następnie potwierdź

Polecenia pomocnicze

openspec feedback

Prześlij opinię na temat OpenSpec. Tworzy zgłoszenie na GitHubie.

openspec feedback <wiadomość> [opcje]

Argumenty:

ArgumentWymaganyOpis
wiadomośćTakTreść opinii

Opcje:

OpcjaOpis
--body <tekst>Szczegółowy opis

Wymagania: Musi być zainstalowany i uwierzytelniony klient GitHub CLI (gh).

Przykład:

bash
openspec feedback "Dodaj obsługę niestandardowych typów artefaktów" \
  --body "Chciałbym definiować własne typy artefaktów wykraczające poza wbudowane."

openspec completion

Zarządzaj uzupełnianiem poleceń w powłoce dla CLI OpenSpec.

openspec completion <podpolecenie> [powłoka]

Podpolecenia:

PodpolecenieOpis
generate [powłoka]Wygeneruj skrypt uzupełniania na standardowe wyjście
install [powłoka]Zainstaluj uzupełnianie dla Twojej powłoki
uninstall [powłoka]Usuń zainstalowane uzupełniania

Obsługiwane powłoki: bash, zsh, fish, powershell

Przykłady:

bash
# Zainstaluj uzupełniania (automatycznie wykrywa powłokę)
openspec completion install

# Zainstaluj dla konkretnej powłoki
openspec completion install zsh

# Wygeneruj skrypt do ręcznej instalacji
openspec completion generate bash > ~/.bash_completion.d/openspec

# Odinstaluj
openspec completion uninstall

Kody wyjścia

KodZnaczenie
0Sukces
1Błąd (niepowodzenie walidacji, brakujące pliki itp.)

Zmienne środowiskowe

ZmiennaOpis
OPENSPEC_TELEMETRYUstaw na 0, aby wyłączyć telemetrię
DO_NOT_TRACKUstaw na 1, aby wyłączyć telemetrię (standardowy sygnał DNT)
OPENSPEC_CONCURRENCYDomyślna liczba równoległych operacji dla walidacji zbiorczej (domyślnie: 6)
EDITOR lub VISUALEdytor dla openspec config edit
NO_COLORWyłącza kolorowe wyjście, gdy jest ustawiona

Powiązana dokumentacja