CLI

Die openspec-Terminalbefehle.

Befehle

Einrichtung

Befehl	Beschreibung
openspec init	OpenSpec in einem Projekt initialisieren.
openspec update	Die installierten Anweisungsdateien von OpenSpec aktualisieren.
openspec config	Globale Konfiguration anzeigen und ändern.

Änderungen und Specs

Befehl	Beschreibung
openspec list	Änderungen auflisten, oder Specs mit --specs.
openspec show	Eine Änderung oder einen Spec als Markdown oder JSON ausgeben.
openspec view	Ein-Bildschirm-Dashboard von Specs und Änderungen.
openspec validate	Änderungen und Specs auf strukturelle Probleme prüfen.
openspec archive	Eine abgeschlossene Änderung ins Archiv verschieben und die Hauptspecs aktualisieren.

Workflows und Schemas

Ihr Agent führt die meisten davon während des Workflows aus.

Befehl	Beschreibung
openspec new	Ein neues Änderungsverzeichnis erstellen.
openspec status	Abschlussstatus der Artefakte für eine oder jede aktive Änderung.
openspec instructions	Anweisungen zum Erstellen, Anwenden oder Archivieren eines Artefakts.
openspec templates	Aufgelöste Vorlagenpfade für die Artefakte eines Schemas.
openspec schemas	Verfügbare Workflow-Schemas auflisten.
openspec schema	Ein Schema prüfen, abzweigen oder erstellen (experimentell).

Multi-Repo (Beta)

Befehl	Beschreibung
openspec store	Stores erstellen und verwalten: eigenständige OpenSpec-Repos, die auf Ihrem Rechner registriert sind.
openspec doctor	Beziehungsstatus für den aufgelösten OpenSpec-Stammknoten melden.
openspec context	Arbeitskontext für den aufgelösten OpenSpec-Stammknoten ausgeben.
openspec workset	Persönliche Arbeitsansichten komponieren, pflegen und öffnen.

Dienstprogramme

Befehl	Beschreibung
openspec version	Installierte Version melden und optional nach einer Aktualisierung suchen.
openspec install	Das eigenständige openspec installieren, das ohne Node.js läuft.
openspec feedback	Feedback zu OpenSpec senden.
openspec completion	Shell-Vervollständigungen installieren oder generieren.

Veraltet

Befehl	Beschreibung
openspec change	Substantivform von show, list und validate für Änderungen. Die CLI warnt und verweist auf die Verb-zuerst-Befehle.
openspec spec	Substantivform von show, list und validate für Specs, mit derselben Warnung.

Jeder Befehl akzeptiert -h, --help. Der bloße openspec-Befehl akzeptiert außerdem:

• -V, --version: CLI-Version ausgeben.
• --no-color: Farbige Ausgabe deaktivieren.

openspec init

Initialisiert OpenSpec in einem Projekt.

openspec init                        # aktuelles Verzeichnis, interaktive Tool-Auswahl
openspec init --tools claude,cursor  # spezifische Tools einrichten, keine Aufforderungen
openspec init --tools none           # nur openspec/-Struktur, keine Tool-Dateien

Ohne --tools fordert init zur Auswahl von Tools in einem interaktiven Terminal auf. Außerhalb eines Terminals richtet es die im Projekt erkannten Tools ein. Wenn keine erkannt werden, wird mit Code 1 beendet und die gültigen IDs aufgelistet.

Nur-Speicher-Repositories

Wenn openspec/config.yaml eine store:-Zeile enthält und das Repository keine lokalen Specs oder Änderungen hat, führen Sie init vom Repository-Stammverzeichnis aus aus:

# Claude-Code-Integrationsdateien im Code-Repository installieren
openspec init --tools claude

• Integrationsdateien: werden im Code-Repository geschrieben.
• openspec/config.yaml: wird byte-genau erhalten.
• openspec/specs/ und openspec/changes/: werden im Code-Repository nicht erstellt.

Wenn init aus einem Unterverzeichnis ausgeführt wird, wird mit Code 1 beendet und Sie werden aufgefordert, es vom Repository-Stammverzeichnis aus auszuführen. --language beendet ebenfalls mit Code 1, da die Sprache in der Konfiguration des externen Speichers hinterlegt gehört. Führen Sie init im Stammverzeichnis des Speichers aus oder bearbeiten Sie diese Konfiguration direkt.

Argumente

Argument	Beschreibung
path	Das zu initialisierende Projektverzeichnis. Standard: aktuelles Verzeichnis. Wird erstellt, falls nicht vorhanden.

Optionen

Flag	Wirkung
--tools <tools>	Kommagetrennte Tool-IDs, all oder none. Überspringt die Auswahl. IDs sind unter Unterstützte Tools aufgelistet.
--language <language>	Fügt eine Sprachanweisung zu einer neuen Projektkonfiguration hinzu. Wird abgelehnt, wenn die store:-Zeile des Repositories auf einen externen Speicher verweist.
--force	Entfernt Dateien aus älteren OpenSpec-Layouts ohne Nachfrage. Interaktive Ausführungen bestätigen das Bereinigen andernfalls zuerst.
--profile <profile>	Überschreibt das globale Konfigurationsprofil für diese Ausführung: core (der Standard-Workflow-Satz) oder custom (die in der globalen Konfiguration gespeicherten Workflows).
--no-animation	Zeigt einen statischen Willkommensschirm statt des animierten.

Ausgabe

Jedes ausgewählte Tool erhält OpenSpec's Skills und Commands in einem eigenen Verzeichnis:

▌ 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 erstellt nur openspec/config.yaml. Bei einem bereits initialisierten Projekt schreibt init die installierten Dateien an Ort und Stelle neu, und die Zusammenfassung lautet Refreshed: Claude Code mit Config: openspec/config.yaml (exists).

Exit-Codes

• 0: Einrichtung abgeschlossen.
• 1: ungültiger --tools- oder --profile-Wert, eine nicht-interaktive Ausführung ohne erkannte Tools und ohne --tools, oder ein ungültiger Nur-Speicher-Aufruf.

openspec update

Aktualisiert die installierten Anweisungsdateien von OpenSpec.

openspec update             # Tools aktualisieren, deren Dateien älter als die CLI sind
openspec update --force     # Dateien auch dann neu schreiben, wenn sie aktuell sind
openspec update --dry-run   # auflisten, was eine Aktualisierung ändern würde, ohne etwas zu ändern

update findet die von init konfigurierten Tools und vergleicht deren generierte Dateien mit der Version der CLI. Wenn eine neuere OpenSpec-Version existiert, bietet es zuerst ein Upgrade der CLI an und führt dann mit der aktualisierten Version erneut aus. Setzen Sie OPENSPEC_NO_UPDATE_CHECK=1, um die Prüfung zu überspringen.

Argumente

Argument	Beschreibung
path	Das zu aktualisierende Projektverzeichnis. Standard: aktuelles Verzeichnis.

Optionen

Flag	Wirkung
--force	Schreibt die Dateien jedes konfigurierten Tools neu, auch wenn sie aktuell sind.
--dry-run	Meldet jede Datei, die die Aktualisierung hinzufügen, ändern oder löschen würde, und schreibt nichts. Keine CLI-Upgrade-Prüfung, keine Aufforderungen. In Kombination mit --force eine erzwungene Aktualisierung in der Vorschau anzeigen.
--json	Mit --dry-run den Plan als JSON ausgeben. Ohne --dry-run wird mit Code 1 beendet.

Aktualisierung in der Vorschau

--dry-run plant die Aktualisierung, die eine nicht-interaktive Ausführung durchführen würde: derselbe Code-Pfad, wobei jedes Schreiben und Löschen aufgezeichnet statt ausgeführt wird. Jede Datei, die die echte Aktualisierung betreffen würde, wird aufgelistet, einschließlich:

• Verschieben von OpenSpec-Dateien aus dem ehemaligen Verzeichnis eines Tools (.kimi/ nach .kimi-code/, .windsurf/ nach .devin/, .codex/ und .agent/ nach .agents/);
• Speichern der globalen Konfiguration, wenn eine Installation aus der Zeit vor den Profilen eine erhält;
• Synchronisieren der GitHub-Copilot-Cloud-Agent-Dateien;
• mit --force, Einrichten von Tools, die nur in Legacy-Artefakten gefunden werden, und Bereinigen dieser Artefakte, einschließlich zurückgezogener globaler Codex-Prompts.

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 gibt denselben Plan als ein JSON-Dokument aus:

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

Feld	Beschreibung
changes[].path	Projektrelativer Pfad. Eine Datei außerhalb des Projekts, wie ein globales Skill oder die globale Konfiguration, wird ab Ihrem Home-Verzeichnis als ~/... angezeigt, oder als absoluter Pfad, wenn sie auch außerhalb des Home-Verzeichnisses liegt.
changes[].action	add, update oder delete. Eine Datei, deren neue Bytes mit den alten übereinstimmen, wird nicht aufgelistet.
changes[].tool	Das konfigurierte Tool, zu dem die Datei gehört, wie claude. Dateien, die zu OpenSpec selbst gehören und nicht zu einem Tool, die globale Konfiguration und die Legacy-Artefaktbereinigung, sind openspec.
notes[]	{ code, message } für einen Schritt, über den ein Terminal-Benutzer befragt würde. legacy-tool-directories: ein Verschiebungsvorgang, den eine interaktive Ausführung zuerst abfragt; changes listet ihn als durchgeführt auf. legacy-artifacts: Dateien aus dem älteren Layout von OpenSpec wurden gefunden, wie openspec-proposal.md-Slash-Commands oder OpenSpec-Markierungsblöcke in AGENTS.md. Ohne --force lässt eine nicht-interaktive Aktualisierung sie unangetastet, daher auch changes; --dry-run --force listet ihre Bereinigung auf. Leer bei einer normalen Aktualisierung.
failures[]	{ tool, error } für jedes Tool, bei dem die echte Aktualisierung fehlschlagen würde, einschließlich eines Schreibvorgangs, den es nicht durchführen kann: ein Verzeichnis, wo eine Datei gehören würde, eine Datei, wo ein Verzeichnis gehören würde, oder eine Datei oder ein Ordner ohne Schreibrechte. Bei diesem Tool stoppt changes, wo die echte Aktualisierung stoppt; die anderen Tools werden weiter plant. Fehler, die die Festplatte erst beim Schreiben meldet, wie Speichermangel, können nicht vorhergesehen werden.

Ein Fehler vor der Planung, wie ein fehlendes OpenSpec-Verzeichnis, gibt weiterhin genau ein JSON-Dokument aus: den leeren Plan plus ein status-Array mit severity, code (update_error) und message. Der Exit-Code ist 1.

Ausgabe

Wenn die Dateien aller Tools mit der CLI-Version übereinstimmen:

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

Use --force to refresh files anyway.

Wenn die Dateien eines Tools von einer älteren CLI stammen (oder mit --force, das stattdessen Force updating 1 tool(s): claude ausgibt):

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.

In einem Verzeichnis ohne OpenSpec verweigert update:

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

Exit-Codes

• 0: Dateien aktualisiert, oder alles bereits aktuell.
• 1: kein OpenSpec-Verzeichnis im Pfad, oder die Aktualisierung ist fehlgeschlagen.

openspec config

Zeigt die globale Konfiguration an und ändert sie.

openspec config list                  # aktuelle Einstellungen anzeigen
openspec config set delivery skills   # einen Wert ändern
openspec config profile               # interaktive Workflow-Auswahl

Subcommand	Beschreibung
path	Den Speicherort der Konfigurationsdatei ausgeben.
list	Alle aktuellen Einstellungen anzeigen.
get <key>	Einen Wert ausgeben, roh und skriptfähig.
set <key> <value>	Einen Wert setzen, mit Typumwandlung.
unset <key>	Einen Schlüssel entfernen, damit sein Standardwert gilt.
reset	Alle Konfiguration auf Standardwerte zurücksetzen.
edit	Die Konfigurationsdatei in $EDITOR öffnen.
profile [preset]	Delivery-Modus und Workflows konfigurieren.

Die Konfiguration ist global für Ihre Maschine und wird als JSON gespeichert, auf das config path verweist: $XDG_CONFIG_HOME/openspec/config.json, falls gesetzt, sonst ~/.config/openspec/config.json (macOS, Linux) oder %APPDATA%\openspec\config.json (Windows). Jeder Subcommand akzeptiert --scope <scope>, aber nur global funktioniert derzeit. Jeder andere Scope wird mit Code 1 beendet und der Meldung Error: Project-local config is not yet implemented.

openspec config path

openspec config path

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

openspec config list

openspec config list          # lesbare Einstellungen plus Profilzusammenfassung
openspec config list --json   # rohe Konfiguration als JSON

Optionen

Flag	Wirkung
--json	Das Konfigurationsobjekt als JSON ausgeben.

Ausgabe

Jede Einstellung, dann eine Profilzusammenfassung, die Werte als explizit oder Standard markiert:

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

openspec config get delivery

Argumente

Argument	Beschreibung
key	Der zu lesende Schlüssel. Punkte erreichen verschachtelte Werte (featureFlags.workspaces).

Ausgabe

Der nackte Wert, bereit für Skripte. Objekte werden als kompaktes JSON ausgegeben:

both

Exit-Codes

• 0: Wert ausgegeben.
• 1: Schlüssel hat keinen Wert, und es wird nichts ausgegeben.

openspec config set

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

Argumente

Argument	Beschreibung
key	Der zu schreibende Schlüssel, mit Punkten für verschachtelte Werte.
value	Der neue Wert. true/false werden zu Booleans, numerische Strings zu Zahlen.

Optionen

Flag	Wirkung
--string	Den Wert als String speichern, ohne Typumwandlung.
--allow-unknown	Schlüssel zulassen, die das Schema nicht kennt.

Ausgabe

Set featureFlags.workspaces = true

Unbekannte Schlüssel und ungültige Werte schlagen mit Exit 1 fehl, bevor etwas gespeichert wird:

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"

Wenn die Konfigurationsdatei existiert, aber kein JSON-Objekt enthält, sei es, weil sie überhaupt kein gültiges JSON ist oder weil ihre Wurzel etwas anderes wie null oder ein Array ist, beenden config set, config unset und config profile mit Code 1 und lassen die Datei unverändert. Beheben Sie es mit openspec config edit, oder ersetzen Sie es mit 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".

Bis es behoben ist, bleiben Telemetrie und die Aktualisierungsprüfung deaktiviert.

openspec config unset

openspec config unset delivery

Entfernt den Schlüssel, damit der Standardwert wieder gilt. Schlüssel mit eingebauten Standardwerten zählen immer als gesetzt, daher meldet dies Erfolg, auch wenn Sie sie nie gesetzt haben:

Unset delivery (reverted to default)

Ein Schlüssel ohne Wert gibt Key "featureFlags.nothere" was not set aus. Beide Fälle beenden mit Code 0. Eine nicht parsebare Konfigurationsdatei beendet stattdessen mit Code 1, wie bei config set.

openspec config reset

openspec config reset --all      # fragt nach Bestätigung
openspec config reset --all -y   # keine Aufforderung

Optionen

Flag	Wirkung
--all	Erforderlich. Alles zurücksetzen.
-y, --yes	Die Bestätigungsaufforderung überspringen.

Ausgabe

Configuration reset to defaults

Ohne --all wird mit Code 1 beendet und die Verwendungszeile ausgegeben.

Exit-Codes

• 0: Zurücksetzen durchgeführt, oder Sie haben bei der Aufforderung Nein geantwortet.
• 1: --all fehlt.
• 130: Aufforderung mit Ctrl-C abgebrochen.

openspec config edit

openspec config edit

Öffnet die Konfigurationsdatei in $EDITOR (mit Rückfall auf $VISUAL) und erstellt sie zuerst mit Standardwerten, falls sie fehlt. Wenn der Editor geschlossen wird, wird die Datei validiert. Ungültiges JSON oder eine ungültige Konfiguration beenden mit Code 1.

Der Editor-Wert kann Argumente und angeführte Pfade enthalten, zum Beispiel code --wait oder "/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl" -w. Er wird ohne Shell in Wörter zerlegt, sodass $VAR, ~ und ; wörtlich durchgereicht werden. Ein Editor, der nicht gestartet werden kann oder mit einem Nicht-Null-Code endet, gibt eine einzeilige Fehlermeldung aus und beendet mit Code 1.

Ohne konfigurierten Editor wird mit Code 1 beendet:

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

openspec config profile

openspec config profile        # interaktive Auswahl (benötigt ein Terminal)
openspec config profile core   # Core-Preset direkt anwenden

Argumente

Argument	Beschreibung
preset	Optionaler Preset-Name. Nur core existiert. Es wählt die Core-Workflows und behält Ihre Delivery-Einstellung.

Ohne Preset zeigt eine interaktive Auswahl Ihre aktuelle Delivery-Einstellung und Workflows, lässt Sie beides oder eins davon ändern (Delivery: both, nur Skills oder nur Commands; Workflows: eine Checkbox-Liste), gibt den Diff aus und bietet innerhalb eines OpenSpec-Projekts an, openspec update für Sie auszuführen. Außerhalb eines Terminals wird mit Code 1 beendet:

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

Ausgabe

Geänderte Konfiguration erreicht Projekte erst, wenn sie aktualisieren:

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

Exit-Codes

• 0: Profil gespeichert, oder Sie haben die aktuellen Einstellungen beibehalten.
• 1: unbekanntes Preset, kein Terminal, oder das angebotene openspec update ist fehlgeschlagen.
• 130: Auswahl mit Ctrl-C abgebrochen.

openspec list

Listet Änderungen oder Specs mit --specs auf.

openspec list                    # aktive Änderungen, zuletzt geändert zuerst
openspec list --archived         # archivierte Änderungen
openspec list --all              # aktive und archivierte Änderungen
openspec list --specs            # Specs mit Anzahl der Anforderungen
openspec list --json             # maschinenlesbar, enthält die aufgelöste Wurzel

Zeilen stammen aus openspec/changes/ und openspec/specs/ unter der aufgelösten Wurzel. Die Standard-Änderungsliste überspringt openspec/changes/archive/.

Optionen

Flag	Wirkung
--specs	Specs statt Änderungen auflisten.
--changes	Änderungen auflisten. Dies ist die Standardeinstellung.
--archived	Nur archivierte Änderungen auflisten. Kann nicht mit --specs kombiniert werden.
--all	Aktive und archivierte Änderungen auflisten. Kann nicht mit --specs kombiniert werden. Hat Vorrang vor --archived.
--sort <order>	recent (zuletzt geändert zuerst) oder name. Standard: recent. Specs werden immer nach Name sortiert.
--json	JSON statt der Tabelle ausgeben.
--store <id>	Einen registrierten Store als OpenSpec-Wurzel verwenden, anstatt des aktuellen Projekts.

Ausgabe

Eine Zeile pro Änderung: Name, Aufgabenstatus, zuletzt geändert. Die Statusspalte zeigt No tasks, 2/5 tasks oder ✓ Complete.

Changes:
  add-rate-limit     No tasks      just now

--all gruppiert aktive und archivierte Änderungen unter getrennten Überschriften. Jede Gruppe verwendet die gewählte Sortierreihenfolge:

Changes:
  add-rate-limit     No tasks      just now

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

Specs:
  api     requirements 1

--json fügt Aufgabenanzahlen und einen status mit no-tasks, in-progress oder complete hinzu:

{
  "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"
  }
}

Mit --archived oder --all enthält jedes Änderungsobjekt einen archived-Boolean. Das kombinierte Array verwendet die gewählte Sortierreihenfolge. Eine archivierte Änderung kann trotzdem den Status in-progress haben, wenn ihre verfolgte Aufgabendatei nicht abgehakte Aufgaben enthält. Ohne einen dieser Flags bleibt die JSON-Struktur unverändert.

Eine leere Liste gibt No active changes found., No archived changes found., No changes found. oder No specs found. aus und endet trotzdem mit Code 0.

Eine Änderung ist ein Verzeichnis direkt unter openspec/changes/. Anders als Specs können Änderungen nicht in einem Namespace-Ordner verschachtelt sein. Ein Ordner wie changes/mobile/, der nur eine Änderung umschließt (changes/mobile/refresh-token/), wird mit dem Status not a change aufgelistet, gefolgt von einer Warnung, die die verschachtelten Verzeichnisse nennt. --json markiert diesen Eintrag mit einem nested-Array und fügt ein warnings-Array auf oberster Ebene hinzu. show, status, validate und archive lehnen den Ordner mit derselben Meldung ab. Um dies zu beheben, verschieben Sie die Änderung nach oben und integrieren Sie den Namespace in den Namen:

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

Exit-Codes

• 0: Liste ausgegeben, auch wenn sie leer ist.
• 1: Keine OpenSpec-Wurzel gefunden (außerhalb eines Projekts, kein --store).

openspec show

Gibt eine Änderung oder einen Spec als Markdown oder JSON aus.

openspec show add-rate-limit              # Änderung: gibt proposal.md aus
openspec show add-rate-limit --diff       # Änderung: hängt Anforderungs-Deltas an
openspec show api                         # Spec: gibt spec.md aus
openspec show api --json --no-scenarios   # Spec-JSON ohne Szenariotext

Ohne Namen fragt show nach Änderung oder Spec und listet dann Einträge zur Auswahl auf. Außerhalb eines interaktiven Terminals endet es mit Code 1 und gibt die direkten Formen aus.

Argumente

Argument	Beschreibung
item-name	Die anzuzeigende Änderung oder der anzuzeigende Spec, nach Ordnername (add-rate-limit, api).

Optionen

Flag	Wirkung
--json	Strukturiertes JSON statt Ro-Markdown ausgeben.
--type <change|spec>	Den Typ auswählen, wenn eine Änderung und ein Spec denselben Namen haben.
--no-interactive	Niemals nachfragen: Ein fehlender Name wird zu einem Fehler.
--deltas-only	JSON, Änderung: Ausgabe auf Deltas beschränken. Änderungs-JSON ist bereits nur Delta, daher entspricht die Ausgabe der einfachen --json-Option.
--requirements-only	Veralteter Alias für --deltas-only. Warnt auf stderr.
--diff	Änderung: Pro-Anforderung Delta-Diffs anhängen. Wird mit einer Warnung für Specs ignoriert.
--requirements	JSON, Spec: Anforderungstext behalten, scenarios-Arrays leeren.
--no-scenarios	JSON, Spec: Gleiche Ausgabe wie --requirements.
-r, --requirement <id>	JSON, Spec: Eine Anforderung nach 1-basierter Position ausgeben. Kann nicht mit --requirements kombiniert werden.
--store <id>	Einen registrierten Store als OpenSpec-Wurzel verwenden, anstatt des aktuellen Projekts.

Flags, die nicht auf den aufgelösten Typ anwendbar sind, werden mit einer Warnung auf stderr ignoriert.

Ausgabe

Der Textmodus ist eine Ro-Weiterleitung: Eine Änderung gibt ihre proposal.md aus, ein Spec gibt seine spec.md aus.

# Add rate limiting

## Warum
Unauthentifizierte Clients können die API erschöpfen.

## Was sich ändert
- Pro-Client-Rate-Limiting für die öffentliche API hinzufügen.

Bei einer Änderung gibt --diff zuerst den Vorschlag aus, dann einen Abschnitt Specifications Changed (diffs). HINZUGEFÜGTE Anforderungen enthalten ihren vollständigen Text. ENTFERNTE Anforderungen behalten den verfassten Grund und die Migration bei. UMBENANNTE Anforderungen zeigen VON und NACH. GEÄNDERTE Anforderungen zeigen einen Unified Diff gegen die passende Haupt-Anforderung.

Wenn ein GEÄNDERTER Header erst nach Groß-/Kleinschreibungsanpassung oder Leerzeichen-Normalisierung übereinstimmt, enthält die Ausgabe sowohl den Diff als auch eine Warnung, dass die Archiv-Zuordnung exakt ist. Wenn die Haupt-Spezifikation oder Anforderung fehlt, warnt die Ausgabe und gibt den vollständigen Delta-Block aus. Ein GEÄNDERTER Block ohne textuelle Unterschiede gibt (no textual changes) aus.

Eine Änderung mit --json hat Delta-Form:

{
  "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"
  }
}

Jede Anforderung trägt ihren name, den Header-Text nach Requirement:. Dies ist der Name, gegen den das Archiv GEÄNDERTE, ENTFERNTE und UMBENANNTE Einträge abgleicht. Jedes Szenario trägt seinen name, den Header-Text nach Scenario:. Ein abschließender #-Lauf auf einem der Header ist nicht Teil des Namens.

--json --diff behält diese obere Struktur bei. Ein GEÄNDERTER Delta erhält eine diff-Zeichenkette, eine warning-Zeichenkette oder beides. Andere Operationen bleiben unverändert. Eine leere diff-Zeichenkette bedeutet, dass die Haupt- und Delta-Blöcke textuell identisch sind.

Eine Spezifikation mit --json listet ihre Anforderungen mit Szenarien auf. Anforderungen und Szenarien tragen die gleichen name-Felder wie das Änderungs-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"
  }
}

Ein unbekannter Name schlägt Naheliegendes vor: Unknown item 'does-not-exist'. Did you mean: add-rate-limit, api?. Ein Name, der sowohl auf eine Änderung als auch auf eine Spezifikation passt, erzeugt einen Fehler und fragt nach --type.

Exit-Codes

• 0: Element ausgegeben.
• 1: unbekannter oder mehrdeutiger Name, kein Name außerhalb eines Terminals, ein -r-Index außerhalb des Bereichs, --requirements kombiniert mit -r, oder ein Delta oder eine Haupt-Spezifikation kann für --diff nicht gelesen werden.

openspec view

Gibt ein Single-Screen-Dashboard von Spezifikationen und Änderungen aus.

openspec view   # project summary in one screen

view gibt das Dashboard einmal aus und beendet sich. Es liest keine Tasteneingaben. Änderungen werden nach Aufgabenfortschritt gruppiert: Entwurf (noch keine Aufgaben), Aktiv (Aufgaben in Arbeit, mit Fortschrittsbalken und Prozent), Abgeschlossen (alle Aufgaben abgehakt). Spezifikationen werden mit Anforderungszahlen aufgelistet, größte zuerst.

Optionen

Flag	Wirkung
--store <id>	Verwendet einen registrierten Speicher als OpenSpec-Wurzel statt des aktuellen Projekts.

Ausgabe

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

Eine Task Progress-Zusammenfassungszeile erscheint, wenn irgendeine Änderung Aufgaben in Arbeit hat.

Jede aktive Änderung zeigt auch ihre Schema- und Artefakt-Zustände unterhalb ihres Fortschrittsbalkens:

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

Marker	Artefakt-Zustand
✓	Seine Ausgabe existiert. Ein vorhandenes Aufgaben-Artefakt ist fertig, auch wenn seine Checkliste unvollständig ist.
→	Es ist bereit zur Erstellung.
Kein Marker	Es ist durch eine fehlende Abhängigkeit blockiert.
(skipped)	Die Änderung überspringt es.

Wenn ein Workflow nicht geladen werden kann, gibt view eine Warnung aus und hält den Aufgabenfortschritt dieser Änderung sichtbar. Führen Sie openspec status --change <name> aus, um den Workflow separat zu untersuchen. Übergeben Sie nach openspec view --store <id> denselben --store <id> an status.

Exit-Codes

• 0: Dashboard ausgegeben.
• 1: keine OpenSpec-Wurzel gefunden (außerhalb eines Projekts, kein --store).

openspec validate

Prüft Änderungen und Spezifikationen auf strukturelle Probleme.

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

Ohne Namen und ohne Bulk-Flag bittet validate Sie zur Auswahl von Elementen auf. Außerhalb eines interaktiven Terminals beendet es sich mit 1 und gibt stattdessen die Bulk-Flags aus.

Argumente

Argument	Was es ist
item-name	Die zu validierende Änderung oder Spezifikation, nach Ordnername (add-rate-limit, api).

Optionen

Flag	Wirkung
--all	Validiert jede Änderung und Spezifikation.
--changes	Validiert jede Änderung.
--specs	Validiert jede Spezifikation.
--archived	Prüft Aufgabenvollständigkeit in archivierten Änderungen, ohne deren angewendete Spezifikations-Deltas zu validieren.
--strict	Behandelt Warnungen als Fehler.
--type <change|spec>	Wählt den Typ, wenn eine Änderung und eine Spezifikation einen Namen teilen.
--json	Gibt einen strukturierten Bericht statt Text aus.
--report <mode>	Bulk-Ausgabe: full (Standard) oder findings. Erfordert einen expliziten Bulk-Bereich.
--concurrency <n>	Max. parallele Validierungen in Bulk-Läufen. Standard: OPENSPEC_CONCURRENCY, sonst 6.
--no-interactive	Niemals abfragen: ein fehlender oder mehrdeutiger Name wird zum Fehler.
--store <id>	Verwendet einen registrierten Speicher als OpenSpec-Wurzel statt des aktuellen Projekts.

Ausgabe

Bulk-Läufe geben eine Statuszeile pro Element aus, gefolgt von etwaigen Befunden, und enden mit Summen:

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

Aufgaben-Checkbox-Befunde

Fortschritt zählt Checkboxes und nichts anderes, daher wird eine Aufgabendatei mit gewöhnlichen Aufzählungspunkten als null Aufgaben gelesen: openspec list und openspec status melden keine Arbeit, und openspec archive hat nichts, was als unvollständig markiert werden könnte. Validate meldet eine WARNING für jede getrackte Aufgabendatei, die Arbeit ohne Checkbox auflistet:

⚠ [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".

Die Warnung wird nur ausgelöst, wenn der gesamte getrackte Satz der Änderung keinerlei Checkbox enthält. Eine Prosa-Datei neben einer echten Checkliste wird nicht gemeldet, und eine Änderung in der Erstellung behält ihren Fortschritt, sobald eine einzige Checkbox existiert. --strict verwandelt die Warnung in einen Fehler. Die Zeilennummer befindet sich im --json-Bericht.

Geschützte Blöcke, HTML-Kommentare, YAML-Frontmatter und eingerückter Code werden nicht durchsucht, daher wird eine eingefügte Terminal-Ausgabe nie fälschlich als Aufgabenliste erkannt.

Archiv-Merge-Befunde

Für Änderungen führt validate den Merge-Builder des Archivs gegen die aktuellen Haupt-Spezifikationen aus, ohne Dateien zu schreiben. Es meldet Merge-Konflikte, wie ein fehlendes MODIFIED-Ziel oder eine widersprüchliche HINZUGEFÜGTE Anforderung, als INFO:

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

Diese Befunde erscheinen auch wenn die Validierung besteht, sowohl in Text- als auch in JSON-Ausgabe. INFO ändert niemals den Exit-Code, auch nicht unter --strict: ein fehlendes Ziel kann zu einer Schwester-Änderung gehören, die noch nicht archiviert wurde. Bereits in die Haupt-Spezifikationen synchronisierte Deltas folgen den bestehenden Merge-Regeln des Archivs.

Diese Prüfung führt die spätere Validierung der gemergten Spezifikationen oder Zurückziehungs-Prüfungen des Archivs nicht aus. Ein sauberer Bericht garantiert nicht, dass das Archiv erfolgreich sein wird.

Wenn der Merge-Preflight nicht starten kann, erklärt ein INFO-Befund warum. Bestehende Validierungs-Befunde und der Exit-Code bleiben unverändert.

Ein fehlgeschlagenes Element listet jedes Problem und die Behebung auf:

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 gibt einen Bericht für den Lauf aus:

{
  "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-Einträge tragen eine level von ERROR, WARNING oder INFO.

Exit-Codes

• 0: jedes validierte Element bestand, einschließlich eines leeren Bulk-Bereichs.
• 1: ein Element schlug fehl, die Berichtsanfrage ist ungültig, openspec/config.yaml kann nicht gelesen werden oder ist kein gültiges YAML, oder der Lauf schlug fehl (z. B. ein unbekannter Name oder keine OpenSpec-Wurzel). Eine Konfiguration, die nicht gelesen oder geparst werden kann, stoppt den Lauf bevor irgendein Element geprüft wird; mit --json wird sie als einzelner status-Eintrag mit dem Code unreadable_config oder unparseable_config gemeldet.

--report full|findings

Wählt die Ausgabe für einen expliziten Bulk-Validierungsbereich:

• full: jedes Element. Dies ist die Standardeinstellung. Explizites --report full behält die bestehende Ausgabeform bei, ohne Berichts-Metadaten hinzuzufügen.
• findings: nur Elemente mit Problemen, einschließlich bestandener Elemente mit Warnungen oder Informationen. Jedes Element wird weiterhin validiert. Summen, Strict-Modus-Verhalten und Exit-Codes bleiben unverändert.

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

Bereiche

Flags	Findings report.scope
--all	all
--changes	changes
--specs	specs
--changes --specs, oder --all mit einem der Flags	all
--archived	archived

Beide expliziten Berichtsmodi werfen einen positionellen Element-Namen, einen fehlenden Bulk-Bereich oder Archiv- und aktive Bereiche in Kombination zurück.

Findings-Textausgabe

Menschliche Ausgabe: stdout gibt Scope: <scope> (<count> items) aus, dann Summen. Ohne problematische Elemente:

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

Labels von problematischen Elementen, Schweregrad-Labels, Pfade und Meldungen werden auf stderr ausgegeben. Fehler im aktiven Bereich behalten den Details:-Hinweis nach den Summen. Das bestehende Wurzel-Banner und die Fortschrittsausgabe können dem Bericht vorausgehen.

Findings-JSON-Ausgabe

--report findings --json gibt ein Dokument aus. Dieses Beispiel hat zwei saubere Elemente:

{
  "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 und report.version: identifizieren die validation-findings-Form, Version 1.0. Es gibt kein version oder items auf oberster Ebene.
• report.returnedItems und report.totalItems: zählen die zurückgegebenen Datensätze bzw. alle validierten Elemente.
• itemFindings: vollständige Element-Datensätze, deren issues-Array nicht leer ist. Enthält ERROR-, WARNING- und INFO-Probleme. Jeder Datensatz behält id, type, valid, issues und durationMs. Archivierte Elemente verwenden type: "change".
• summary: Summen des Gesamtlaufs und Zählungen pro Typ, nicht Zählungen der zurückgegebenen Teilmenge. Ein leerer Bereich hat null Summen und beendet sich mit 0.
• root: dieselben Metadaten der ausgewählten Wurzel wie der vollständige Bericht.

Datensatz-Erhalt: zurückgegebene Elemente behalten ihre Reihenfolge aus dem vollständigen Bericht und alle additiven Felder auf Elementen oder Problemen. Die Filterung schreibt Meldungen oder Orte nicht um, einschließlich optionaler line- und column-Felder.

Befehlsfehler: Fehler bei der Wurzelauswahl oder Element-Erkennung behalten die bestehende status-Diagnose und beenden sich mit 1. Sie geben keinen abgeschlossenen Findings-Bericht oder einen erfolgreichen leeren Bericht zurück.

Ungültige Berichtsanfragen

Beide expliziten Berichtsmodi werfen diese Anfragen zurück, bevor die Wurzelauswahl oder Element-Erkennung stattfindet:

• Ein nicht unterstützter Berichtswert, einschließlich einer leeren Zeichenkette.
• Ein positioneller Element-Name, sogar mit einem Bulk-Flag.
• Kein expliziter Bulk-Bereich.
• --archived kombiniert mit --all, --changes oder --specs.

Im JSON-Modus beendet eine abgelehnte Anfrage mit 1 und nur einem einzelnen status-Array. Sie hat kein root oder Berichts-Payload:

openspec validate --all --report bogus --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."
    }
  ]
}

Der menschliche Modus gibt den Fehler auf stderr aus. Ein nacktes --report ohne Wert ist ein Commander-Syntaxfehler auf stderr, auch mit --json; es verwendet nicht diese Diagnose-Hülle.

Einen vollständigen Bericht extern filtern

Für eine benutzerdefinierte JSON-Ansicht filtern Sie den vollständigen Bericht mit jq oder PowerShell. Diese Skriptbeispiele bewahren den Validierungs-Exit-Code und lassen Befehlsfehler-Dokumente intakt.

In Bash mit jq:

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:

$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

Diese benutzerdefinierten Ansichten behalten die Schlüssel des vollständigen Berichts, lassen aber saubere Elemente weg. Sie sind weder vollständige full-v1-Berichte noch die versionierte --report findings-Form.

openspec archive

Verschiebt eine abgeschlossene Änderung ins Archiv und aktualisiert die Haupt‑Spezifikationen.

openspec archive add-rate-limit -y                # archive one change, merge its deltas
openspec archive add-rate-limit -y --skip-specs   # archive without touching the specs

Ohne Namen fordert Archive zum Auswählen einer Änderung auf. Außerhalb eines interaktiven Terminals wird es mit 1 beendet und gibt stattdessen den Befehl zur erneuten Ausführung aus.

Argumente

Argument	Was es ist
change-name	Die zu archivierende Änderung, anhand des Ordnernamens (add-rate-limit).

Optionen

Flag	Wirkung
-y, --yes	Beantwortet jede Bestätigung mit Ja: Spezifikations‑Updates, unvollständige Aufgaben, übersprungene Validierung.
--skip-specs	Archiviert, ohne die Haupt‑Spezifikationen zu berühren (Infrastruktur, Tooling oder rein dokumentarische Änderungen).
--no-validate	Überspringt die Validierung. Archive bittet zuerst um Bestätigung, und -y antwortet darauf.
--json	Gibt ein strukturiertes Ergebnis statt Text aus. Benötigt --yes, um Spezifikations‑Updates zu bestätigen.
--store <id>	Verwendet einen registrierten Store als OpenSpec‑Wurzel statt des aktuellen Projekts.

Ausgabe

Ein erfolgreicher Lauf meldet den Aufgabenstatus, zeigt eine Vorschau der Spezifikations‑Updates, wendet sie an und nennt den Archivordner:

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'.

Der Änderungsordner wird vollständig nach openspec/changes/archive/2026-08-11-add-rate-limit/ verschoben, mit dem heutigen Datum als Präfix vor dem Namen. Jedes Delta wird in seine Haupt‑Spezifikation eingebunden: Die oben hinzugefügte Anforderung wurde an openspec/specs/api/spec.md angehängt. Ohne -y zeigt Archive die Vorschau an und fragt vor der Aktualisierung nach. Ein Ablehnen archiviert die Änderung dennoch und lässt die Spezifikationen unverändert.

Mit --json --yes:

{
  "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 validiert die Änderung zunächst und verweigert die Archivierung bei Fehlern:

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.

Unvollständige Aufgaben erzeugen eine Warnung, blockieren aber nicht. Im interaktiven Modus fragt Archive, ob fortgesetzt werden soll, und -y fährt automatisch fort:

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

Exit‑Codes

• 0: Die Änderung wurde archiviert, mit oder ohne Spezifikations‑Updates.
• 1: Validierung fehlgeschlagen, Änderungsname unbekannt oder eine Bestätigung war erforderlich und es konnte keine Antwort gelesen werden.

openspec new

Erstellt ein neues Änderungsverzeichnis.

openspec new change add-caching                                # metadata only
openspec new change add-search --goal "Users can search docs"  # record a goal

new hat einen einzigen Unterbefehl, new change <name>. Er erstellt openspec/changes/<name>/ mit einer einzelnen .openspec.yaml-Metadatendatei:

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

Artefakte (Proposal, Specs, Design, Tasks) werden hier nicht erstellt. Sie werden später angelegt, und openspec status teilt Ihnen mit, welches als Nächstes an der Reihe ist.

Argumente

Argument	Was es ist
name	Ordnername für die Änderung (add-caching).

Optionen

Flag	Wirkung
--description <text>	Erstellt zusätzlich eine README.md im Änderungsverzeichnis mit diesem Text.
--goal <text>	Speichert eine goal:-Zeile in .openspec.yaml.
--schema <name>	Workflow‑Schema für die Änderung. Standard: spec-driven, das einzige mitgelieferte Schema.
--json	Gibt die erstellte Änderung als JSON statt Text aus.
--store <id>	Verwendet einen registrierten Store als OpenSpec‑Wurzel statt des aktuellen Projekts.

Ausgabe

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

Wenn kein openspec/-Verzeichnis gefunden wurde, erstellt new change eines im aktuellen Verzeichnis und teilt dies mit:

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.

Der Hinweis geht zusammen mit dem restlichen menschenlesbaren Output nach stdout und erscheint niemals mit --json.

Mit --json, in einem Projekt, das bereits openspec/ hat:

{
  "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"
  }
}

Wenn kein openspec/-Verzeichnis gefunden wurde und new change eines erstellt hat, hat das JSON die gleiche Struktur. root.path ist das Verzeichnis, aus dem Sie es ausgeführt haben, und root.source lautet implicit:

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

Exit‑Codes

• 0: Änderung erstellt.
• 1: Die Änderung existiert bereits oder das Schema ist unbekannt.

openspec status

Meldet den Abschlussstatus der Artefakte für eine Änderung oder jede aktive Änderung.

openspec status --change add-rate-limit          # checklist view
openspec status --change add-rate-limit --json   # structured report
openspec status --all                            # every active change
openspec status --all --json                     # one batch report

Wenn aktive Änderungen vorhanden sind, verwenden Sie genau eines von --change oder --all. Ohne eines davon beendet status mit Code 1 und listet die verfügbaren Änderungen auf, selbst wenn nur eine existiert:

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

Wenn das Projekt keine aktiven Änderungen hat, gibt status No active changes. Create one with: openspec new change <name> aus und beendet sich mit Code 0, auch ohne einen der beiden Flags. Mit --all --json ist derselbe leere Zustand { "changes": [], "message": "No active changes.", "root": ... }.

Optionen

Flag	Wirkung
--change <id>	Die Änderung, über die berichtet werden soll, anhand des Ordnernamens.
--all	Meldet jede aktive Änderung, sortiert nach Name. Kann nicht mit --change kombiniert werden.
--schema <name>	Überschreibt das automatisch erkannte Schema aus openspec/config.yaml. Ein unbekannter Name ist ein Fehler.
--json	Gibt einen strukturierten Bericht statt Text aus.
--store <id>	Verwendet einen registrierten Store als OpenSpec-Wurzel statt des aktuellen Projekts.

Ausgabe

Eine Checkliste der Schema-Artefakte: [x] erledigt, [ ] bereit zum Schreiben, [-] blockiert, bis die abhängigen Artefakte vorhanden sind.

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

Die Zeile Next: nennt den einen Befehl, der die Änderung voranbringt, sodass openspec status ausreicht, um eine Änderung in einer neuen Sitzung wieder aufzunehmen. Sie nennt das nächste bereitstehende Artefakt, solange die Planung nicht abgeschlossen ist, und openspec instructions apply, sobald alle Planungsartefakte vorhanden sind:

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

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

Es trägt --store <id>, wann immer die aufgelöste Wurzel ein Store ist, und nennt denselben Befehl wie der JSON-nextSteps-Satz.

--json fügt Artefakt-Abhängigkeiten, aufgelöste Dateipfade und einen vorgeschlagenen nächsten Schritt hinzu. Gekürzt:

{
  "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"
      ]
    }
  ]
}

Mit --all --json enthält changes dasselbe Statusobjekt für jede Änderung, ohne ein pro Änderung vorhandenes root. Die ausgewählte Wurzel erscheint einmal auf der Hülle. Dieses Beispiel kürzt die oben gezeigten pro Änderung vorhandenen Statusfelder:

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

Wenn eine Änderung nicht geladen werden kann, wird der Batch fortgesetzt. Ihr Eintrag enthält changeName und eine status-Diagnose, während die anderen Einträge verfügbar bleiben. Der Befehl beendet sich mit Code 1, auch im JSON-Modus, damit CI einen unvollständigen Bericht nicht als erfolgreich akzeptiert. Die JSON-Ausgabe bleibt ein parsbares Dokument.

Exit-Codes

• 0: jeder angeforderte Status ausgegeben; ein leerer --all-Bericht beendet sich ebenfalls mit 0.
• 1: eine angeforderte Änderung konnte nicht geladen werden, --change oder --all fehlt, die beiden Flags wurden kombiniert, die Änderung existiert nicht oder die Schema-Überschreibung ist unbekannt.

openspec instructions

Gibt Anweisungen zum Erstellen eines Artefakts, zum Anwenden oder Archivieren aus. Ihr Agent führt dies während des Workflows aus, um den Anweistungstext für den nächsten Schritt abzurufen.

openspec instructions proposal --change add-rate-limit   # how to write one artifact
openspec instructions apply --change add-rate-limit      # how to implement the change
openspec instructions archive --change add-rate-limit    # inputs for archiving

Argumente

Argument	Was es ist
artifact	Eine Artefakt-ID aus dem Schema (proposal, specs, design, tasks in spec-driven) oder die reservierten Wörter apply und archive.

Optionen

Flag	Wirkung
--change <id>	Die Änderung, für die Anweisungen generiert werden sollen. Erforderlich.
--schema <name>	Überschreibt das Schema. Andernfalls automatisch erkannt aus config.yaml.
--json	Gibt ein strukturiertes Objekt statt Text aus.
--store <id>	Verwendet einen registrierten Store als OpenSpec-Wurzel statt des aktuellen Projekts.

Ausgabe

Die Artefaktform gibt einen Anweisungsblock aus: die Aufgabe, die zu schreibende Datei, wie sie zu schreiben ist, die Vorlage des Artefakts und was deren Vervollständigung freischaltet.

<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 gibt Kontextdateien, Aufgabenfortschritt und die Arbeitsanweisung aus:

## 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.

Wenn erforderliche Artefakte fehlen, meldet apply ### ⚠️ Blocked und nennt sie stattdessen. archive gibt den Änderungsnamen sowie jeden Projektkontext und jede Betriebsanleitung aus der Konfiguration aus. Wenn keiner konfiguriert ist, sagt es dies und nichts weiter.

Mit --json gibt jede Form ein Objekt zurück. Die Artefaktform beginnt:

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

und fährt fort mit outputPath, existingOutputPaths, den vollständigen instruction- und template-Strings, dependencies, unlocks und root. Die apply-Form trägt contextFiles, progress, tasks, taskTrackingConfigured, state (blocked, ready, all_done) und instruction.

Jeder tasks-Eintrag trägt id, description, done, sourcePath und line. sourcePath ist der absolute Pfad zur nachverfolgten Datei, die die Aufgabe bereitgestellt hat. line ist die einsbasierte Zeilennummer der Aufgaben-Checkbox in dieser Datei.

taskTrackingConfigured ist immer ein Boolean: true, wenn das Schema ein von null verschiedene apply.tracks setzt, auch wenn keine Datei übereinstimmt, und false andernfalls. Wenn eine übereinstimmende Nachverfolgungsdatei nicht gelesen werden kann, enthält unavailableTrackingFiles ihren absoluten path und den Fehler-reason. Dieses Feld wird ausgelassen, wenn jede übereinstimmende Datei lesbar ist. Lesbare Dateien tragen weiterhin zu tasks und progress bei, aber state kann nicht all_done sein, bis jede übereinstimmende Datei gelesen wurde.

Exit-Codes

• 0: Anweisungen ausgegeben.
• 1: unbekanntes Artefakt, unbekannte Änderung, unbekanntes Schema oder fehlendes --change. Jeder Fehler listet die gültigen Werte auf.

openspec templates

Gibt die aufgelösten Vorlagenpfade für die Artefakte eines Schemas aus.

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

Optionen

Flag	Wirkung
--schema <name>	Schema zum Auflösen. Standard: spec-driven.
--json	Gibt eine JSON-Zuordnung von Artefakt-IDs zu Vorlagenpfaden aus.

Ausgabe

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 benennt, woher das Schema aufgelöst wurde: project (openspec/schemas/ in Ihrem Projekt), user (eine globale Überschreibung) oder package (in der CLI integriert). Projekt schlägt Benutzer, Benutzer schlägt Paket.

{
  "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"
  }
}

Exit-Codes

• 0: Pfade ausgegeben.
• 1: unbekanntes Schema. Der Fehler listet verfügbare Schemas auf.

openspec schemas

Listet verfügbare Workflow-Schemas auf.

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

Optionen

Flag	Wirkung
--json	Ausgabe als JSON (für die Verwendung durch Agents).

Ausgabe

Verfügbare Schemas:

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

Schemas aus Ihrem Projekt sind mit (project) gekennzeichnet, und globale Überschreibungen sind mit (user override) gekennzeichnet.

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

Exit-Codes

• 0: Schemas aufgelistet.
• 1: die Schema-Liste konnte nicht gelesen werden.

openspec schema

Untersucht, forkt oder erstellt ein Schema (experimentell). Jeder Unterbefehl gibt zunächst Note: Schema commands are experimental and may change. auf stderr aus.

openspec schema which spec-driven          # woher ein Schema aufgelöst wird
openspec schema fork spec-driven my-flow   # ein Schema in das Projekt kopieren
openspec schema init my-schema             # ein Schema von Grund auf erstellen

Unterbefehl	Zweck
which	Zeigt, woher ein Schema aufgelöst wird.
validate	Prüft die Struktur und Vorlagen eines Schemas.
fork	Kopiert ein vorhandenes Schema in das Projekt zur Anpassung.
init	Erstellt ein neues projektlokales Schema.

Schemas werden von drei Speicherorten aufgelöst. Die erste Übereinstimmung gewinnt:

Quelle	Speicherort
project	openspec/schemas/ im aktuellen Projekt.
user	~/.local/share/openspec/schemas/ (XDG_DATA_HOME und Windows %LOCALAPPDATA% werden berücksichtigt).
package	Die mit der CLI ausgelieferten Schemas. spec-driven befindet sich hier.

openspec schema which

Zeigt, welche Kopie eines Schemas die CLI verwenden wird.

openspec schema which spec-driven
openspec schema which --all        # alle Schemas, gruppiert nach Quelle

Argumente

Argument	Beschreibung
name	Das zu suchende Schema. Erforderlich, sofern --all nicht gesetzt ist. Ohne beides endet which mit Code 1.

Optionen

Flag	Wirkung
--all	Listet alle Schemas mit ihrer Auflösungsquelle auf.
--json	Gibt die Auflösung als JSON aus.

Ausgabe

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

Wenn eine Kopie mit höherer Priorität eine andere verdeckt, listet ein Abschnitt Shadows: die verdeckten Kopien auf. Mit --json:

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

Ein unbekannter Name führt zu Exit-Code 1 und listet die verfügbaren Schemas auf.

openspec schema validate

Prüft die Struktur und Vorlagen eines Schemas.

openspec schema validate spec-driven   # ein Schema, von beliebiger Quelle
openspec schema validate               # alle projektlokalen Schemas

Es wird überprüft, ob schema.yaml vorhanden ist und geparst werden kann, ob die Struktur dem Schema-Format entspricht, ob die Vorlagendatei jedes Artefakts innerhalb des templates/-Verzeichnisses des Schemas vorhanden ist und ob der Abhängigkeitsgraph keine Zyklen oder unbekannte Referenzen enthält, einschließlich in apply.requires. Ein apply.tracks-Wert, der nicht exakt dem generates-Wert eines Artefakts entspricht, gibt eine Zeile mit warning: aus, führt jedoch nicht zu einem Validierungsfehler, da OpenSpec in diesem Fall nicht erkennen kann, zu welchem Artefakt der Fortschritt dieser Datei gehört.

Optionen

Flag	Wirkung
--json	Gibt einen strukturierten Bericht statt Text aus.
--verbose	Gibt jeden Validierungsschritt aus.

Ausgabe

✓ Schema 'spec-driven' is valid

Ohne Namen erhält jedes Projektschema eine Zeile unter der Überschrift Validation Results:. Ein fehlgeschlagenes Schema listet seine Probleme auf und der Lauf endet mit Code 1:

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

openspec schema fork

Kopiert ein vorhandenes Schema in das Projekt, damit Sie es anpassen können.

openspec schema fork spec-driven my-flow

Argumente

Argument	Beschreibung
source	Das zu kopierende Schema, von beliebigem Speicherort.
name	Name für die Kopie. Kebab-case (my-workflow). Standard: <source>-custom.

Optionen

Flag	Wirkung
--force	Überschreibt ein vorhandenes Zielschema.
--json	Gibt das Ergebnis als JSON aus.

Ausgabe

✔ 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

Der Fork landet in openspec/schemas/, und das Feld name: in dessen schema.yaml wird auf den neuen Namen umgeschrieben:

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

Ein vorhandenes Ziel ist ein Fehler, sofern --force nicht übergeben wird. Ein Fork, der den Namen der Quelle beibehält, überschattet das Original.

openspec schema init

Erstellt ein neues projektlokales Schema mit Startvorlagen.

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

Ohne --description und ohne --artifacts in einem interaktiven Terminal fragt init nach einer Beschreibung, einer Artefakt-Checkliste und ob das Schema zum Projektstandard gemacht werden soll. Außerhalb eines Terminals werden die Standardwerte unten verwendet.

Argumente

Argument	Beschreibung
name	Name für das neue Schema. Kebab-case (my-workflow).

Optionen

Flag	Wirkung
--description <text>	Schema-Beschreibung. Standard: Custom workflow schema for <name>.
--artifacts <list>	Kommagetrennte Artefakt-IDs aus proposal, specs, design, tasks. Standard: alle vier.
--default	Schreibt schema: <name> in die vorhandene openspec/config.yaml oder openspec/config.yml. Erstellt openspec/config.yaml, wenn keines von beiden vorhanden ist. Neue Änderungen verwenden dieses Schema.
--no-default	Überspringt die Abfrage zum Standard.
--force	Überschreibt ein vorhandenes Schema mit demselben Namen.
--json	Gibt das Ergebnis als JSON aus.

Die Schemaerstellung und die --default-Konfigurationsaktualisierung sind ein einziger Vorgang. Wenn OpenSpec die Konfiguration nicht validieren oder schreiben kann, lässt es sowohl die Konfiguration als auch ein vorhandenes Schema unverändert.

Ausgabe

✔ Created schema 'my-schema'

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

Artifacts: proposal, tasks

Das Layout auf der Festplatte:

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

schema.yaml verknüpft die ausgewählten Artefakte mit ihren Abhängigkeiten. Wenn tasks enthalten ist, erhält es zusätzlich eine apply-Phase, die tasks.md verfolgt. Verwenden Sie das Schema mit openspec new --schema my-schema.

openspec store

Erstellt und verwaltet Stores: eigenständige OpenSpec-Repos, die auf Ihrem Rechner registriert sind.

openspec store setup team-context --path ~/openspec/team-context   # erstellen und registrieren
openspec store register ~/stores/design-system                     # einen vorhandenen Checkout registrieren
openspec store list                                                # registrierte Stores anzeigen

Registrierungen befinden sich in einer rechnerbezogenen Registry: ~/.local/share/openspec/stores/registry.yaml, oder $XDG_DATA_HOME/openspec/stores/registry.yaml, wenn XDG_DATA_HOME gesetzt ist. Jeder Unterbefehl akzeptiert --json, um einen strukturierten Bericht statt Text auszugeben. Die Ausführung von openspec store mit einem fehlenden oder unbekannten Unterbefehl endet mit Code 1 und listet die Unterbefehle auf.

Unterbefehl	Zweck
setup [id]	Erstellt einen Store-Ordner und registriert ihn.
register [path]	Registriert einen vorhandenen Store-Ordner.
unregister <id>	Löscht die Registrierung. Der Ordner bleibt auf der Festplatte.
remove <id>	Löscht die Registrierung und entfernt den Ordner.
list (Alias ls)	Listet registrierte Stores auf.
doctor [id]	Prüft Registrierung, Metadaten und Git-Status für registrierte Stores.

openspec store setup

Erstellt einen Store-Ordner und registriert ihn.

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

In einem interaktiven Terminal fragt setup nach einem fehlenden Namen und Speicherort und bestätigt, bevor etwas erstellt wird. Außerhalb eines Terminals führt ein fehlender Name oder --path zu Exit-Code 1 mit dem Hinweis auf den zu übergebenden Parameter. Das erneute Ausführen von setup für einen registrierten Store meldet Registry: already registered.

Setup endet mit Code 1 und store_setup_inside_git_repo, wenn --path innerhalb eines anderen Git-Repository liegt, da die Initialisierung des Stores dort ein Repository in einem anderen verschachteln würde. --no-init-git erstellt kein Repository und überspringt daher diese Prüfung. Verwenden Sie es, um einen Store unter ~/openspec/<id> zu halten, wenn Ihr Home-Verzeichnis selbst ein Git-Repository ist, wie z. B. ein Dotfiles-Repo.

Argumente

Argument	Beschreibung
id	Der Store-Name. Er wird zur ID, die Sie an --store übergeben.

Optionen

Flag	Wirkung
--path <path>	Ordner, in dem der Store liegen soll (~ wird erweitert).
--init-git	Initialisiert ein Git-Repository mit einem ersten Commit. Standard.
--no-init-git	Überspringt alle Git-Aktionen: kein Init, kein erster Commit.
--remote <url>	Kannonische Clone-Quelle, die in store.yaml festgehalten wird.

Ausgabe

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 meldet, was erstellt wurde und wo es registriert wurde:

{
  "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

Registriert einen vorhandenen Store-Ordner, z. B. den Store eines Teammitglieds, den Sie geklont haben.

openspec store register ~/stores/design-system

Der Ordner muss ein intaktes openspec/-Wurzelverzeichnis enthalten. Wenn .openspec-store/store.yaml vorhanden ist, verwendet register die darin festgehaltene ID. Ohne diese Datei fragt register, bevor es diese Metadaten erstellt. Außerhalb eines interaktiven Terminals übergeben Sie stattdessen --yes. Ein Rechner kann einen Checkout pro Store-ID registrieren. Ein zweiter Pfad unter derselben ID oder derselbe Pfad unter einer zweiten ID führt zu Exit-Code 1.

Argumente

Argument	Beschreibung
path	Der zu registrierende Store-Ordner (~ wird erweitert). Erforderlich.

Optionen

Flag	Wirkung
--id <id>	Store-ID. Standardmäßig aus Metadaten oder Ordnername.
--yes	Bestätigt die Erstellung der Store-Identitätsmetadaten für ein intaktes OpenSpec-Wurzelverzeichnis.

Ausgabe

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

--json gibt dieselbe Dokumentstruktur wie store setup --json aus.

openspec store unregister

Löscht die Registrierung. Der Ordner bleibt auf der Festplatte.

openspec store unregister design-system

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

openspec store remove

Löscht die Registrierung und entfernt den Ordner.

openspec store remove design-system --yes

Interaktiv fragt remove vor dem Löschen nach. Mit --json oder außerhalb eines interaktiven Terminals erfordert das Löschen --yes:

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

Remove endet mit Code 1 und löscht nichts, wenn der Ordner keine passenden Store-Metadaten enthält oder wenn er einen anderen registrierten Store enthält (z. B. einen Store, der als Git-Submodule eingebunden ist). In diesem Fall lautet der Fehler store_remove_contains_registered_store: Führen Sie zuerst openspec store unregister <nested-id> aus, oder openspec store unregister <id>, um den Store zu vergessen, ohne Dateien zu löschen.

Optionen

Flag	Wirkung
--yes	Bestätigt die Löschung des lokalen Store-Ordners.

Ausgabe

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

openspec store list

Listet registrierte Stores auf. ls ist ein Alias.

openspec store list

OpenSpec stores (2)

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

Wenn nichts registriert ist, gibt list No stores registered. sowie die auszuführenden setup- und register-Befehle aus.

openspec store doctor

Prüft Registrierung, Metadaten und Git-Status für registrierte Stores.

openspec store doctor                # jeder registrierte Store
openspec store doctor team-context  # ein Store

Ausgabe

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

Exit-Codes

• 0: Der Bericht wurde ausgegeben, auch wenn ein Store Probleme meldet.
• 1: Der Bericht konnte nicht ausgeführt werden (z. B. eine unbekannte Store-ID).

openspec doctor

Berichtet über die Beziehungsgesundheit für den aufgelösten OpenSpec-Root.

openspec doctor                       # nächster openspec/-Root über dem aktuellen Arbeitsverzeichnis
openspec doctor --store team-context  # ein registrierter Store als Root

Doctor ist schreibgeschützt: Es klont, synchronisiert oder repariert niemals. Es berichtet, ob der Root gesund ist und ob jede in openspec/config.yaml deklarierte Referenz auf diesem Rechner auflösbar ist. Wenn kein Root über dem aktuellen Arbeitsverzeichnis und kein --store vorhanden ist, beendet es sich mit Code 1 und listet Ihre registrierten Stores auf.

Optionen

Flag	Effekt
--store <id>	Einen registrierten Store als OpenSpec-Root anstelle des aktuellen Projekts verwenden.
--json	Den Gesundheitsbericht als JSON ausgeben.

Ausgabe

Doctor

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

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

Mit --store ist der Root der Store und der Bericht fügt eine Store-Zeile hinzu:

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)

{
  "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": []
}

Exit-Codes

• 0: der Bericht wurde ausgegeben, einschließlich wenn er Probleme auflistet.
• 1: kein Root aufgelöst (kein openspec/ über dem aktuellen Arbeitsverzeichnis und kein --store), oder eine unbekannte --store-ID.

openspec context

Gibt den Arbeitskontext für den aufgelösten OpenSpec-Root aus: den Root plus jeden referenzierten Store, der in openspec/config.yaml deklariert ist, jeweils mit einem Fetch-Befehl.

openspec context                       # nächster openspec/-Root über dem aktuellen Arbeitsverzeichnis
openspec context --store team-context  # ein registrierter Store als Root
openspec context --json                # Agentenkurzfassung

Referenzen, die auf diesem Rechner nicht auflösbar sind, landen in einem Abschnitt Not available on this machine, jeweils mit einer Korrektur.

Optionen

Flag	Effekt
--store <id>	Einen registrierten Store als OpenSpec-Root anstelle des aktuellen Projekts verwenden.
--json	Die Agentenkurzfassung als JSON ausgeben.
--code-workspace <path>	Zusätzlich eine VS Code-Workspace-Datei für den Satz schreiben.
--force	Eine vorhandene --code-workspace-Datei überschreiben.

Ausgabe

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

Mit --store ist der Store der gesamte Satz:

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.

{
  "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": []
}

Workspace-Datei schreiben

--code-workspace schreibt eine VS Code-Workspace-Datei am angegebenen Pfad: einen Ordner für den Root, einen ref:<id>-Ordner pro verfügbarem referenziertem Store. Nicht verfügbare Referenzen werden übersprungen und in der Zusammenfassungszeile genannt, Wrote /Users/you/projects/my-app/openspec.code-workspace (2 folders). Die Zusammenfassung wird auf stderr ausgegeben, sodass --json stdout ein einziges JSON-Dokument bleibt. Eine vorhandene Datei beendet sich mit Code 1, es sei denn, Sie übergeben --force.

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

Exit-Codes

• 0: der Bericht wurde ausgegeben.
• 1: kein Root aufgelöst (kein openspec/ über dem aktuellen Arbeitsverzeichnis und kein --store), oder das Schreiben der --code-workspace-Datei wurde abgelehnt.

openspec workset

Erstellt, verwaltet und öffnet persönliche Arbeitsansichten. Ein Workset ist eine gespeicherte, benannte Liste von Ordnern, an denen gemeinsam gearbeitet wird.

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

Subcommand	Funktion
create [name]	Erstellen und Speichern einer benannten Arbeitsansicht aus ausgewählten Ordnern.
list, ls	Gespeicherte Worksets mit ihren Mitgliedern anzeigen.
open <name>	Ein gespeichertes Workset in Ihrem Tool öffnen (Editor-Fenster oder Agent-Session).
remove <name>	Ein gespeichertes Workset löschen (Mitgliedsordner werden niemals angefasst).

Ein Workset ist rein lokal:

• Sein Zustand liegt in einem einzigen Ordner: ~/.local/share/openspec/worksets/ ($XDG_DATA_HOME/openspec/worksets/ wenn gesetzt; %LOCALAPPDATA%\openspec\worksets\ unter Windows).
• In die Mitgliedsordner wird nichts geschrieben und nichts committet oder geteilt.
• Das Löschen dieses einen Ordners entfernt jede Spur.

openspec workset create

Speichert eine benannte Arbeitsansicht von Ordnern.

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

In einem interaktiven Terminal fragt create nach allem, was die Flags nicht bereitgestellt haben: den Namen, die Ordner einzeln, ein Tool und dann die Option, das Workset jetzt zu öffnen. Außerhalb eines interaktiven Terminals ist ein fehlender Name oder Mitglied ein Fehler. Ein bereits gespeicherter Name ist immer ein Fehler. Entfernen Sie ihn zuerst.

Argumente

Argument	Beschreibung
name	Der Workset-Name. Kebab-Case: Kleinbuchstaben, Zahlen, einzelne Bindestriche. Erforderlich außerhalb eines interaktiven Terminals.

Optionen

Flag	Wirkung
--member <member>	Mitgliedsordner als <path> oder <name>=<path>, wiederholbar. Das erste ist das primäre. Der Pfad muss ein existierender Ordner sein, und das Label standardmäßig der Name des Ordners.
--tool <id>	Bevorzugtes Tool zum Öffnen dieses Worksets. Integrierte IDs: code (VS Code), cursor (Cursor). claude und codex sind vorübergehend deaktiviert.
--json	Das gespeicherte Workset als JSON ausgeben.

Ausgabe

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

openspec workset list

Zeigt gespeicherte Worksets mit ihren Mitgliedern, sortiert nach Name.

openspec workset list   # alias: ls

Optionen

Flag	Wirkung
--json	Die Worksets als JSON ausgeben.

Ausgabe

Ein Block pro Workset: der Name, das Tool wenn vorhanden, dann eine name path-Zeile pro Mitglied. Wenn nichts gespeichert ist, gibt list No worksets saved. Create one with: openspec workset create aus.

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

Mit --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

Öffnet ein gespeichertes Workset in Ihrem Tool. Editor-Tools (code, cursor) erhalten eine generierte .code-workspace-Datei. Ein Fenster öffnet sich und der Befehl kehrt zurück. CLI-Agent-Tools (claude, codex) würden dieses Terminal mit jedem angehängten Mitglied übernehmen. Sie sind vorübergehend deaktiviert, während dieser Ablauf überarbeitet wird, daher öffnen sich Worksets vorerst in einer IDE.

openspec workset open checkout                # gespeichertes Tool oder eine Aufforderung
openspec workset open checkout --tool cursor  # dieses Tool nur dieses Mal

Argumente

Argument	Beschreibung
name	Das zu öffnende Workset.

Optionen

Flag	Wirkung
--tool <id>	Mit diesem Tool nur dieses Mal öffnen.

Ohne --tool und ohne gespeichertes Tool fordert open zur Auswahl eines installierten Tools auf. Außerhalb eines interaktiven Terminals endet es mit Code 1.

• Ein Mitgliedsordner, der nicht mehr existiert, wird mit einer Warnung übersprungen. Wenn das primäre fehlt, wird das nächste vorhandene Mitglied für dieses Öffnen zum Primären. Wenn kein Mitgliedsordner existiert, schlägt das Öffnen fehl.
• --json wird abgelehnt: open übergibt das Terminal an das Tool und hat keinen JSON-Modus.
• Wenn der Start fehlschlägt, endet der Fehler mit dem manuellen Weg: dem Pfad der Workspace-Datei und der Mitgliederliste.

Exit-Codes

• Spiegelt das Tool wider: Der Befehl endet mit dem Exit-Code des Tools, und ein Signal wird zu 128+n (130 nach Strg-C).
• 1: Unbekanntes Workset, kein Mitgliedsordner verfügbar oder kein nutzbares Tool.

openspec workset remove

Löscht ein gespeichertes Workset und seine generierte .code-workspace-Datei. Mitgliedsordner werden niemals angefasst.

openspec workset remove checkout --yes

In einem interaktiven Terminal zeigt remove das Workset an und bittet um Bestätigung. Mit --json oder außerhalb eines Terminals benötigt es --yes und endet ohne mit Code 1.

Optionen

Flag	Wirkung
--yes	Entfernung nicht interaktiv bestätigen.
--json	Die Entfernung als JSON ausgeben.

Ausgabe

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

openspec version

Meldet die laufende OpenSpec-Version und wie diese Kopie installiert wurde.

openspec version                 # lokale Version und Installationsdetails
openspec version --json          # strukturierter lokaler Bericht
openspec version --check         # zusätzlich das Registry auf Updates prüfen
openspec version --check --json  # strukturierter lokaler und Update-Bericht

Ohne --check ist dieser Befehl lokal und kontaktiert kein Registry. Er funktioniert außerhalb eines OpenSpec-Projekts. Der bestehende openspec --version-Flag bleibt die kürzeste Form und gibt nur die reine Versionsnummer aus.

Optionen

Flag	Wirkung
--json	Ein versioniertes JSON-Dokument statt Text ausgeben.
--check	Das konfigurierte Registry auf eine neuere Version prüfen.

Ausgabe

Für eine globale npm-Installation:

OpenSpec 1.13.2 (npm, global)

Der Installationsumfang ist global, project, temporary für einen ephemeren Runner wie npx, source für einen Checkout oder standalone für die Standalone-Installation. OpenSpec lässt Details, die es nicht identifizieren kann, weg, anstatt zu raten.

--json hält unbekannte Details als explizite null-Werte:

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

Mit --check fügt ein verfügbares Update die neueste Version und einen Befehl hinzu, wenn OpenSpec einen sicheren Befehl für diese Installation identifizieren kann:

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

{
  "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
  }
}

Update-Statuswerte:

Status	Bedeutung
available	Das Registry hat eine sichere Version zurückgegeben, die neuer ist als die laufende Version.
current	Die Prüfung wurde abgeschlossen und fand keine neuere Version.
disabled	Eine bestehende Datenschutz- oder Update-Prüfungseinstellung blockierte den Registry-Zugriff. latest ist null.
offline	Das Registry war nicht verfügbar oder hat eine unbrauchbare Antwort zurückgegeben. latest ist null.

Für die Standalone-Installation ist der Update-Befehl openspec install.

DO_NOT_TRACK, Telemetrie-Opt-outs, OPENSPEC_NO_UPDATE_CHECK, CI-Erkennung und abgelehnte Nicht-HTTPS-Registry-Überschreibungen deaktivieren die Prüfung. Deaktivierte und Offline-Prüfungen enden weiterhin mit 0, da die Update-Verfügbarkeit informativ ist. Dieser Befehl aktualisiert OpenSpec niemals; canSelfUpgrade meldet nur, ob der bestehende openspec update-Pfad diese Kopie sicher aktualisieren könnte.

Exit-Codes

• 0: Der lokale Bericht wurde ausgegeben, einschließlich deaktivierter oder Offline-Update-Prüfungen.
• 1: Die Befehlssyntax war ungültig, wie z. B. die nicht unterstützte --upgrade-Option.

openspec install

Installiert das standalone openspec. Führen Sie es von einer npm- oder Homebrew-Installation aus, um zu wechseln, oder von der standalone-Installation aus, um es an Ort und Stelle zu aktualisieren.

openspec install          # newest release
openspec install 1.15.0   # a specific release

Es führt das Installationsskript aus, das die neueste Version auswählt, deren Dateien alle angehängt sind und die Datei für Ihren Rechner, und diese gegen die SHA256SUMS dieser Version prüft:

• Von einem Paketmanager aus: installiert nach ~/.local/bin (Windows: %LOCALAPPDATA%\Programs\openspec) und gibt den Befehl aus, der die alte Kopie entfernt, wie z. B. npm uninstall -g @fission-ai/openspec. Es entfernt diese Kopie selbst nie.
• Von der standalone-Installation aus: ersetzt die laufende Datei an ihrem Ort unter ihrem eigenen Namen.

Anschließend wird angezeigt, welche Kopie openspec nun ausführt, da eine Kopie eines Paketmanagers, die früher in Ihrem PATH steht, weiter ausgeführt wird, bis Sie sie entfernen.

Argumente

Argument	Beschreibung
version	Zu installierende Version, wie 1.15.0. Optional; Standard ist die neueste.

OPENSPEC_INSTALL_DIR und OPENSPEC_INSTALL_NAME wählen einen anderen Ordner oder Dateinamen.

Exit-Codes

• 0: installiert.
• 1: Die Version ist keine Release-Version, oder der Download oder die Installation ist fehlgeschlagen. Ihre aktuelle Kopie bleibt unverändert.

openspec feedback

Sendet Feedback zu OpenSpec.

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

Die CLI reicht Ihre Nachricht als GitHub-Issue im Repository Fission-AI/OpenSpec über Ihre gh CLI ein. Der Titel wird Feedback: <message>. Der Text verwendet die Überschriften des Fehlerformulars: Ihre Nachricht unter What happened, Ihr --body-Text unter Details und einen Abschnitt Minimal steps to reproduce, in dem Sie aufgefordert werden, die Schritte hinzuzufügen, da die CLI diese nicht ausfüllen kann. Eine Fußzeile fügt CLI-Version, Plattform und Zeitstempel hinzu. Das Issue erhält das Label feedback. Wenn das Repository dieses Label nicht definiert, versucht die CLI es erneut ohne das Label und teilt dies mit.

Argumente

Argument	Beschreibung
message	Einzeilige Zusammenfassung. Wird zum Issue-Titel. Erforderlich.

Optionen

Flag	Wirkung
--body <text>	Längere Beschreibung, die zum Issue-Text hinzugefügt wird.

Ausgabe

Bei Erfolg:

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

Ohne installiertes gh oder wenn bei gh nicht angemeldet ist, wird nichts übermittelt. Die CLI gibt Ihr formatiertes Feedback zwischen den Markierungen --- FORMATTED FEEDBACK --- aus, dann einen Link, der das Fehlerberichtsformular mit ausgefülltem Titel, was passiert ist (Ihre Nachricht und der --body-Text), CLI-Version und Umgebung (Plattform und Node-Version) öffnet. Sie vervollständigen den Rest des Formulars im Browser. Der Pfad ohne Anmeldung fügt To auto-submit in the future: gh auth login hinzu.

Exit-Codes

• 0: Issue erstellt oder die manuelle Übermittlung wurde ausgeführt (kein gh oder gh nicht angemeldet).
• 1: keine Nachricht angegeben.
• ghs eigener Code: gh ist nach der Authentifizierung fehlgeschlagen (Netzwerk, Ratenlimit, Issues deaktiviert). Die CLI gibt zuerst Ihr Feedback und die URL für die manuelle Übermittlung erneut aus.

openspec completion

Installiert oder generiert Shell-Vervollständigungen.

openspec completion install        # detect your shell, install, wire up config
openspec completion generate zsh   # print the script to stdout

Unterstützte Shells: zsh, bash, fish, powershell. Jeder Unterbefehl akzeptiert ein optionales Shell-Argument. Lassen Sie es weg, erkennt die CLI Ihre Shell aus der Umgebung.

Unterbefehl	Funktion
generate [shell]	Gibt das Vervollständigungsskript auf stdout aus.
install [shell]	Schreibt das Skript und konfiguriert Ihre Shell-Startdatei.
uninstall [shell]	Entfernt das Skript und den Konfigurationsblock.

Bei Installation mit Nix sind die Vervollständigungen bereits vorhanden: Das flake-Paket enthält die Bash-, Fish- und Zsh-Skripte an den Standardspeicherorten, sodass install nicht erforderlich ist (Installation).

openspec completion generate

Gibt das Skript aus und schreibt nichts.

#compdef openspec

# Zsh completion script for OpenSpec CLI
# Auto-generated - do not edit manually

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

openspec completion install

Schreibt das Skript und bearbeitet Ihre Shell-Konfiguration. Konfigurationsänderungen befinden sich zwischen den Markierungen # OPENSPEC:START und # OPENSPEC:END. Ein vorhandenes Skript wird zuerst gesichert (.backup-<timestamp>-Kopie).

Shell	Skriptspeicherort	Bearbeitete Konfiguration
zsh	~/.zsh/completions/_openspec	$ZDOTDIR/.zshrc, wenn ZDOTDIR ein absoluter Pfad ist, sonst ~/.zshrc
bash	~/.local/share/bash-completion/completions/openspec	~/.bashrc
fish	~/.config/fish/completions/openspec.fish	Keine: fish lädt es automatisch.
powershell	OpenSpecCompletion.ps1 neben Ihrem Profil	$PROFILE

Mit installiertem Oh My Zsh landet das Skript stattdessen in $ZSH_CUSTOM/completions/_openspec (Standard: ~/.oh-my-zsh/custom/completions/_openspec).

Ein relativer oder mit ~ vorangestellter ZDOTDIR wird ignoriert, stattdessen wird ~/.zshrc bearbeitet. Wenn Sie die Installation erneut ausführen, während das Skript bereits aktuell ist, wird der Block weiterhin zur .zshrc hinzugefügt, die zsh liest.

Optionen

Flag	Wirkung
--verbose	Gibt außerdem den installierten Pfad, einen etwaigen Sicherungspfad und die bearbeitete Konfigurationsdatei aus.

Ausgabe

✓ Completion script installed and .zshrc configured successfully

Restart your shell or run: exec zsh

openspec completion uninstall

Entfernt das Skript und den markierten Konfigurationsblock. Es fragt vor der Änderung Ihrer Konfiguration nach (Standard: Nein).

Für zsh bereinigt es die .zshrc, die install bearbeitet, und auch ~/.zshrc, wenn eine ältere Installation dort unter ZDOTDIR einen Block hinterlassen hat. Wenn ein Block nicht entfernt werden kann, nennt uninstall die Datei und beendet sich mit 1.

Optionen

Flag	Wirkung
-y, --yes	Bestätigungsabfragen überspringen.

Ausgabe

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

Exit-Codes

• 0: Skript generiert, installiert oder entfernt. Ein abgebrochenes uninstall beendet sich ebenfalls mit 0.
• 1: Shell nicht unterstützt oder nicht erkannt, oder ein Installations- oder Deinstallationsschritt ist fehlgeschlagen.

openspec change

Veraltete Substantivform von show, list und validate. Jeder Aufruf warnt und verweist auf die Verb-zuerst-Befehle und führt dann trotzdem aus:

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

Veraltet	Stattdessen verwenden
openspec change show <name>	openspec show <name>
openspec change list	openspec list
openspec change validate <name>	openspec validate <name> (alle Änderungen: openspec validate --changes)

Die Abschnitte zu den Verb-zuerst-Befehlen dokumentieren die Flags.

openspec spec

Veraltete Substantivform von show, list und validate. Jeder Aufruf warnt und verweist auf die Verb-zuerst-Befehle und führt dann trotzdem aus:

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

Veraltet	Stattdessen verwenden
openspec spec show <id>	openspec show <id>
openspec spec list	openspec list --specs
openspec spec validate <id>	openspec validate <id> (alle Specs: openspec validate --specs)

Die Abschnitte zu den Verb-zuerst-Befehlen dokumentieren die Flags.