# update

> Faire passer un projet installé à une version plus récente de BMAD+ avec un plan, des sauvegardes et un reçu restaurable : options, fichiers préservés, refus, récupération et chaque message.

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

Documentation BMAD+ › [Référence](https://bmad-plus.rochetta.fr/fr/docs/reference/) › update

`update` prend un projet qui a déjà BMAD+ et amène ses fichiers à la version du paquet que vous lancez. Elle ne travaille jamais à l’aveugle : elle calcule d’abord un plan à partir de l’inventaire de propriété enregistré à l’installation, indique combien de fichiers changent et lesquels elle laisse tels quels parce que vous les avez modifiés, demande confirmation, sauvegarde tout, écrit, vérifie et laisse un reçu. Si quelque chose échoue en route, elle revient en arrière, et une mise à jour terminée peut être annulée plus tard avec `--restore`.

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

**Dans le terminal de votre projet**

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

**Options de update**

| Option | Argument | Ce qu’elle fait |
| --- | --- | --- |
| `-d, --directory <path>` | dossier | Projet à mettre à jour (par défaut : dossier courant). |
| `-y, --yes` | - | Confirmer sans demander. Obligatoire sans terminal. |
| `-l, --lang <code>` | code de langue | Langue des textes de confirmation. Par défaut, la langue enregistrée à l’installation. |
| `--latest` | - | Ne pas utiliser le paquet que vous lancez : chercher la dernière version compatible sur npm et lancer exactement celle-ci. Sans `--yes` ni `--auto`, elle indique seulement ce qu’elle lancerait. |
| `--expected-version <version>` | version exacte | Refuser sauf si le paquet lancé est exactement cette version. Utilisé par l’outil de mise à jour lui-même comme garde-fou. |
| `--auto` | - | N’appliquer que si la politique de mise à jour du projet l’autorise, si l’inventaire de propriété est complet et si rien n’est en conflit. Demande `--expected-version`. |
| `--restore <receipt-id>` | identifiant de reçu | Remettre les fichiers sauvegardés par une mise à jour précédente. Incompatible avec `--latest`, `--expected-version` et `--auto`. |

<a id="two-paths"></a>
## Deux façons de choisir la version

- `update` seule utilise le paquet que vous lancez. `npx bmad-plus@0.23.0 update` amène le projet en 0.23.0. Quand la version installée et la version lancée sont égales, elle affiche « Nothing to update. » et s’arrête.
- `update --latest` interroge npm (`update-check` fait la même recherche) pour la version la plus récente de votre canal de mise à jour, vérifie qu’elle est plus récente, éligible, compatible avec votre Node et autorisée par votre politique, puis lance `npm exec` sur exactement cette version, dans un dossier temporaire, avec `update --yes --expected-version <version>`. Sans `--yes` (ni `--auto`), elle s’arrête après avoir nommé la cible : le rapport vaut demande d’approbation.
- Après `--latest`, le manifeste est relu. S’il n’affiche pas la version cible, la commande échoue et vous demande d’inspecter le projet.

<a id="what-changes"></a>
## Ce qu’elle change et ce qu’elle garde

**Comment update traite chaque sorte de fichier**

| Fichier | Traitement |
| --- | --- |
| Agents, compétences, données et fichiers de module que vous n’avez pas touchés | Remplacés par la nouvelle version après sauvegarde. |
| Fichiers gérés que vous avez modifiés (`modified-managed-file`) | Laissés tels quels et listés comme conflit préservé. |
| Un fichier gênant que BMAD+ n’a jamais enregistré (`unowned-file`) | Laissé tel quel, listé comme conflit. |
| Fichiers que la nouvelle version ne livre plus | Supprimés avec sauvegarde s’ils sont inchangés ; gardés et listés (`modified-orphaned-file`) si vous les avez modifiés. Les dossiers vides sont nettoyés. |
| `AGENTS.md` et fichiers d’outils portant la marque BMAD+ et inchangés | Régénérés. |
| Fichiers d’instructions que vous avez écrits ou modifiés après l’installation (`local-instructions`, `repository-adopted`) | Laissés tels quels, listés comme conflit. |
| `_bmad/config.yaml`, mémoire, `_bmad-output/` | Non touchés. |
| Installations anciennes sans inventaire de propriété complet | Les fichiers d’origine des packs sont sauvegardés avant remplacement, avec un avertissement ; les anciens fichiers d’instructions sont enregistrés en `<file>.bak`. `--auto` refuse. |

Une sauvegarde de chaque fichier que la mise à jour modifie est rangée sous `.bmad/updates/<receipt-id>/backups/`, à côté de `receipt.json`. Le reçu note l’état de la mise à jour : `prepared`, `committed`, `rolled-back`, `recovery-required` ou `restored`. Une seule installation ou mise à jour peut tourner à la fois (`.bmad/update.lock`).

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

**Codes de sortie de update**

| Code | Signification |
| --- | --- |
| 0 | Mis à jour, restauré, rien à mettre à jour, question refusée, ou `--latest` a indiqué la cible et attend `--yes`. |
| 1 | Toute erreur : non installé, refus, conflit de verrou, échec avec retour en arrière, pas de terminal et pas de `--yes`. |

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

Aucune mise à jour n’a été enregistrée dans les recettes de la 0.23.0 ; les deux transcriptions ci-dessous sont donc composées à partir des modèles de messages du code (numéros de version et nombres sont des marqueurs) et signalées comme simulées.

**Une mise à jour simple avec un conflit préservé** (Simulé)

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

Transcription illustrative, non capturée lors d’une exécution réelle. Source: tools/cli/commands/update.js lignes 120-190

**Dernière version, approbation demandée puis donnée** (Simulé)

```text
$ npx bmad-plus update --latest
Confirm this exact update with --yes.
Target: v<new>
# Rien n’a changé ; code de sortie 0.
$ npx bmad-plus update --latest --yes
updated
# L’outil de mise à jour que cette commande lance affiche ici ses propres lignes (le plan, le reçu et la ligne « applied », comme dans la transcription précédente) ; elles sont omises.
Target: v<new>
Reload your agent instructions or start a new session.
```

Transcription illustrative, non capturée lors d’une exécution réelle. Source: tools/cli/lib/update-dispatch.js lignes 110-180 et tools/cli/commands/update.js lignes 62-74

<a id="recovery"></a>
## Récupération avec --restore

Si une mise à jour échoue après avoir commencé à écrire, elle revient en arrière d’elle-même et se termine par une ligne du type `; rolled-back. Recovery: bmad-plus update --restore <id> --directory "<dir>" --yes`. L’identifiant du reçu est aussi le nom du dossier sous `.bmad/updates/`. `--restore` vérifie que chaque fichier sauvegardé correspond encore à son empreinte enregistrée, que le manifeste actuel est celui d’avant ou d’après cette mise à jour et qu’aucune mise à jour vivante ne tient le verrou ; puis elle remet les anciens fichiers et marque le reçu `restored`. Rien n’est restauré si un fichier a changé depuis la mise à jour : la commande refuse et le nomme.

<a id="errors"></a>
## Erreurs et que faire

**Messages de update**

| Message | Cause | Que faire |
| --- | --- | --- |
| `No BMAD+ installation found in <dir> (missing _bmad/.bmad-plus-install.json).` | Vous êtes dans le mauvais dossier, ou BMAD+ n’est pas installé. | Lancez depuis le dossier du projet, passez `--directory`, ou installez d’abord. |
| `--restore cannot be combined with --latest or --expected-version.` | Options incompatibles. | Lancez la restauration seule. |
| `Automatic update requires --expected-version.` | `--auto` sans version cible. | Ajoutez `--expected-version <v>`, ou laissez `--latest --auto` le faire. |
| `Executing package version X does not match expected version Y.` | Le paquet lancé n’est pas celui que vous avez nommé. | Lancez `npx bmad-plus@Y update ...`. |
| `Downgrade refused: A -> B` | Le paquet lancé est plus ancien que la version installée. | Lancez un paquet plus récent. |
| `Automatic update refused: <reason>` | La politique ne l’autorise pas (`approval-required`, `updates-disabled`, `outside-allowed-range`, `prerelease-not-allowed`), ou le projet est ancien ou en conflit. | Consultez-la avec `update-policy`, ou approuvez à la main avec `update --latest --yes`. |
| `Update refused: <reason>.` | Un contrôle de sécurité de `--latest` a échoué : `updates-disabled`, `automatic-updates-not-authorized` (`--auto` alors que le mode de la politique n’est pas `auto`), `fresh-metadata-required`, `policy-channel-changed`, `downgrade-not-allowed`, `ownership-preflight-failed`, `incompatible-or-invalid-node-engine`, etc. | Lisez la raison, corrigez sa cause, réessayez. `fresh-metadata-required` signifie en général que npm était injoignable. |
| `Updater finished without the expected manifest version X. Inspect the project before retrying.` | L’outil imbriqué s’est terminé mais le manifeste n’affiche pas la cible. | Lancez `doctor` ; ne réessayez pas à l’aveugle. |
| `Another update is in progress: <path>.` | Le verrou du projet est tenu. | Attendez ; s’il a été interrompu, `doctor` dit quand il est périmé et quel fichier supprimer. |
| `File changed after preflight: <file>` | Un fichier a changé entre le plan et l’écriture. | Réessayez ; la mise à jour n’avait pas commencé à écrire. |
| `...; rolled-back. Recovery: bmad-plus update --restore <id> ...` | Une écriture a échoué ; les changements ont été annulés. | Corrigez la cause et réessayez ; n’utilisez la commande affichée que si des fichiers semblent faux. |
| `Installation changed since this receipt; recovery refused.` | Le manifeste n’est ni celui d’avant ni celui d’après le reçu. | Ne restaurez qu’à partir du reçu le plus récent. |
| `Backup is missing or corrupt: <file>` / `File changed since the update: <file>` | Un fichier sauvegardé a été supprimé ou modifié. | Récupérez ce fichier depuis votre propre historique, puis réessayez. |

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

<a id="example-cli-update-ask-assistant"></a>
### Laisser l’assistant vérifier et mettre à jour

Chaque fichier d’instructions généré demande à l’assistant de vérifier une fois par session et de suivre la politique du projet. Vous pouvez le lui demander explicitement.

**Dans votre assistant IA**

```text
Existe-t-il une version plus récente de BMAD+ pour ce projet ? Si notre politique autorise la mise à jour, applique-la, puis dis-moi ce qui a été préservé.
```

**Ce que vous devriez obtenir** L’assistant lance `npx bmad-plus update-check --json`. Si `updateAvailable` et `canAutoApply` sont tous deux vrais, il lance `update --latest --auto` ; si une mise à jour existe mais ne peut pas être appliquée automatiquement, il explique la version et la raison, et ne l’applique avec `update --latest --yes` que parce que vous l’avez demandé. Il ne change pas la politique, n’écrase pas les fichiers personnalisés et ne résout pas les conflits de son propre chef. Ensuite il relit les instructions du projet et rapporte les conflits préservés que la commande a listés.

**À la main, avec une question et un reçu**

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

**Voir aussi**

- [update-check](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-update-check/)
- [update-policy](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-update-policy/)
- [doctor](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-doctor/)
- [install](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-install/)
- [Tout le cycle de vie](https://bmad-plus.rochetta.fr/fr/docs/guides/install-lifecycle/)
- [Dépannage](https://bmad-plus.rochetta.fr/fr/docs/faq/troubleshooting/)

[Documentation BMAD+](https://bmad-plus.rochetta.fr/fr/docs/) · [Référence](https://bmad-plus.rochetta.fr/fr/docs/reference/)

[Code sur GitHub](https://github.com/lrochetta/BMAD-PLUS)