Llevar un proyecto instalado a una versión más reciente de BMAD+ con un plan, copias de seguridad y un recibo restaurable: opciones, qué se conserva, rechazos, recuperación y cada mensaje.
update toma un proyecto que ya tiene BMAD+ y lleva sus archivos a la versión del paquete que ejecutas. Nunca trabaja a ciegas: primero calcula un plan a partir del inventario de propiedad registrado en la instalación, indica cuántos archivos cambian y cuáles deja como están porque los editaste, pide confirmación, hace copia de todo, escribe, verifica y deja un recibo. Si algo falla a medias, deshace los cambios, y una actualización terminada puede revertirse después con --restore.
Proyecto a actualizar (por defecto, la carpeta actual).
-y, --yes
-
Confirmar sin preguntar. Obligatorio si no hay terminal.
-l, --lang <code>
código de idioma
Idioma de los textos de confirmación. Por defecto, el idioma registrado al instalar.
--latest
-
No usar el paquete que ejecutas: buscar en npm la última versión compatible y ejecutar exactamente esa. Sin --yes ni --auto solo informa de lo que ejecutaría.
--expected-version <version>
versión exacta
Rechazar salvo que el paquete en ejecución sea exactamente esta versión. Lo usa el propio actualizador como comprobación de seguridad.
--auto
-
Aplicar solo si la política de actualización del proyecto lo permite, el inventario de propiedad está completo y no hay conflictos. Necesita --expected-version.
--restore <receipt-id>
id de recibo
Devolver los archivos guardados por una actualización anterior. No se combina con --latest, --expected-version ni --auto.
update a secas usa el paquete que ejecutas. npx bmad-plus@0.23.0 update lleva el proyecto a 0.23.0. Si la versión instalada y la que se ejecuta son iguales, imprime «Nothing to update.» y termina.
update --latest consulta npm (update-check hace la misma búsqueda) para obtener la versión más reciente de tu canal de actualización, comprueba que es más nueva, elegible, compatible con tu Node y permitida por tu política, y luego ejecuta npm exec con exactamente esa versión en una carpeta temporal, con update --yes --expected-version <version>. Sin --yes (ni --auto) se detiene tras nombrar el destino: el informe es la petición de aprobación.
Tras --latest se vuelve a leer el manifiesto. Si no muestra la versión de destino, el comando falla y te pide inspeccionar el proyecto.
Agentes, habilidades, datos y archivos de módulo que no tocaste
Sustituidos por la nueva versión tras una copia de seguridad.
Archivos gestionados que editaste (modified-managed-file)
Se dejan como están y se listan como conflicto conservado.
Un archivo en el camino que BMAD+ nunca registró (unowned-file)
Se deja como está y se lista como conflicto.
Archivos que la nueva versión ya no incluye
Se eliminan con copia de seguridad si no cambiaron; se conservan y se listan (modified-orphaned-file) si los editaste. Las carpetas vacías se limpian.
AGENTS.md y archivos de herramienta con la marca BMAD+ y sin cambios
Se regeneran.
Archivos de instrucciones que escribiste o editaste tras instalar (local-instructions, repository-adopted)
Se dejan como están y se listan como conflicto.
_bmad/config.yaml, memoria, _bmad-output/
No se tocan.
Instalaciones antiguas sin inventario de propiedad completo
Los archivos originales de los packs se copian antes de sustituirlos, con un aviso; los archivos de instrucciones antiguos se guardan como <file>.bak. --auto rechaza.
Una copia de cada archivo que cambia la actualización se guarda en .bmad/updates/<receipt-id>/backups/, junto a receipt.json. El recibo anota el estado de la actualización: prepared, committed, rolled-back, recovery-required o restored. Solo puede ejecutarse una instalación o actualización a la vez (.bmad/update.lock).
Las recetas de la 0.23.0 no registraron ninguna actualización, así que las dos transcripciones de abajo se componen con las plantillas de mensajes del código (versiones y cifras son marcadores) y se señalan como simuladas.
Una actualización simple con un conflicto conservadoSimulado
$ 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
Transcripción ilustrativa, no capturada de una ejecución real. Fuente: tools/cli/commands/update.js líneas 120-190
Última versión, aprobación pedida y luego dadaSimulado
$ npx bmad-plus update --latestConfirm this exact update with --yes.Target: v<new># No se cambió nada; código de salida 0.$ npx bmad-plus update --latest --yesupdated# El actualizador que lanza este comando imprime aquí sus propias líneas (el plan, el recibo y la línea «applied», como en la transcripción anterior); se omiten.Target: v<new>Reload your agent instructions or start a new session.
Transcripción ilustrativa, no capturada de una ejecución real. Fuente: tools/cli/lib/update-dispatch.js líneas 110-180 y tools/cli/commands/update.js líneas 62-74
Si una actualización falla después de empezar a escribir, se deshace sola y termina con una línea como ; rolled-back. Recovery: bmad-plus update --restore <id> --directory "<dir>" --yes. El id del recibo es también el nombre de la carpeta bajo .bmad/updates/. --restore comprueba que cada archivo guardado siga coincidiendo con su huella registrada, que el manifiesto actual sea el de antes o el de después de esa actualización y que ninguna actualización viva tenga el bloqueo; luego devuelve los archivos antiguos y marca el recibo como restored. No se restaura nada si un archivo cambió desde la actualización: el comando se niega y lo nombra.
No BMAD+ installation found in <dir> (missing _bmad/.bmad-plus-install.json).
Estás en la carpeta equivocada, o BMAD+ no está instalado.
Ejecuta desde la carpeta del proyecto, pasa --directory, o instala primero.
--restore cannot be combined with --latest or --expected-version.
Opciones incompatibles.
Ejecuta la restauración sola.
Automatic update requires --expected-version.
--auto sin versión de destino.
Añade --expected-version <v>, o deja que --latest --auto lo haga.
Executing package version X does not match expected version Y.
El paquete en ejecución no es el que nombraste.
Ejecuta npx bmad-plus@Y update ....
Downgrade refused: A -> B
El paquete en ejecución es más antiguo que la versión instalada.
Ejecuta un paquete más nuevo.
Automatic update refused: <reason>
La política no lo permite (approval-required, updates-disabled, outside-allowed-range, prerelease-not-allowed), o el proyecto es antiguo o tiene conflictos.
Revísala con update-policy, o aprueba a mano con update --latest --yes.
Update refused: <reason>.
Falló una comprobación de seguridad de --latest: updates-disabled, automatic-updates-not-authorized (--auto mientras el modo de la política no es auto), fresh-metadata-required, policy-channel-changed, downgrade-not-allowed, ownership-preflight-failed, incompatible-or-invalid-node-engine, etc.
Lee el motivo, corrige su causa y reintenta. fresh-metadata-required suele significar que npm no era alcanzable.
Updater finished without the expected manifest version X. Inspect the project before retrying.
El actualizador anidado terminó pero el manifiesto no muestra el destino.
Ejecuta doctor; no reintentes a ciegas.
Another update is in progress: <path>.
El bloqueo del proyecto está tomado.
Espera; si se interrumpió, doctor indica cuándo queda obsoleto y qué archivo borrar.
File changed after preflight: <file>
Un archivo cambió entre el plan y la escritura.
Reintenta; la actualización no había empezado a escribir.
Cada archivo de instrucciones generado le pide al asistente comprobar una vez por sesión y seguir la política del proyecto. Puedes pedírselo de forma explícita.
En tu asistente de IA
¿Hay una versión más reciente de BMAD+ para este proyecto? Si nuestra política permite la actualización, aplícala y luego dime qué se conservó.
Lo que deberías obtener El asistente ejecuta npx bmad-plus update-check --json. Si updateAvailable y canAutoApply son ambos verdaderos, ejecuta update --latest --auto; si existe una actualización pero no puede aplicarse automáticamente, explica la versión y el motivo, y solo la aplica con update --latest --yes porque tú lo pediste. No cambia la política, no sobrescribe archivos personalizados ni resuelve conflictos por su cuenta. Después vuelve a leer las instrucciones del proyecto e informa de los conflictos conservados que listó el comando.