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.
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.
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.
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.
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).
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é
$ 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
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éeSimulé
$ npx bmad-plus update --latestConfirm this exact update with --yes.Target: v<new># Rien n’a changé ; code de sortie 0.$ npx bmad-plus update --latest --yesupdated# 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
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.
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.
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
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.