# update-check

> Preguntar a npm si existe una versión más reciente de BMAD+ y si tu política permitiría aplicarla, sin cambiar nada: opciones, estados, motivos, campos JSON, caché y modo sin conexión.

Canonical: https://bmad-plus.rochetta.fr/es/docs/reference/cli-update-check/
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-check

`update-check` te dice cómo está tu proyecto frente a la última versión publicada. Compara tres cosas: la versión instalada en el proyecto, la del paquete que ejecutas y la más reciente de tu canal de actualización. Solo informa. No se descarga, instala ni escribe nada salvo un pequeño archivo de caché. Los asistentes la ejecutan una vez por sesión porque los archivos de instrucciones generados se lo piden.

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

**En la terminal de tu proyecto**

```sh
npx bmad-plus update-check [-d <path>] [--refresh] [--offline] [--json]
```

**Opciones de update-check**

| Opción | Qué hace |
| --- | --- |
| `-d, --directory <path>` | Proyecto a comprobar (por defecto, la carpeta actual). |
| `--refresh` | Ignorar la caché de 24 horas y la pausa de una hora tras un fallo, y consultar npm ahora. |
| `--offline` | No hacer ninguna petición de red; informar solo del estado local (estado `unknown`, motivo `offline`, o el destino obsoleto de la caché). |
| `--json` | Imprimir una línea de JSON en lugar de dos líneas de texto. |

<a id="reads-writes"></a>
## Qué lee y qué escribe

- Lee `_bmad/.bmad-plus-install.json` (versión instalada), `_bmad/update-policy.json` (modo, canal, rango) y, para el veredicto de disponibilidad, el inventario de propiedad.
- Solo contacta con npm si el modo de la política no es `off`, no estás en `--offline` y no hay caché fresca. La consulta ejecuta `npm view bmad-plus@<channel> version engines --json` contra el registro oficial `https://registry.npmjs.org/`, con 4 segundos de límite, sin reintentos y un tope de 6 segundos.
- Escribe `.bmad/update-check.json`: la versión vista y cuándo (válida 24 horas), o la hora del último fallo (entonces espera una hora antes de volver a preguntar, salvo `--refresh`).
- Es el único comando de BMAD+ que existe para consultar npm (`update --latest` también consulta npm y luego descarga el destino con `npm exec`). Para desactivar del todo las consultas: `update-policy --mode off`.

<a id="statuses"></a>
## Estados y motivos

La salida de texto son dos líneas. La primera es `Installed: <v>; running: <v>; channel <name>: <target>`, con `unknown` si falta un valor. La segunda es `<status>: <reason>`, seguida de `(cached result is stale)` cuando el destino viene de una caché caducada.

**Estados**

| Estado | Significado |
| --- | --- |
| `update-available` | El canal lleva una versión más nueva que la instalada. El motivo dice si puede aplicarse (ver abajo). |
| `current` | La versión instalada es igual a la del canal (motivo `installed-matches-channel`). |
| `ahead` | La versión instalada es más nueva que el canal (motivo `installed-ahead-of-channel`). |
| `off` | El modo de la política es `off` (motivo `updates-disabled`). No se contactó con npm. |
| `unknown` | Sin respuesta: `offline`, `registry-retry-backoff` (fallo reciente) o `registry-unavailable`. |
| `invalid-runtime`, `invalid-installation`, `invalid-policy` | La versión en ejecución o el reloj son inutilizables; no hay manifiesto válido; el archivo de política no es válido. Código de salida 1. |

Cuando el estado es `update-available`, el motivo explica qué se interpone. `ready-for-authorized-update` significa que la política la autoriza y los archivos no han cambiado: `canAutoApply` es verdadero. Otros motivos: `approval-required` (el modo es `notify`, así que debe aprobar una persona), `outside-allowed-range`, `prerelease-not-allowed`, `incompatible-node-version`, `Complete file ownership inventory is required.` (instalación antigua), `Local changes or an active update require manual review.`, `ownership-readiness-failed`.

La línea JSON lleva: `schemaVersion`, `installedVersion`, `runningVersion`, `latestVersion` (solo en el canal `latest`), `targetVersion`, `channel`, `status`, `checkedAt`, `source` (`registry`, `cache`, `stale-cache` o `none`), `stale`, `updateAvailable`, `releaseEligible`, `versionEligible`, `canAutoApply`, `engineCompatible`, `engines` y `reason`.

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

**Códigos de salida de update-check**

| Código | Significado |
| --- | --- |
| 0 | Cualquier otro estado, incluidos `unknown` y `off`: no poder llegar a npm no es un fallo. |
| 1 | El estado empieza por `invalid-`. |

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

Las recetas de aceptación no ejercitaron este comando, así que estas transcripciones se componen con las plantillas de salida del código (las versiones son marcadores) y se señalan como simuladas.

**Una versión más reciente que la política no aplica sola** (Simulado)

```text
$ npx bmad-plus update-check
Installed: <old>; running: <old>; channel latest: <new>
update-available: approval-required
```

Transcripción ilustrativa, no capturada de una ejecución real. Fuente: tools/cli/commands/update-check.js líneas 32-37; tools/cli/lib/update-check.js líneas 209-231

**Sin conexión** (Simulado)

```text
$ npx bmad-plus update-check --offline --json
{"schemaVersion":1,"installedVersion":"<old>","runningVersion":"<old>","latestVersion":null,"targetVersion":null,"channel":"latest","status":"unknown","checkedAt":null,"source":"none","stale":false,"updateAvailable":null,"releaseEligible":false,"versionEligible":false,"canAutoApply":false,"engineCompatible":null,"engines":{},"reason":"offline"}
# Código de salida 0. Un asistente lo trata como «continuar la tarea» y nunca afirma que la versión esté al día.
```

Transcripción ilustrativa, no capturada de una ejecución real. Fuente: tools/cli/lib/update-check.js líneas 161-163

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

**Mensajes de update-check**

| Mensaje o motivo | Causa | Qué hacer |
| --- | --- | --- |
| `No BMAD+ installation found in <dir> (missing _bmad/.bmad-plus-install.json).` (en el flujo de error) | Carpeta equivocada o no instalado; el estado es `invalid-installation`. | Ejecuta desde el proyecto o pasa `--directory`. |
| `unknown: registry-unavailable` | No se pudo llegar a npm en el tiempo límite. | Reintenta más tarde, o `--refresh`. Una máquina sin conexión puede ignorarlo. |
| `unknown: registry-retry-backoff` | Se anotó un fallo hace menos de una hora. | Usa `--refresh` para preguntar de nuevo ahora. |
| `invalid-policy: unreadable-or-invalid-update-policy` | `_bmad/update-policy.json` no es válido. | Corrige o borra el archivo, o reescríbelo con `update-policy`. |
| `update-available: incompatible-node-version` | La nueva versión necesita un Node.js más reciente que el tuyo. | Actualiza Node.js y vuelve a comprobar. |

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

**Para un script: actuar solo si se permite una actualización automática**

```sh
npx bmad-plus update-check --json --refresh
```

**Véase también**

- [update-policy](https://bmad-plus.rochetta.fr/es/docs/reference/cli-update-policy/)
- [update](https://bmad-plus.rochetta.fr/es/docs/reference/cli-update/)
- [doctor](https://bmad-plus.rochetta.fr/es/docs/reference/cli-doctor/)
- [El ciclo completo](https://bmad-plus.rochetta.fr/es/docs/guides/install-lifecycle/)

[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)