Ein installiertes Projekt auf eine neuere BMAD+-Version bringen, mit Plan, Backups und einem wiederherstellbaren Beleg: Optionen, Erhaltenes, Ablehnungen, Wiederherstellung und jede Meldung.
update nimmt ein Projekt, das schon BMAD+ hat, und bringt dessen Dateien auf die Version des Pakets, das du startest. Es arbeitet nie blind: Zuerst berechnet es aus dem bei der Installation geführten Besitzinventar einen Plan, zeigt, wie viele Dateien sich ändern und welche es unangetastet lässt, weil du sie bearbeitet hast, fragt nach Bestätigung, sichert alles, schreibt, prüft und hinterlässt einen Beleg. Scheitert unterwegs etwas, rollt es zurück, und ein abgeschlossenes Update lässt sich später mit --restore rückgängig machen.
Zu aktualisierendes Projekt (Standard: aktueller Ordner).
-y, --yes
-
Ohne Rückfrage bestätigen. Ohne Terminal Pflicht.
-l, --lang <code>
Sprachcode
Sprache der Bestätigungstexte. Standard: die bei der Installation gespeicherte Sprache.
--latest
-
Nicht das laufende Paket nutzen, sondern die neueste kompatible Version auf npm suchen und genau diese starten. Ohne --yes oder --auto meldet es nur, was es starten würde.
--expected-version <version>
exakte Version
Ablehnen, wenn das laufende Paket nicht genau diese Version ist. Der Updater nutzt das selbst als Sicherung.
--auto
-
Nur anwenden, wenn die Update-Richtlinie des Projekts es erlaubt, das Besitzinventar vollständig ist und kein Konflikt besteht. Braucht --expected-version.
--restore <receipt-id>
Beleg-ID
Die von einem früheren Update gesicherten Dateien zurückspielen. Nicht kombinierbar mit --latest, --expected-version oder --auto.
Das schlichte update nutzt das laufende Paket. npx bmad-plus@0.23.0 update bringt das Projekt auf 0.23.0. Sind installierte und laufende Version gleich, gibt es „Nothing to update.“ aus und endet.
update --latest fragt npm (update-check macht dieselbe Abfrage) nach dem neuesten Release deines Update-Kanals, prüft, dass es neuer, zulässig, mit deinem Node kompatibel und von deiner Richtlinie erlaubt ist, und startet dann npm exec mit genau dieser Version in einem temporären Ordner mit update --yes --expected-version <version>. Ohne --yes (oder --auto) hält es nach der Nennung des Ziels an: Der Bericht ist die Freigabeanfrage.
Nach --latest wird das Manifest erneut gelesen. Zeigt es nicht die Zielversion, schlägt der Befehl fehl und bittet dich, das Projekt zu prüfen.
Agenten, Skills, Daten und Moduldateien, die du nicht angefasst hast
Nach einem Backup durch die neue Version ersetzt.
Verwaltete Dateien, die du bearbeitet hast (modified-managed-file)
Bleiben unverändert und werden als erhaltener Konflikt aufgelistet.
Eine im Weg stehende Datei, die BMAD+ nie verzeichnet hat (unowned-file)
Bleibt unverändert, wird als Konflikt aufgelistet.
Dateien, die die neue Version nicht mehr mitliefert
Unverändert: mit Backup entfernt; von dir bearbeitet: behalten und aufgelistet (modified-orphaned-file). Leere Ordner werden aufgeräumt.
AGENTS.md und Tool-Dateien mit BMAD+-Marke und ohne Änderung
Werden neu erzeugt.
Anweisungsdateien, die du geschrieben oder nach der Installation bearbeitet hast (local-instructions, repository-adopted)
Bleiben unverändert, werden als Konflikt aufgelistet.
_bmad/config.yaml, Memory, _bmad-output/
Werden nicht angefasst.
Alte Installationen ohne vollständiges Besitzinventar
Originale Pack-Dateien werden vor dem Ersetzen gesichert, mit Warnung; ältere Anweisungsdateien als <file>.bak. --auto lehnt ab.
Ein Backup jeder Datei, die das Update ändert, liegt unter .bmad/updates/<receipt-id>/backups/ neben receipt.json. Der Beleg hält den Stand des Updates fest: prepared, committed, rolled-back, recovery-required oder restored. Es kann immer nur eine Installation oder ein Update laufen (.bmad/update.lock).
In den Abnahmeläufen von 0.23.0 wurde kein Update aufgezeichnet; die beiden Mitschriften unten sind daher aus den Meldungsvorlagen im Code zusammengesetzt (Versionen und Zahlen sind Platzhalter) und als simuliert gekennzeichnet.
Ein einfaches Update mit einem erhaltenen KonfliktSimuliert
$ npx bmad-plus@<new> updateInstalled: v<old> -> Executing package: v<new>Planned changes: <N> files (<R> no longer shipped, removed with backup); preserved conflicts: 1.CLAUDE.md: preserved (local-instructions).? Apply this update from v<old> to v<new>? Yes<N> files updated; 1 local conflicts preserved.Receipt and backups: <project>/.bmad/updates/<receipt-id>/receipt.jsonBMAD+ v<new> applied partially. Reload your agent instructions or start a new session.
npx bmad-plus@<new> update
Beispielhafter Ablauf, nicht bei einem echten Lauf aufgezeichnet. Quelle: tools/cli/commands/update.js Zeilen 120-190
Neueste Version, Freigabe erbeten und dann erteiltSimuliert
$ npx bmad-plus update --latestConfirm this exact update with --yes.Target: v<new># Nichts wurde geändert; Exit-Code 0.$ npx bmad-plus update --latest --yesupdated# Der Updater, den dieser Befehl startet, gibt hier seine eigenen Zeilen aus (den Plan, die Belege und die Zeile „applied“, wie in der vorigen Mitschrift); sie sind ausgelassen.Target: v<new>Reload your agent instructions or start a new session.
Beispielhafter Ablauf, nicht bei einem echten Lauf aufgezeichnet. Quelle: tools/cli/lib/update-dispatch.js Zeilen 110-180 und tools/cli/commands/update.js Zeilen 62-74
Scheitert ein Update, nachdem es zu schreiben begonnen hat, rollt es sich selbst zurück und endet mit einer Zeile wie ; rolled-back. Recovery: bmad-plus update --restore <id> --directory "<dir>" --yes. Die Beleg-ID ist zugleich der Ordnername unter .bmad/updates/. --restore prüft, dass jede gesicherte Datei noch zu ihrem verzeichneten Hash passt, dass das aktuelle Manifest das von vor oder nach diesem Update ist und dass kein lebendes Update die Sperre hält; dann spielt es die alten Dateien zurück und markiert den Beleg als restored. Hat sich seit dem Update eine Datei geändert, wird nichts wiederhergestellt: Der Befehl lehnt ab und nennt sie.
No BMAD+ installation found in <dir> (missing _bmad/.bmad-plus-install.json).
Du bist im falschen Ordner, oder BMAD+ ist nicht installiert.
Aus dem Projektordner starten, --directory angeben oder zuerst installieren.
--restore cannot be combined with --latest or --expected-version.
Unverträgliche Optionen.
Die Wiederherstellung allein ausführen.
Automatic update requires --expected-version.
--auto ohne Zielversion.
--expected-version <v> ergänzen oder --latest --auto das erledigen lassen.
Executing package version X does not match expected version Y.
Das laufende Paket ist nicht das genannte.
npx bmad-plus@Y update ... ausführen.
Downgrade refused: A -> B
Das laufende Paket ist älter als die installierte Version.
Ein neueres Paket starten.
Automatic update refused: <reason>
Die Richtlinie erlaubt es nicht (approval-required, updates-disabled, outside-allowed-range, prerelease-not-allowed), oder das Projekt ist alt bzw. hat Konflikte.
Mit update-policy ansehen oder von Hand mit update --latest --yes freigeben.
Update refused: <reason>.
Eine Sicherheitsprüfung von --latest ist gescheitert: updates-disabled, automatic-updates-not-authorized (--auto, während der Richtlinienmodus nicht auto ist), fresh-metadata-required, policy-channel-changed, downgrade-not-allowed, ownership-preflight-failed, incompatible-or-invalid-node-engine u. a.
Grund lesen, Ursache beheben, erneut versuchen. fresh-metadata-required heißt meist, npm war nicht erreichbar.
Updater finished without the expected manifest version X. Inspect the project before retrying.
Der verschachtelte Updater endete, aber das Manifest zeigt das Ziel nicht.
doctor ausführen; nicht blind wiederholen.
Another update is in progress: <path>.
Die Projektsperre ist belegt.
Warten; wurde sie unterbrochen, sagt doctor, wann sie veraltet ist und welche Datei zu löschen ist.
File changed after preflight: <file>
Eine Datei änderte sich zwischen Plan und Schreiben.
Erneut versuchen; das Update hatte noch nicht zu schreiben begonnen.
Jede erzeugte Anweisungsdatei weist den Assistenten an, einmal pro Sitzung zu prüfen und die Projektrichtlinie zu befolgen. Du kannst ihn ausdrücklich darum bitten.
In deinem KI-Assistenten
Gibt es eine neuere BMAD+-Version für dieses Projekt? Wenn unsere Richtlinie das Update erlaubt, wende es an und sag mir danach, was erhalten blieb.
Das solltest du erhalten Der Assistent führt npx bmad-plus update-check --json aus. Sind updateAvailable und canAutoApply beide wahr, startet er update --latest --auto; gibt es ein Update, das sich nicht automatisch anwenden lässt, erklärt er Version und Grund und wendet es nur deshalb mit update --latest --yes an, weil du darum gebeten hast. Er ändert nicht die Richtlinie, überschreibt keine angepassten Dateien und löst Konflikte nicht eigenmächtig. Danach liest er die Projektanweisungen neu und berichtet die erhaltenen Konflikte, die der Befehl aufgelistet hat.