# update

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

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

Documentación de BMAD+ › [Referencia](https://bmad-plus.rochetta.fr/es/docs/reference/) › update

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

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

**En la terminal de tu proyecto**

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

**Opciones de update**

| Opción | Argumento | Qué hace |
| --- | --- | --- |
| `-d, --directory <path>` | carpeta | 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`. |

<a id="two-paths"></a>
## Dos formas de elegir la versión

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

<a id="what-changes"></a>
## Qué cambia y qué conserva

**Cómo trata update cada tipo de archivo**

| Archivo | Tratamiento |
| --- | --- |
| 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`).

<a id="exit-codes"></a>
## Códigos de salida

**Códigos de salida de update**

| Código | Significado |
| --- | --- |
| 0 | Actualizado, restaurado, nada que actualizar, rechazaste la pregunta, o `--latest` informó del destino y espera `--yes`. |
| 1 | Cualquier error: no instalado, rechazo, conflicto de bloqueo, fallo con reversión, sin terminal y sin `--yes`. |

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

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 conservado** (Simulado)

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

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 dada** (Simulado)

```text
$ npx bmad-plus update --latest
Confirm this exact update with --yes.
Target: v<new>
# No se cambió nada; código de salida 0.
$ npx bmad-plus update --latest --yes
updated
# 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

<a id="recovery"></a>
## Recuperación con --restore

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.

<a id="errors"></a>
## Errores y qué hacer

**Mensajes de update**

| Mensaje | Causa | Qué hacer |
| --- | --- | --- |
| `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. |
| `...; rolled-back. Recovery: bmad-plus update --restore <id> ...` | Falló una escritura; se revirtieron los cambios. | Corrige la causa y reintenta; usa el comando impreso solo si hay archivos incorrectos. |
| `Installation changed since this receipt; recovery refused.` | El manifiesto no es ni el de antes ni el de después del recibo. | Restaura solo desde el recibo más reciente. |
| `Backup is missing or corrupt: <file>` / `File changed since the update: <file>` | Un archivo guardado se borró o se editó. | Recupera ese archivo de tu propio historial y reintenta. |

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

<a id="example-cli-update-ask-assistant"></a>
### Dejar que el asistente compruebe y actualice

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

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

**A mano, con una pregunta y un recibo**

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

**Véase también**

- [update-check](https://bmad-plus.rochetta.fr/es/docs/reference/cli-update-check/)
- [update-policy](https://bmad-plus.rochetta.fr/es/docs/reference/cli-update-policy/)
- [doctor](https://bmad-plus.rochetta.fr/es/docs/reference/cli-doctor/)
- [install](https://bmad-plus.rochetta.fr/es/docs/reference/cli-install/)
- [El ciclo completo](https://bmad-plus.rochetta.fr/es/docs/guides/install-lifecycle/)
- [Solución de problemas](https://bmad-plus.rochetta.fr/es/docs/faq/troubleshooting/)

[Documentación de BMAD+](https://bmad-plus.rochetta.fr/es/docs/) · [Referencia](https://bmad-plus.rochetta.fr/es/docs/reference/)

[Código en GitHub](https://github.com/lrochetta/BMAD-PLUS)