CLI-Referenz

Die OpenSpec-CLI (openspec) bietet Terminalbefehle für Projekteinrichtung, Validierung, Statusüberprüfung und Verwaltung. Diese Befehle ergänzen die in Commands dokumentierten KI-Slash-Befehle (wie /opsx:propose).

Übersicht

Kategorie	Befehle	Zweck
Einrichtung	`init`, `update`	OpenSpec in Ihrem Projekt initialisieren und aktualisieren
Stores (eigenständige OpenSpec-Repos)	`store setup`, `store register`, `store unregister`, `store remove`, `store list`, `store doctor`	Verwalten Sie Stores — eigenständige OpenSpec-Repos, die Sie registriert haben
Gesundheit	`doctor`	Berichten Sie den Beziehungsstatus für das aufgelöste Root
Arbeitskontext	`context`	Arbeitssatz zusammenstellen (Root + referenzierte Stores)
Persönliche Worksets	`workset create`, `workset list`, `workset open`, `workset remove`	Persönliche, lokale Arbeitsansichten in Ihrem Tool behalten und öffnen
Durchsuchen	`list`, `view`, `show`	Änderungen und Spezifikationen erkunden
Validierung	`validate`	Änderungen und Spezifikationen auf Probleme überprüfen
Lebenszyklus	`archive`	Abgeschlossene Änderungen finalisieren
Workflow	`new change`, `status`, `instructions`, `templates`, `schemas`	Artefaktgesteuerte Workflow-Unterstützung
Schemata	`schema init`, `schema fork`, `schema validate`, `schema which`	Benutzerdefinierte Workflows erstellen und verwalten
Konfiguration	`config`	Einstellungen anzeigen und ändern
Dienstprogramm	`feedback`, `completion`	Feedback und Shell-Integration

Mensch- vs. Agent-Befehle

Die meisten CLI-Befehle sind für die menschliche Nutzung im Terminal konzipiert. Einige Befehle unterstützen auch die Agent-/Skriptnutzung über JSON-Ausgabe.

Nur-menschliche Befehle

Diese Befehle sind interaktiv und für die Terminalnutzung konzipiert:

Befehl	Zweck
`openspec init`	Projekt initialisieren (interaktive Eingabeaufforderungen)
`openspec view`	Interaktives Dashboard
`openspec workset open <name>`	Ein gespeichertes Workset öffnen (Editorfenster oder Terminal-Agent-Sitzung)
`openspec config edit`	Konfiguration im Editor öffnen
`openspec feedback`	Feedback über GitHub einreichen
`openspec completion install`	Shell-Vervollständigungen installieren

Agent-kompatible Befehle

Diese Befehle unterstützen --json-Ausgabe für die programmatische Nutzung durch KI-Agenten und Skripte:

Befehl	Menschliche Nutzung	Agent-Nutzung
`openspec list`	Änderungen/Spezifikationen durchsuchen	`--json` für strukturierte Daten
`openspec show <item>`	Inhalt lesen	`--json` zum Parsen
`openspec validate`	Auf Probleme prüfen	`--all --json` für Massenvalidierung
`openspec status`	Artefaktfortschritt anzeigen	`--json` für strukturierten Status
`openspec instructions`	Nächste Schritte abrufen	`--json` für Agent-Anweisungen
`openspec templates`	Template-Pfade finden	`--json` für Pfadauflösung
`openspec schemas`	Verfügbare Schemas auflisten	`--json` für Schema-Erkennung; `--store <id>` zum Auswählen eines registrierten Roots
`openspec store setup <id>`	Einen lokalen Store erstellen und registrieren	`--json` mit expliziten Eingaben für strukturierte Einrichtungsausgabe
`openspec store register <path>`	Einen vorhandenen Store registrieren	`--json` für strukturierte Registrierungsausgabe
`openspec store unregister <id>`	Eine lokale Store-Registrierung vergessen	`--json` für strukturierte Bereinigungsausgabe
`openspec store remove <id>`	Einen registrierten lokalen Store-Ordner löschen	`--yes --json` für nicht-interaktive Löschung
`openspec store list`	Registrierte Stores durchsuchen	`--json` für strukturierte Registrierungen
`openspec store doctor`	Lokale Store-Einrichtung prüfen	`--json` für strukturierte Diagnose
`openspec new change <id>`	Repo-lokale Änderungsgerüste erstellen	`--json`, plus `--store <id>` zur Verwendung eines registrierten Stores als OpenSpec-Root
`openspec workset create [name]`	Eine persönliche Arbeitsansicht zusammenstellen	`--member <path> --json` für nicht-interaktive Zusammenstellung
`openspec workset list`	Gespeicherte Worksets durchsuchen	`--json` für strukturierte Ansichten
`openspec workset remove <name>`	Eine gespeicherte Ansicht löschen	`--yes --json` für nicht-interaktive Entfernung

Globale Optionen

Diese Optionen funktionieren mit allen Befehlen:

Option	Beschreibung
`--version`, `-V`	Versionsnummer anzeigen
`--no-color`	Farbe Ausgabe deaktivieren
`--help`, `-h`	Hilfe für den Befehl anzeigen

Einrichtungsbefehle

`openspec init`

OpenSpec in Ihrem Projekt initialisieren. Erstellt die Ordnerstruktur und konfiguriert KI-Tool-Integrationen.

Das Standardverhalten verwendet die globalen Konfigurationsstandardeinstellungen: Profil core, Lieferung both, Workflows propose, explore, apply, update, sync, archive.

openspec init [path] [options]

Verwenden Sie --language <language>, um eine Sprachinstruktion zu einer neuen Projekt-openspec/config.yaml hinzuzufügen. Bei einem vorhandenen Projekt bearbeiten Sie das context-Feld der Konfiguration, sodass OpenSpec projektspezifische Anweisungen nie überschreibt.

Argumente:

Argument	Erforderlich	Beschreibung
`path`	Nein	Zielverzeichnis (Standard: aktuelles Verzeichnis)

Optionen:

Option	Beschreibung
`--tools <list>`	KI-Tools nicht-interaktiv konfigurieren. `all`, `none` oder kommagetrennte Liste verwenden
`--language <language>`	Artefakte in dieser Sprache schreiben, wenn eine neue Konfiguration erstellt wird
`--force`	Legacy-Dateien ohne Rückfrage automatisch bereinigen
`--profile <profile>`	Globales Profil für diesen Init-Lauf überschreiben (`core` oder `custom`)
`--no-animation`	Statischen Begrüßungsbildschirm anstelle des animierten anzeigen
`--copilot-cloud`	GitHub Copilot Cloud-Coding-Agent-Dateien ohne Rückfrage einrichten
`--no-copilot-cloud`	GitHub Copilot Cloud-Coding-Agent-Dateien ohne Rückfrage überspringen

--profile custom verwendet die Workflows, die derzeit in der globalen Konfiguration ausgewählt sind (openspec config profile).

Die Begrüßungsanimation wird auch übersprungen, wenn die Umgebungsvariable OPENSPEC_NO_ANIMATION gesetzt ist (beliebiger Wert, einschließlich leer), wenn NO_COLOR auf einen nicht-leeren Wert gesetzt ist, oder wenn die Betriebssystem-Einstellung für reduzierte Bewegung aktiviert ist (macOS „Bewegung reduzieren“, GNOME-Animationen deaktiviert).

Unterstützte Tool-IDs (--tools) – windsurf wird ebenfalls akzeptiert, als Alias für devin: amazon-q, antigravity, auggie, bob, claude, cline, command-code, codeartsagent, codex, devin, forgecode, codebuddy, continue, costrict, crush, cursor, factory, gemini, github-copilot, hermes, iflow, junie, kilocode, kimi, kiro, lingma, minimax-code, vibe, oh-my-pi, opencode, pi, codeassistant, qoder, qwen, rovodev, roocode, trae, zed, zcode, agents

Diese Liste spiegelt AI_TOOLS in src/core/config.ts wider. Siehe Unterstützte Tools für die Skill- und Befehlspfade jedes Tools.

Beispiele:

bash

# Interaktive Initialisierung
openspec init

# In einem bestimmten Verzeichnis initialisieren
openspec init ./mein-projekt

# Nicht-interaktiv: Für Claude und Cursor konfigurieren
openspec init --tools claude,cursor

# Nicht-interaktiv: Globale MiniMax Code-Skills konfigurieren
openspec init --tools minimax-code

# Für alle unterstützten Tools konfigurieren
openspec init --tools all

# Profil für diesen Lauf überschreiben
openspec init --profile core

# Eingabeaufforderungen überspringen und Legacy-Dateien automatisch bereinigen
openspec init --force

Was erstellt wird:

openspec/
├── specs/              # Ihre Spezifikationen (Quelle der Wahrheit)
├── changes/            # Vorgeschlagene Änderungen
└── config.yaml         # Projektkonfiguration

.claude/skills/         # Claude Code-Skills (wenn claude ausgewählt)
.cursor/skills/         # Cursor-Skills (wenn cursor ausgewählt)
.cursor/commands/       # Cursor OPSX-Befehle (wenn Lieferung Befehle enthält)
.agents/skills/         # Gemeinsame Skills für AGENTS.md-kompatible Tools (wenn agents ausgewählt)
... (andere Tool-Konfigurationen)

`openspec update`

OpenSpec-Instruktionsdateien nach einem Upgrade der CLI aktualisieren. Generiert KI-Tool-Konfigurationsdateien neu, basierend auf Ihrem aktuellen globalen Profil, ausgewählten Workflows und Liefermodus.

openspec update [path] [options]

Argumente:

Argument	Erforderlich	Beschreibung
`path`	Nein	Zielverzeichnis (Standard: aktuelles Verzeichnis)

Optionen:

Option	Beschreibung
`--force`	Aktualisierung erzwingen, auch wenn Dateien aktuell sind

Beispiel:

bash

# Instruktionsdateien nach npm-Upgrade aktualisieren
npm install -g @fission-ai/openspec@latest
openspec update

Aktualisieren Sie zuerst das Paket. Instruktionsdateien werden von der installierten CLI generiert. Wenn Sie openspec update gegen eine veraltete Installation ausführen, wird gemeldet, dass alles auf dem neuesten Stand ist, ohne die Workflows hinzuzufügen, die neuere Versionen liefern.

Um das sichtbar zu machen, fragt openspec update die npm-Registry, ob eine neuere CLI veröffentlicht wurde. Wenn Ihre Version hinterherhinkt, bietet es ein Upgrade an:

text

Eine neuere OpenSpec CLI ist verfügbar (v1.6.0 → v1.7.0).
  Ausgeführt von: /usr/local/lib/node_modules/@fission-ai/openspec
? Jetzt auf v1.7.0 upgraden? (J/n)

Wenn Sie mit „Ja“ antworten, führt es npm install -g @fission-ai/openspec@latest aus und führt dann die Aktualisierung mit der neuen CLI erneut aus, sodass die neuen Workflows im selben Befehl landen. Es bestätigt das Upgrade, indem es die installierte Binärdatei nach ihrer Version fragt, anstatt sich auf den Exit-Code von npm zu verlassen. Wenn also eine andere Installation weiter vorne auf Ihrem PATH noch antwortet, teilt es Ihnen das mit, anstatt Erfolg zu behaupten. Wenn Sie mit „Nein“ antworten, wird der Befehl ausgegeben und mit der vorhandenen CLI aktualisiert. Strg-C stoppt den Befehl.

Das Angebot erscheint nur in einem interaktiven Terminal und nur, wenn npm die Installation besitzt – dem einzigen Fall, in dem npm install -g tatsächlich hilft. Alles andere erhält den Befehl, der der Installationsmethode entspricht:

Wie OpenSpec installiert ist	Was Sie erhalten
Globale npm-Installation	Die Eingabeaufforderung und das Upgrade für Sie ausgeführt – in einem interaktiven Terminal; bei weitergeleiteter Ausgabe erhalten Sie den gedruckten Befehl stattdessen
Globale pnpm-, bun-, yarn- oder volta-Installation	Der eigene Befehl des Managers: `pnpm add -g …@latest`, `bun add -g …@latest`, `yarn global add …@latest` oder `volta install …@latest`
Eine Abhängigkeit des Projekts	Ein Hinweis, die Abhängigkeit zu aktualisieren, da der Paketmanager die Lock-Datei besitzt
Ein `npx`/`dlx`-Cache	`npx @fission-ai/openspec@latest update` – dieser Befehl ist die Aktualisierung, es gibt also keinen zweiten Schritt
Ein Git-Klon	Nichts – Ihre Version ist die des Branches

Wenn etwas ausgegeben wird, benennt es das Verzeichnis, aus dem die laufende CLI geladen wurde – das, was Sie überprüfen sollten, wenn Sie ein Upgrade durchgeführt haben, aber ein veralteter Shim immer noch Ihren PATH besitzt.

Es fragt die Registry in npm_config_registry, wenn npm diese exportiert, andernfalls https://registry.npmjs.org. Es wird keine .npmrc gelesen: Dateiinhalten zu erlauben, zu bestimmen, wohin eine ausgehende Anfrage geht, ist ein Ablauf, den man vermeiden sollte, und die .npmrc eines Projekts reist mit dem Repository. Bei einem privaten Mirror exportieren Sie npm_config_registry – oder setzen Sie OPENSPEC_NO_UPDATE_CHECK, um die Prüfung vollständig zu überspringen. Die Prüfung wird übersprungen, wenn CI auf einen expliziten Off-Wert gesetzt ist (false, 0, no, off oder leer), unter NODE_ENV=test und wann immer OPENSPEC_NO_UPDATE_CHECK (beliebiger Wert), DO_NOT_TRACK=1 oder OPENSPEC_TELEMETRY=0 gesetzt ist. Sie läuft vor der Aktualisierung und kann sie um höchstens 1,5 Sekunden verzögern – sie gibt danach auf, selbst wenn das Netzwerk Pakete still verwirft, und bleibt still, wenn die Registry nicht erreichbar ist.

Wie „auf dem neuesten Stand“ entschieden wird: Skill-Dateien zeichnen die Version auf, die sie generiert hat. OpenSpec vergleicht diese mit der installierten CLI. Befehlsdateien tragen keinen Versionsstempel. Für ein Tool mit Befehlen, aber ohne Skills (Lieferung commands), vergleicht OpenSpec den Dateiinhalt mit dem, was es jetzt generieren würde – bearbeitete Dateien gelten als Abweichung und werden überschrieben. Bei Lieferung skills oder both wird nur die aufgezeichnete Version geprüft, sodass eine handbearbeitete Datei, deren Version noch übereinstimmt, in Ruhe gelassen wird; verwenden Sie --force, um sie neu zu schreiben. In beiden Fällen gehören generierte Dateien OpenSpec – bewahren Sie Ihre eigenen Anweisungen anderweitig auf.

Stores (eigenständige OpenSpec-Repos)

Beta. Stores und die darauf aufbauenden Funktionen (References, Working Context, Worksets) sind neu; Befehlsnamen, Flags, Dateiformate und JSON-Ausgabe können sich zwischen Versionen ändern. Für die problemorientierte Einführung siehe den Stores-Leitfaden.

Ein Store ist ein eigenständiges OpenSpec-Repo, das Sie auf diesem Computer registriert haben — beispielsweise ein Planung-Repo oder ein Verträge-Repo. Durch die Registrierung eines Stores können normale Befehle (list, show, status, validate, new change, archive, …) von überall aus in diesem Store arbeiten, indem Sie --store <id> übergeben.

`openspec store setup`

Erstellt und registriert einen lokalen Store. Ohne Argumente in einem Terminal führt OpenSpec den Benutzer durch die Einrichtung. Agenten und Skripte sollten explizite Eingaben übergeben und --json verwenden.

bash

openspec store setup [id] [options]

Optionen:

Option	Beschreibung
`--path <path>`	Ordner, in dem der Store abgelegt werden soll (zum Beispiel `~/openspec/<id>`)
`--remote <url>`	Trägt die kanonische Remote in die `store.yaml` des neuen Stores ein
`--init-git`	Initialisiert ein Git-Repository mit einem ersten Commit (Standard)
`--no-init-git`	Überspringt alle Git-Aktionen: kein Init, kein erster Commit
`--json`	Gibt JSON aus

Nicht-interaktive Ausführungen (--json, Skripte, Agenten) müssen sowohl die Store-ID als auch --path übergeben. In einem interaktiven Terminal fragt die Einrichtung nach dem Speicherort mit einem bearbeitbaren Vorschlag an einem sichtbaren, benutzereigenen Ort (zum Beispiel ~/openspec/<id>); sie verwendet niemals das von OpenSpec verwaltete Datenverzeichnis als Standard.

Beispiele:

bash

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

`openspec store register`

Registriert einen vorhandenen lokalen Store-Ordner. Während der Stores-Beta kann ein Root registriert werden, bevor Änderungen existieren, Spezifikationen angewendet oder Änderungen archiviert wurden; in diesem Fall können openspec/changes/, openspec/specs/ und openspec/changes/archive/ fehlen, bis normale Befehle sie erstellen. Ein nur konfigurierendes Repo, das store: <id> deklariert, bleibt ein Zeiger auf einen anderen Store und wird nicht als Store-Root registriert, es sei denn, dieser Zeiger wird entfernt.

bash

openspec store register [path] [options]

Optionen:

Option	Beschreibung
`--id <id>`	Store-ID; Standard ist die Store-Metadaten oder der Ordnernamen
`--yes`	Bestätigt die Erstellung von Store-Identitätsmetadaten für einen intakten OpenSpec-Root
`--json`	Gibt JSON aus

`openspec store unregister`

Entfernt eine lokale Store-Registrierung, ohne Dateien zu löschen.

bash

openspec store unregister <id> [--json]

Verwenden Sie dies, wenn ein Store verschoben, woanders geklont oder auf diesem Computer nicht mehr von OpenSpec angezeigt werden soll.

`openspec store remove`

Entfernt eine lokale Store-Registrierung und löscht den lokalen Ordner.

bash

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

remove zeigt den exakten Ordner vor dem Löschen in einem interaktiven Terminal an. Agenten, Skripte und JSON-Aufrufe müssen --yes übergeben, um das Löschen zu bestätigen. OpenSpec verweigert das Löschen eines Ordners, der keine übereinstimmenden Store-Metadaten enthält.

`openspec store list`

Listet lokal registrierte Stores auf.

bash

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

`openspec store doctor`

Prüft lokale Store-Registrierung, Metadaten und Git-Vorhandensein.

bash

openspec store doctor [id] [--json]

Doctor dient ausschließlich der Diagnose; er meldet fehlende Roots, Metadaten-Mismatches und ungültigen lokalen Registrierungsstatus, ohne den Store zu verändern.

Stores aus einem Projekt referenzieren

Ein Projekt-Repo kann in openspec/config.yaml deklarieren, auf welche Stores seine Arbeit zurückgreift:

yaml

schema: spec-driven
references:
  - team-context

Ab diesem Zeitpunkt enthält die Ausgabe von openspec instructions in diesem Repo (sowohl die pro Artefakt als auch die apply-Oberflächen, JSON- und Mensch-Modi) einen Index der Spezifikationen jedes referenzierten Stores — Spezifikations-IDs, eine einzeilige Zusammenfassung aus dem Purpose-Abschnitt jeder Spezifikation und der Abrufbefehl (openspec show <spec-id> --type spec --store <id>). Der Index wird bei jeder Ausführung live aus dem registrierten Checkout erstellt; der Spezifikationsinhalt wird niemals in die Ausgabe kopiert.

References sind nur-lesender Kontext. Sie ändern niemals, wo Befehle wirken: Die Arbeit bleibt im eigenen Root des Repos, und das Schreiben in einen referenzierten Store bleibt eine explizite --store-Aktion. Eine Referenz, die nicht aufgelöst werden kann (zum Beispiel ein Store, der auf diesem Computer nicht registriert ist), degradiert zu einer Warnung im Index mit dem exakten Lösungsweg, und die Instructions werden weiterhin generiert. openspec doctor meldet den Referenzstatus an einer Stelle.

Erfassen, woher ein Store geklont wurde

Ein Store kann seine kanonische Klonquelle in seiner committeten Identitätsdatei erfassen, sodass die Onboarding-Prozesse niemals bei „Store registrieren" enden:

bash

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

Die Remote landet in .openspec-store/store.yaml innerhalb des ersten Commits, sodass jeder Klon von Anfang an darüber Bescheid weiß. Für einen vorhandenen Store bearbeiten Sie store.yaml manuell und committen Sie die Änderung. store doctor zeigt die erfasste Remote (und den beobachteten Git-Origin des Checkouts) an; die Einrichtung/Registrierung nennt sie in den Anweisungen; und die Registrierung trägt den Origin des Checkouts in das maschinenlokale Register ein.

Eine Referenzdeklaration kann ebenfalls die Klonquelle tragen, sodass ein Teammitglied, das den Store noch nicht hat, eine vollständige, kopierbare Lösung erhält (git clone <remote> <path> && openspec store register <path> --id <id>):

yaml

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

Das Erfassen einer Remote ist keine Synchronisation: OpenSpec klonen, zieht oder schiebt niemals von selbst.

Standard-Store deklarieren

Ein Repo, dessen Planung vollständig externalisiert ist — kein lokales openspec/specs/ oder openspec/changes/ — kann seinen Store einmal deklarieren, anstatt bei jedem Befehl --store zu übergeben:

yaml

# openspec/config.yaml (die einzige Datei unter openspec/)
store: team-context

Normale Befehle werden dann automatisch auf den deklarierten Store aufgelöst; der Root-Banner und der JSON-root-Block melden source: "declared" mit der Store-ID, und gedruckte Hinweise tragen weiterhin --store <id>. Die Deklaration ist ein Fallback, niemals ein Override: explizites --store gewinnt immer, und ein Verzeichnis mit echten Planungsordnern ignoriert den Zeiger (mit einer Warnung). Um ein Zeiger-Repo in einen lokalen OpenSpec-Root umzuwandeln, entfernen Sie die store:-Zeile und führen Sie openspec init aus — init verweigert das Scaffolding, solange die Deklaration vorhanden ist.

Eine maschinenweite Variante deckt jedes Repo auf einmal ab: openspec config set defaultStore <id> (siehe Konfiguration). Sie wird nur konsultiert, nachdem --store, ein lokaler Root und ein Projekt-Zeiger alle erfolglos geblieben sind; der Root-Banner und der JSON-root-Block melden dann source: "global_default".

Doctor (Beziehungsgesundheit)

Eine Nur-Lese-Frage, ein Ort: Ist die OpenSpec-Wurzel gesund, und sind die von ihr referenzierten Stores auf diesem Rechner verfügbar?

bash

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

Der Bericht trennt Wurzelgesundheit, Store-Metadaten-Gesundheit (einschließlich eines Hinweises, wenn der aufgezeichnete Remote und der Ursprung des Checkouts abweichen, sowie eines Hinweises, wenn der Store-Checkout hinter seinem zuletzt abgerufenen Upstream-Tracking-Ref zurückgeblieben ist) und Referenzgesundheit (die gleichen Diagnoseanweisungen, die auch show anzeigt, mit Klon-Korrekturen für nicht aufgelöste Referenzen). Gesundheitsbefunde jeder Schwere enden mit Exit-Code 0 – Agenten lesen die status-Arrays; nur Befehlsfehler (keine Wurzel, unbekannter Store) führen zu Exit 1. Doctor klont, synchronisiert oder repariert nie. Um den zusammengestellten Satz selbst zu erhalten statt seiner Gesundheit, verwenden Sie openspec context.

Arbeitskontext (der zusammengestellte Satz)

Alles, worauf diese Arbeit durch OpenSpec-Deklarationen bezogen ist, in einem Arbeitssatz: die OpenSpec-Wurzel und die von ihr referenzierten Stores.

bash

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

Die JSON-Kurzfassung ist agentenkonsumierbar (jeder verfügbare referenzierte Store trägt sein Abrufrezept; nicht aufgelöste Mitglieder tragen dieselben Korrekturanweisungen und die Doctor-Anzeige). --code-workspace schreibt zusätzlich eine VS-Code-Arbeitsbereichsdatei, die die Wurzel plus die verfügbaren referenzierten Stores (ref:<id>-Ordner) enthält – das einzige Schreiben, das dieser Befehl durchführt, und das ohne --force verweigert wird, wenn die Datei existiert. Nicht verfügbare Mitglieder werden gemeldet, nie erraten.

„Arbeitskontext“ ist der zusammengestellte Satz; das Feld context: in openspec/config.yaml ist Projekthintergrund, der in Anweisungen injiziert wird – zwei verschiedene Dinge. openspec doctor beantwortet, ob der Satz gesund ist; openspec context beantwortet, was der Satz ist.

Persönliche Worksets

Beta. Worksets sind Teil der neuen Beta-Oberfläche; Befehle, Flags und Dateiformate können sich zwischen Versionen ändern. Für die Vorführung siehe den Stores-Leitfaden.

Ein Workset ist eine persönliche, benannte Ansicht der Ordner, an denen Sie zusammenarbeiten – eine Planungswurzel plus alles andere, was Sie wählen –, die auf Ihrem Rechner gespeichert und in Ihrem Werkzeug per Namen erneut geöffnet wird. Es ist rein lokal: nie committet, nie geteilt, nie aus Deklarationen abgeleitet, und das Entfernen eines Worksets berührt niemals einen Mitgliedsordner.

bash

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

create führt einen kurzen geführten Ablauf aus (oder nimmt --member-Flags nicht-interaktiv; das erste Mitglied ist das primäre – Sitzungen beginnen dort). open startet das gewählte Werkzeug: Editoren (VS Code, Cursor) öffnen ein Fenster mit jedem Mitglied und geben zurück; CLI-Agenten (Claude Code, codex) übernehmen dieses Terminal als Sitzung mit jedem Mitglied verbunden und ohne vorausgefüllte Eingabeaufforderung, die endet, wenn Sie beenden. Ein Mitgliedsordner, der beim Öffnen fehlt, wird mit einem Hinweis übersprungen; der Rest öffnet sich. Die gespeicherte Werkzeugpräferenz ist pro Öffnung mit --tool überschreibbar.

Die Unterstützung eines neuen Werkzeugs ist Konfiguration, nicht Code. Jedes Werkzeug ist einer von zwei Startstilen – workspace-file (gestartet mit der generierten .code-workspace) oder attach-dirs (ein Anhänge-Flag pro Mitglied) – und der Schlüssel openers in der globalen config.json (öffnen Sie ihn mit openspec config edit) fügt Werkzeuge hinzu oder passt eingebaute Werkzeuge pro Feld an:

json

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

Der gesamte Workset-Zustand liegt unter dem globalen Datenverzeichnis im Ordner worksets/ (die gespeicherten Ansichten plus die generierten <name>.code-workspace-Dateien, die bei jedem Öffnen neu erzeugt werden); das Löschen dieses Ordners entfernt jede Spur.

Browsing-Befehle

`openspec list`

Listet Änderungen oder Spezifikationen in Ihrem Projekt auf.

openspec list [optionen]

Optionen:

Option	Beschreibung
`--specs`	Listet Spezifikationen statt Änderungen auf
`--changes`	Listet Änderungen auf (Standard)
`--sort <reihenfolge>`	Sortiert nach `recent` (Standard) oder `name`
`--json`	Ausgabe als JSON

Beispiele:

bash

# Alle aktiven Änderungen auflisten
openspec list

# Alle Spezifikationen auflisten
openspec list --specs

# JSON-Ausgabe für Skripte
openspec list --json

Ausgabe (Text):

Änderungen:
  add-dark-mode     Keine Aufgaben      gerade eben

`openspec view`

Zeigt ein interaktives Dashboard zur Erkundung von Spezifikationen und Änderungen.

openspec view

Öffnet eine terminalbasierte Oberfläche zur Navigation durch die Spezifikationen und Änderungen Ihres Projekts.

`openspec show`

Zeigt Details einer Änderung oder Spezifikation an.

openspec show [element-name] [optionen]

Argumente:

Argument	Erforderlich	Beschreibung
`element-name`	Nein	Name der Änderung oder Spezifikation (fragt ab, wenn weggelassen)

Optionen:

Option	Beschreibung
`--type <typ>`	Gibt den Typ an: `change` oder `spec` (automatisch erkannt, wenn eindeutig)
`--json`	Ausgabe als JSON
`--no-interactive`	Deaktiviert Eingabeaufforderungen

Änderungsspezifische Optionen:

Option	Beschreibung
`--deltas-only`	Zeigt nur Delta-Spezifikationen an (JSON-Modus)

Spezifikationsspezifische Optionen:

Option	Beschreibung
`--requirements`	Zeigt nur Anforderungen, schließt Szenarien aus (JSON-Modus)
`--no-scenarios`	Schließt Szenario-Inhalte aus (JSON-Modus)
`-r, --requirement <id>`	Zeigt eine bestimmte Anforderung anhand ihres 1-basierten Index (JSON-Modus)

Beispiele:

bash

# Interaktive Auswahl
openspec show

# Eine bestimmte Änderung anzeigen
openspec show add-dark-mode

# Eine bestimmte Spezifikation anzeigen
openspec show auth --type spec

# JSON-Ausgabe zum Parsen
openspec show add-dark-mode --json

Validierungsbefehle

`openspec validate`

Validiert Änderungen und Spezifikationen auf strukturelle Probleme und prüft die MODIFIED-Anforderungen einer Änderung gegen die Hauptspezifikationen, die sie ersetzen würde.

openspec validate [item-name] [options]

Eine Änderung ohne Spezifikationsdeltas schlägt die Validierung fehl, es sei denn, deren .openspec.yaml deklariert skip_specs: true (für reine Refactorings, Tooling- oder Dokumentationsarbeiten — siehe Rezept 5).

Argumente:

Argument	Erforderlich	Beschreibung
`item-name`	Nein	Spezifisches Element zur Validierung (wird abgefragt, wenn weggelassen)

Optionen:

Option	Beschreibung
`--all`	Validiert alle Änderungen und Spezifikationen
`--changes`	Validiert alle Änderungen
`--specs`	Validiert alle Spezifikationen
`--archived`	Validiert, dass archivierten Änderungen alle Aufgaben abgeschlossen sind (für Pre-Commit-Linting)
`--type <type>`	Gibt den Typ an, wenn der Name mehrdeutig ist: `change` oder `spec`
`--strict`	Aktiviert den strikten Validierungsmodus
`--json`	Ausgabe als JSON
`--concurrency <n>`	Maximale parallele Validierungen (Standard: 6, oder `OPENSPEC_CONCURRENCY`-Umgebungsvariable)
`--no-interactive`	Deaktiviert Abfragen

--archived ist ein eigener Geltungsbereich: Es validiert keine Spezifikationsdeltas (diese wurden bereits bei der Archivierung angewendet), sondern prüft, dass jede Änderung unter changes/archive/ alle Checkboxen in tasks.md abgehakt hat, und beendet sich mit einem nicht-null-Exit-Code, wenn noch welche offen sind. Dies fängt Änderungen ab, die mit unvollendeter Arbeit archiviert wurden — nützlich in einem Pre-Commit-Hook.

Beispiele:

bash

# Interaktive Validierung
openspec validate

# Validiert eine bestimmte Änderung
openspec validate add-dark-mode

# Validiert alle Änderungen
openspec validate --changes

# Validiert alles mit JSON-Ausgabe (für CI/Scripts)
openspec validate --all --json

# Strikte Validierung mit erhöhter Parallelität
openspec validate --all --strict --concurrency 12

# Scheitert, wenn eine archivierte Änderung noch offene Aufgaben hat
openspec validate --archived

Ausgabe (Text):

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

1 warning found

Ausgabe (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
  }
}

Lebenszyklus-Befehle

`openspec archive`

Archiviert eine abgeschlossene Änderung und führt Delta-Spezifikationen in die Hauptspezifikationen ein.

openspec archive [change-name] [options]

Argumente:

Argument	Erforderlich	Beschreibung
`change-name`	Nein	Änderung zum Archivieren (wird abgefragt, wenn weggelassen; erforderlich, wenn niemand die Abfrage beantworten kann)

Optionen:

Option	Beschreibung
`-y, --yes`	Überspringt Bestätigungsabfragen. Erforderlich, wenn niemand sie beantworten kann — ein KI-Agent, ein CI-Job oder jeder Lauf mit geschlossenem stdin
`--skip-specs`	Überspringt Spezifikationsaktualisierungen für eine einzelne Archivierung. Eine Änderung, die dauerhaft keine Spezifikationsdeltas hat, sollte stattdessen `skip_specs: true` in ihrer `.openspec.yaml` deklarieren — sie wird ohne Flag archiviert
`--no-validate`	Überspringt die Validierung (erfordert Bestätigung). Deaktiviert außerdem die Capability-Rücknahme — ohne Validierungsurteil wird nichts zurückgenommen

Beispiele:

bash

# Interaktive Archivierung (fragt nach, welche Änderung, und bestätigt dann)
openspec archive

# Archiviert eine bestimmte Änderung
openspec archive add-dark-mode

# Archiviert ohne Abfragen (Agenten, CI, Scripts)
openspec archive add-dark-mode --yes

# Archiviert eine Tooling-Änderung, die keine Spezifikationen betrifft
openspec archive update-ci-config --skip-specs

Eine Capability zurücknehmen: Fügen Sie den Rücknahmemarker in die Änderungs-Metadaten ein:

yaml

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

Archivieren Sie die Änderung anschließend wie gewohnt:

bash

openspec archive retire-legacy --yes

Wenn die Änderung die letzte Anforderung der Capability entfernt, löscht OpenSpec deren aktives spec.md. Andere Capability-Deltas in derselben Änderung aktualisieren weiterhin ihre Hauptspezifikationen. Ohne den Marker stoppt die Archivierung, bevor Dateien geändert werden, und weist Sie darauf hin, ihn hinzuzufügen.

Was es tut:

Validiert die Änderung (außer mit --no-validate)
Fragt nach Bestätigung (außer mit --yes)
Besetzt das Archivziel, bevor eine Hauptspezifikation geändert wird
Validiert und führt die aktiven Delta-Spezifikationen in openspec/specs/ ein — eine Capability, deren letzte Anforderung die Änderung entfernt, wird zurückgenommen und ihre Spezifikationsdatei gelöscht, aber nur wenn die .openspec.yaml der Änderung neben ihrem schema: retire_capabilities: true deklariert
Verschiebt den Änderungsordner nach openspec/changes/archive/YYYY-MM-DD-<name>/
Wenn eine Spezifikationsänderung oder der abschließende Verschiebevorgang fehlschlägt, bevor eine vollständige Archivierung gesichert ist, werden die Spezifikationen wiederhergestellt und die Änderung bleibt oder wird an ihrem aktiven Pfad belassen
Wenn eine verifizierte Fallback-Kopie abgeschlossen ist, aber die Bereinigung der Staging-Quelle fehlschlägt, bleibt die vollständige Archivierung und der committe Spezifikationszustand zur Wiederherstellung erhalten

Ohne Terminal: Ein KI-Agent, ein CI-Job oder jeder Lauf mit geschlossenem stdin kann Schritt 2 nicht beantworten, daher stoppt die Archivierung, bevor etwas berührt wird, beendet sich mit Exit-Code 1 und nennt den Befehl zum erneuten Ausführen — openspec archive <name> --yes, mit allen anderen Flags, die Sie übergeben haben. Übergeben Sie --yes (und den Änderungsnamen) von vornherein, um den Umweg zu vermeiden.

Workflow-Befehle

Diese Befehle unterstützen den artefaktgesteuerten OPSX-Workflow. Sie sind sowohl für Menschen zur Fortschrittskontrolle als auch für Agenten zur Bestimmung der nächsten Schritte nützlich.

`openspec new change`

Erstellt ein Änderungsverzeichnis und optional eingecheckte Metadaten im aufgelösten OpenSpec-Rootverzeichnis.

bash

openspec new change <name> [options]

Änderungsnamen müssen in Kleinbuchstaben-Kebab-Case sein: Kleinbuchstaben, Zahlen und einzelne Bindestriche. Sie dürfen keine Leerzeichen, Unterstriche, Großbuchstaben, aufeinanderfolgende Bindestriche oder führende/nachgestellte Bindestriche enthalten. Eine führende Zahl ist erlaubt, sodass Sie Namen mit Präfixen zur Sortierung oder Stufung von Änderungen versehen können, zum Beispiel 100-add-feature oder 00001-add-auth.

Optionen:

Option	Beschreibung
`--description <text>`	Beschreibung, die zu `index.md` hinzugefügt wird
`--goal <text>`	Optionale Ziel-Metadaten, die mit der Änderung gespeichert werden
`--schema <name>`	Zu verwendendes Workflow-Schema
`--store <id>`	Store-ID, die als OpenSpec-Root verwendet werden soll (ein Store ist ein eigenständiges OpenSpec-Repository, das Sie registriert haben)
`--json`	Ausgabe als JSON

Beispiele:

bash

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

`openspec status`

Zeigt den Fertigstellungsstatus der Artefakte für eine Änderung an.

openspec status [options]

Optionen:

Option	Beschreibung
`--change <id>`	Änderungsname (fragt nach, wenn ausgelassen)
`--schema <name>`	Schema-Überschreibung (automatisch aus der Konfiguration der Änderung erkannt)
`--json`	Ausgabe als JSON

Beispiele:

bash

# Interaktive Statusabfrage
openspec status

# Status für bestimmte Änderung
openspec status --change add-dark-mode

# JSON für Agentenverwendung
openspec status --change add-dark-mode --json

Ausgabe (Text):

Änderung: add-dark-mode
Schema: spec-driven
Fortschritt: 2/4 Artefakte abgeschlossen

[x] proposal
[x] specs
[ ] design
[-] tasks (blockiert durch: design)

Eine Änderung, die skip_specs: true deklariert, zeigt ihre Specs-Phase als [~] specs (übersprungen: Änderung deklariert skip_specs) an und schließt sie von der Fortschrittszählung aus.

Ausgabe (JSON):

json

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

isPlanningComplete gibt an, ob jedes nicht übersprungene Planungsartefakt existiert; übersprungene Artefakte gelten als erfüllt, ohne erstellt zu werden. Es gibt nicht an, ob Implementierungsaufgaben abgeschlossen sind. isComplete wird als Kompatibilitäts-Alias mit demselben Wert beibehalten.

Artefakte werden in Abhängigkeitsreihenfolge aufgelistet – eine Abhängigkeit erscheint niemals nach etwas, das sie benötigt – und Artefakte, die gleichzeitig bereit werden (bei spec-driven benötigen sowohl specs als auch design nur proposal), behalten die Reihenfolge, die das Schema angibt, und nicht alphabetisch. Daher ist der erste ready-Eintrag das als nächstes zu schreibende Artefakt.

`openspec instructions`

Ruft erweiterte Anweisungen zum Erstellen eines Artefakts oder zum Anwenden von Aufgaben ab. Wird von KI-Agenten verwendet, um zu verstehen, was als nächstes zu erstellen ist.

openspec instructions [artifact] [options]

Argumente:

Argument	Erforderlich	Beschreibung
`artifact`	Nein	Artefakt-ID oder Workflow-Eingabeoberfläche: `apply` oder `archive`

Optionen:

Option	Beschreibung
`--change <id>`	Änderungsname (erforderlich im nicht-interaktiven Modus)
`--schema <name>`	Schema-Überschreibung
`--json`	Ausgabe als JSON

Sonderfälle: Verwenden Sie apply, um Anweisungen zur Aufgabenimplementierung zu erhalten. Verwenden Sie archive, um aktuelle, schreibgeschützte Archiv-Eingaben (context und operationGuidance) für eine gültige Änderung abzurufen; es archiviert oder verändert nichts.

Beispiele:

bash

# Anweisungen für das nächste Artefakt abrufen
openspec instructions --change add-dark-mode

# Anweisungen für ein bestimmtes Artefakt abrufen
openspec instructions design --change add-dark-mode

# Anweisungen zum Anwenden/Implementieren abrufen
openspec instructions apply --change add-dark-mode

# Aktuelle Archiv-Eingaben ohne Archivierung abrufen
openspec instructions archive --change add-dark-mode --json

# JSON für Agentenverwendung
openspec instructions design --change add-dark-mode --json

Die Ausgabe enthält:

Vorlageninhalt für das Artefakt
Projektkontext aus der Konfiguration
Inhalt aus Abhängigkeitsartefakten
Artefaktspezifische Regeln aus der Konfiguration
Aktueller Projektkontext und passende Betriebsanleitung für apply/archive

Betriebseingaben werden bei jedem Aufruf aus dem aufgelösten Repository oder dem ausgewählten Store gelesen. Projektkontext ist eine erforderliche Eingabe auf Prompt-Ebene: Agenten lesen ihn und wenden relevante Projektfakten, Konventionen und Einschränkungen an. Betriebsanleitung ist optionaler ergänzender Rat: Agenten berücksichtigen jeden Eintrag und befolgen nur Einträge, die anwendbar und mit dem integrierten Workflow kompatibel sind. Beide Felder bleiben getrennt von expliziten Benutzerentscheidungen, CLI-gesteuertem Zustand, integrierten Anweisungen und Artefaktregeln. Widersprüchlicher Kontext wird gemeldet; widersprüchliche oder nicht anwendbare Anleitung wird nicht befolgt und der Grund wird erklärt. Dies sind Verhaltensverträge für generierte Agenten, keine durchsetzbaren CLI-Prüfungen. instructions archive gibt nur die ausgewählte Änderung, optionale Eingaben und Root-Metadaten zurück; es enthält nicht den statischen Archivierungs-Workflow.

Für ein Artefakt, das über skip_specs: true übersprungen wird, besteht die Ausgabe nur aus einer Warnung (JSON fügt skipped/warning-Felder hinzu) – das Artefakt darf nicht erstellt werden.

`openspec templates`

Zeigt aufgelöste Vorlagenpfade für alle Artefakte in einem Schema an.

openspec templates [options]

Optionen:

Option	Beschreibung
`--schema <name>`	Zu untersuchendes Schema (Standard: `spec-driven`)
`--json`	Ausgabe als JSON

Beispiele:

bash

# Vorlagenpfade für Standardschema anzeigen
openspec templates

# Vorlagen für benutzerdefiniertes Schema anzeigen
openspec templates --schema my-workflow

# JSON für programmatische Nutzung
openspec templates --json

Ausgabe (Text):

Schema: spec-driven

Vorlagen:
  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`

Listet verfügbare Workflow-Schemas mit ihren Beschreibungen und Artefaktflüssen auf.

openspec schemas [options]

Optionen:

Option	Beschreibung
`--json`	Ausgabe als JSON
`--store <id>`	Einen registrierten Store als OpenSpec-Root verwenden

Beispiel:

bash

openspec schemas

Ausgabe:

Verfügbare Schemas:

  spec-driven (package)
    Der standardmäßige spec-driven Entwicklungs-Workflow
    Flow: proposal → specs → design → tasks

  my-custom (project)
    Benutzerdefinierter Workflow für dieses Projekt
    Flow: research → proposal → tasks

Schema-Befehle

Befehle zum Erstellen und Verwalten von benutzerdefinierten Workflow-Schemas.

`openspec schema init`

Erstellt ein neues projektlokales Schema.

openspec schema init <name> [options]

Argumente:

Argument	Erforderlich	Beschreibung
`name`	Ja	Schemaname (kebab-case)

Optionen:

Option	Beschreibung
`--description <text>`	Schemabeschreibung
`--artifacts <list>`	Kommagetrennte Artifact-IDs (Standard: `proposal,specs,design,tasks`)
`--default`	Als Projektstandard-Schema festlegen
`--no-default`	Nicht nach der Festlegung als Standard fragen
`--force`	Vorhandenes Schema überschreiben
`--json`	Ausgabe als JSON

Beispiele:

bash

# Interaktive Schemaanlage
openspec schema init research-first

# Nicht-interaktiv mit bestimmten Artifacts
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

Was erstellt wird:

openspec/schemas/<name>/
├── schema.yaml           # Schema-Definition
└── templates/
    ├── proposal.md       # Vorlage für jedes Artifact
    ├── specs.md
    ├── design.md
    └── tasks.md

`openspec schema fork`

Kopiert ein vorhandenes Schema in Ihr Projekt zur Anpassung.

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

Argumente:

Argument	Erforderlich	Beschreibung
`source`	Ja	Zu kopierendes Schema
`name`	Nein	Neuer Schemaname (Standard: `<source>-custom`)

Optionen:

Option	Beschreibung
`--force`	Vorhandenes Ziel überschreiben
`--json`	Ausgabe als JSON

Beispiel:

bash

# Eingebautes spec-driven-Schema forken
openspec schema fork spec-driven my-workflow

`openspec schema validate`

Validiert die Struktur und Vorlagen eines Schemas.

openspec schema validate [name] [options]

Argumente:

Argument	Erforderlich	Beschreibung
`name`	Nein	Zu validierendes Schema (validiert alle, wenn weggelassen)

Optionen:

Option	Beschreibung
`--verbose`	Detaillierte Validierungsschritte anzeigen
`--json`	Ausgabe als JSON

Beispiel:

bash

# Ein bestimmtes Schema validieren
openspec schema validate my-workflow

# Alle Schemas validieren
openspec schema validate

`openspec schema which`

Zeigt an, woher ein Schema aufgelöst wird (nützlich zur Fehlersuche bei Prioritäten).

openspec schema which [name] [options]

Argumente:

Argument	Erforderlich	Beschreibung
`name`	Nein	Schemaname

Optionen:

Option	Beschreibung
`--all`	Alle Schemas mit ihren Quellen auflisten
`--json`	Ausgabe als JSON

Beispiel:

bash

# Prüfen, woher ein Schema stammt
openspec schema which spec-driven

Ausgabe:

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

Schema-Prioritäten:

Projekt: openspec/schemas/<name>/
Benutzer: ~/.local/share/openspec/schemas/<name>/
Paket: Eingebaute Schemas

Konfigurationsbefehle

`openspec config`

Anzeigen und Ändern der globalen OpenSpec-Konfiguration.

openspec config <subcommand> [options]

Unterbefehle:

Unterbefehl	Beschreibung
`path`	Konfigurationsdatei-Ort anzeigen
`list`	Alle aktuellen Einstellungen anzeigen
`get <key>`	Einen bestimmten Wert abrufen
`set <key> <value>`	Einen Wert festlegen
`unset <key>`	Einen Schlüssel entfernen
`reset`	Auf Standardwerte zurücksetzen
`edit`	In `$EDITOR` öffnen
`profile [preset]`	Workflow-Profil interaktiv oder über Preset konfigurieren

Beispiele:

bash

# Konfigurationsdatei-Pfad anzeigen
openspec config path

# Alle Einstellungen auflisten
openspec config list

# Einen bestimmten Wert abrufen
openspec config get telemetry.enabled

# Einen Wert festlegen (anonyme Nutzungs-Telemetrie deaktivieren)
openspec config set telemetry.enabled false

# Einen Zeichenkettenwert explizit festlegen
openspec config set user.name "My Name" --string

# Eine benutzerdefinierte Einstellung entfernen
openspec config unset user.name

# Einen maschinenweiten Standard-Store festlegen (Fallback-Wurzel, wenn kein --store,
# lokale Wurzel oder Projekt-Store: pointer aufgelöst wird)
openspec config set defaultStore team-plans

# Alle Konfigurationen zurücksetzen
openspec config reset --all --yes

# Konfiguration im Editor bearbeiten
openspec config edit

# Profil mit aktionsbasiertem Assistenten konfigurieren
openspec config profile

# Schnelles Preset: Workflows auf core umstellen (behält Liefermodus bei)
openspec config profile core

Telemetrie-Opt-out: telemetry.enabled ist standardmäßig aktiviert, wenn nicht gesetzt (Opt-out-Modell). Setzen Sie es auf false, um anonyme Nutzungsstatistiken und die Versionsprüfung von openspec update zu deaktivieren. Umgebungsvariablen haben Vorrang vor der Konfiguration: OPENSPEC_TELEMETRY=0, DO_NOT_TRACK=1 und ein wahrheitsgemäßer CI-Wert (z. B. true/1/yes) deaktivieren die Telemetrie unabhängig vom Konfigurationswert.

openspec config profile beginnt mit einer Zusammenfassung des aktuellen Zustands und bietet dann die Auswahl:

Lieferung + Workflows ändern
Nur Lieferung ändern
Nur Workflows ändern
Aktuelle Einstellungen beibehalten (beenden)

Wenn Sie die aktuellen Einstellungen beibehalten, werden keine Änderungen geschrieben und keine Aktualisierungsanfrage angezeigt. Wenn es keine Konfigurationsänderungen gibt, aber die aktuellen Projektdateien nicht mit Ihrem globalen Profil/Liefermodus synchron sind, zeigt OpenSpec eine Warnung an und schlägt openspec update vor. Das Drücken von Ctrl+C bricht den Ablauf ebenfalls sauber ab (ohne Stack Trace) und beendet sich mit dem Code 130. In der Workflow-Checkliste bedeutet [x], dass der Workflow in der globalen Konfiguration ausgewählt ist. Um diese Auswahl auf die Projektdateien anzuwenden, führen Sie openspec update aus (oder wählen Sie Apply changes to this project now?, wenn Sie innerhalb eines Projekts gefragt werden).

Interaktive Beispiele:

bash

# Nur Lieferung aktualisieren
openspec config profile
# wählen: Nur Lieferung ändern
# Lieferung wählen: Nur Skills

# Nur Workflows aktualisieren
openspec config profile
# wählen: Nur Workflows ändern
# Workflows in der Checkliste umschalten, dann bestätigen

Hilfsbefehle

`openspec feedback`

Sendet Feedback zu OpenSpec. Erstellt ein GitHub-Issue.

openspec feedback <message> [options]

Argumente:

Argument	Erforderlich	Beschreibung
`message`	Ja	Feedback-Zusammenfassung; langer Text wird im Issue-Titel gekürzt und im Inhalt aufbewahrt

Optionen:

Option	Beschreibung
`--body <text>`	Zusätzliche Details, die nach der Zusammenfassung eingefügt werden

Voraussetzungen: GitHub CLI (gh) muss installiert und authentifiziert sein.

Beispiel:

bash

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

`openspec completion`

Verwaltet Shell-Vervollständigungen für die OpenSpec-CLI.

openspec completion <subcommand> [shell]

Unterbefehle:

Unterbefehl	Beschreibung
`generate [shell]`	Vervollständigungsskript auf stdout ausgeben
`install [shell]`	Vervollständigung für Ihre Shell installieren
`uninstall [shell]`	Installierte Vervollständigungen entfernen

Unterstützte Shells: bash, zsh, fish, powershell

Beispiele:

bash

# Vervollständigungen installieren (Shell wird automatisch erkannt)
openspec completion install

# Für bestimmte Shell installieren
openspec completion install zsh

# Skript für manuelle Installation generieren (bash)
openspec completion generate bash > ~/.bash_completion.d/openspec

# Deinstallieren
openspec completion uninstall

Windows (PowerShell): Vervollständigungen für den aktuellen PowerShell-Host installieren:

powershell

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

$env:PROFILE teilt OpenSpec mit, welches Profil in dieser Sitzung konfiguriert werden soll. Der Installer erstellt fehlende Profilverzeichnisse und fügt einen verwalteten Block hinzu, der OpenSpecCompletion.ps1 lädt. Das Neuladen des Profils aktiviert die Vervollständigungen sofort.

Zum Deinstallieren vom aktuellen Host führen Sie Folgendes aus:

powershell

$env:PROFILE = $PROFILE
openspec completion uninstall powershell

Starten Sie PowerShell nach der Deinstallation neu, um die Vervollständigungen aus der aktuellen Sitzung zu entfernen.

Vervollständigungen sind optional. Die CLI erwähnt sie einmalig auf stderr beim ersten Ausführen eines Befehls in einem interaktiven Terminal und nie wieder — sie bleibt ebenfalls still, wenn Sie bereits Vervollständigungen installiert haben. Setzen Sie OPENSPEC_NO_COMPLETIONS=1, um diesen Hinweis vollständig zu unterdrücken.

Exit-Codes

Code	Bedeutung
`0`	Erfolg
`1`	Fehler (Validierungsfehler, fehlende Dateien usw.)

Umgebungsvariablen

Variable	Beschreibung
`OPENSPEC_TELEMETRY`	Auf `0` setzen, um Telemetrie und die Versionsprüfung von `openspec update` zu deaktivieren (überschreibt `telemetry.enabled` in der globalen Konfiguration)
`DO_NOT_TRACK`	Auf `1` setzen, um Telemetrie und die Versionsprüfung von `openspec update` zu deaktivieren (Standard-DNT-Signal; überschreibt Konfiguration)
`OPENSPEC_CONCURRENCY`	Standard-Konnektivität für Bulk-Validierung (Standard: 6)
`EDITOR` oder `VISUAL`	Editor für `openspec config edit`
`NO_COLOR`	Farbige Ausgabe deaktivieren, wenn gesetzt
`OPENSPEC_NO_ANIMATION`	Die Willkommensanimation von `openspec init` deaktivieren, wenn gesetzt
`OPENSPEC_NO_COMPLETIONS`	Auf `1` setzen, um den einmaligen Hinweis zu Shell-Vervollständigungen zu unterdrücken
`OPENSPEC_NO_UPDATE_CHECK`	Die `openspec update`-Prüfung auf eine neuere veröffentlichte CLI deaktivieren, wenn gesetzt (jeder Wert, einschließlich leer). Wird ebenfalls übersprungen, wenn `CI` gesetzt ist (außer `false`/`0`/`no`/`off`) oder `NODE_ENV=test`
`npm_config_registry`	Registry, bei der die `openspec update`-Versionsprüfung fragt. Muss eine `http(s)`-URL sein, andernfalls wird auf `https://registry.npmjs.org` zurückgefallen. Es wird keine `.npmrc`-Datei gelesen

CLI-Referenz ​

Übersicht ​

Mensch- vs. Agent-Befehle ​

Nur-menschliche Befehle ​

Agent-kompatible Befehle ​

Globale Optionen ​

Einrichtungsbefehle ​

openspec init ​

openspec update ​

Stores (eigenständige OpenSpec-Repos) ​

openspec store setup ​

openspec store register ​

openspec store unregister ​

openspec store remove ​

openspec store list ​

openspec store doctor ​

Stores aus einem Projekt referenzieren ​

Erfassen, woher ein Store geklont wurde ​

Standard-Store deklarieren ​

Doctor (Beziehungsgesundheit) ​

Arbeitskontext (der zusammengestellte Satz) ​

Persönliche Worksets ​

Browsing-Befehle ​

openspec list ​

openspec view ​

openspec show ​

Validierungsbefehle ​

openspec validate ​

Lebenszyklus-Befehle ​

openspec archive ​

Workflow-Befehle ​

openspec new change ​

openspec status ​

openspec instructions ​

openspec templates ​

openspec schemas ​

Schema-Befehle ​

openspec schema init ​

openspec schema fork ​

openspec schema validate ​

openspec schema which ​

Konfigurationsbefehle ​

openspec config ​

Hilfsbefehle ​

openspec feedback ​

openspec completion ​

Exit-Codes ​

Umgebungsvariablen ​

Verwandte Dokumentation ​

CLI-Referenz

Übersicht

Mensch- vs. Agent-Befehle

Nur-menschliche Befehle

Agent-kompatible Befehle

Globale Optionen

Einrichtungsbefehle

`openspec init`

`openspec update`

Stores (eigenständige OpenSpec-Repos)

`openspec store setup`

`openspec store register`

`openspec store unregister`

`openspec store remove`

`openspec store list`

`openspec store doctor`

Stores aus einem Projekt referenzieren

Erfassen, woher ein Store geklont wurde

Standard-Store deklarieren

Doctor (Beziehungsgesundheit)

Arbeitskontext (der zusammengestellte Satz)

Persönliche Worksets

Browsing-Befehle

`openspec list`

`openspec view`

`openspec show`

Validierungsbefehle

`openspec validate`

Lebenszyklus-Befehle

`openspec archive`

Workflow-Befehle

`openspec new change`

`openspec status`

`openspec instructions`

`openspec templates`

`openspec schemas`

Schema-Befehle

`openspec schema init`

`openspec schema fork`

`openspec schema validate`

`openspec schema which`

Konfigurationsbefehle

`openspec config`

Hilfsbefehle

`openspec feedback`

`openspec completion`

Exit-Codes

Umgebungsvariablen

Verwandte Dokumentation