# update

> Ein installiertes Projekt auf eine neuere BMAD+-Version bringen, mit Plan, Backups und einem wiederherstellbaren Beleg: Optionen, Erhaltenes, Ablehnungen, Wiederherstellung und jede Meldung.

Canonical: https://bmad-plus.rochetta.fr/de/docs/reference/cli-update/
Language: de
BMAD+ version: 0.23.1
Documentation reviewed: 2026-10-19
Author: Laurent Rochetta
License: MIT

BMAD+ Dokumentation › [Referenz](https://bmad-plus.rochetta.fr/de/docs/reference/) › update

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

<a id="synopsis"></a>
## Syntax

**Im Terminal deines Projekts**

```sh
npx bmad-plus@latest update [-d <path>] [-y] [-l <code>] [--latest] [--expected-version <v>] [--auto]
npx bmad-plus update --restore <receipt-id> [-d <path>] [-y]
```

**Optionen von update**

| Option | Argument | Was sie tut |
| --- | --- | --- |
| `-d, --directory <path>` | Ordner | 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`. |

<a id="two-paths"></a>
## Zwei Wege zur Versionswahl

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

<a id="what-changes"></a>
## Was sich ändert und was bleibt

**Wie update jede Dateiart behandelt**

| Datei | Behandlung |
| --- | --- |
| 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`).

<a id="exit-codes"></a>
## Exit-Codes

**Exit-Codes von update**

| Code | Bedeutung |
| --- | --- |
| 0 | Aktualisiert, wiederhergestellt, nichts zu aktualisieren, Rückfrage abgelehnt, oder `--latest` hat das Ziel gemeldet und wartet auf `--yes`. |
| 1 | Jeder Fehler: nicht installiert, abgelehnt, Sperrkonflikt, gescheitert mit Rollback, kein Terminal und kein `--yes`. |

<a id="real-output"></a>
## Ausgabe

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 Konflikt** (Simuliert)

```text
$ npx bmad-plus@<new> update
Installed: 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.json
BMAD+ v<new> applied partially. Reload your agent instructions or start a new session.
```

Beispielhafter Ablauf, nicht bei einem echten Lauf aufgezeichnet. Quelle: tools/cli/commands/update.js Zeilen 120-190

**Neueste Version, Freigabe erbeten und dann erteilt** (Simuliert)

```text
$ npx bmad-plus update --latest
Confirm this exact update with --yes.
Target: v<new>
# Nichts wurde geändert; Exit-Code 0.
$ npx bmad-plus update --latest --yes
updated
# 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

<a id="recovery"></a>
## Wiederherstellung mit --restore

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.

<a id="errors"></a>
## Fehler und was zu tun ist

**Meldungen von update**

| Meldung | Ursache | Was tun |
| --- | --- | --- |
| `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. |
| `...; rolled-back. Recovery: bmad-plus update --restore <id> ...` | Ein Schreibvorgang scheiterte; die Änderungen wurden zurückgenommen. | Ursache beheben und erneut versuchen; den ausgegebenen Befehl nur nutzen, wenn Dateien falsch aussehen. |
| `Installation changed since this receipt; recovery refused.` | Das Manifest ist weder das von vor noch das von nach dem Beleg. | Nur aus dem jüngsten Beleg wiederherstellen. |
| `Backup is missing or corrupt: <file>` / `File changed since the update: <file>` | Eine gesicherte Datei wurde gelöscht oder bearbeitet. | Die Datei aus deiner eigenen Historie holen, dann erneut versuchen. |

<a id="examples"></a>
## Beispiele

<a id="example-cli-update-ask-assistant"></a>
### Den Assistenten prüfen und aktualisieren lassen

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

```text
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.

**Von Hand, mit Rückfrage und Beleg**

```sh
npx bmad-plus update-check
npx bmad-plus update --latest --yes
# something looks wrong afterwards:
npx bmad-plus update --restore <receipt-id> --yes
```

**Siehe auch**

- [update-check](https://bmad-plus.rochetta.fr/de/docs/reference/cli-update-check/)
- [update-policy](https://bmad-plus.rochetta.fr/de/docs/reference/cli-update-policy/)
- [doctor](https://bmad-plus.rochetta.fr/de/docs/reference/cli-doctor/)
- [install](https://bmad-plus.rochetta.fr/de/docs/reference/cli-install/)
- [Der ganze Lebenszyklus](https://bmad-plus.rochetta.fr/de/docs/guides/install-lifecycle/)
- [Fehlerbehebung](https://bmad-plus.rochetta.fr/de/docs/faq/troubleshooting/)

[BMAD+ Dokumentation](https://bmad-plus.rochetta.fr/de/docs/) · [Referenz](https://bmad-plus.rochetta.fr/de/docs/reference/)

[Quellcode auf GitHub](https://github.com/lrochetta/BMAD-PLUS)