Browse the documentation

update-check

Ask npm whether a newer BMAD+ release exists and whether your policy would let it apply, without changing anything: flags, statuses, reasons, the JSON fields, cache and offline behaviour.

On this page

Synopsis
What it reads and writes
Statuses and reasons
Exit codes
Output
Errors and what to do
Examples

update-check tells you where your project stands against the latest published release. It compares three things: the version installed in the project, the version of the package you are running, and the newest release on your update channel. It only reports. Nothing is downloaded, installed or written except a small cache file. Assistants run it once per session because the generated instruction files tell them to.

Synopsis

In your project terminal

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

Options of update-check
Flag	What it does
`-d, --directory <path>`	Project to check (default: current folder).
`--refresh`	Ignore the 24-hour cache and the one-hour retry pause after a failure, and ask npm now.
`--offline`	Make no network request; report the local state only (status `unknown`, reason `offline`, or the stale cached target).
`--json`	Print one line of JSON instead of two lines of text.

What it reads and writes

Reads _bmad/.bmad-plus-install.json (installed version), _bmad/update-policy.json (mode, channel, range) and, for the readiness verdict, the ownership inventory.
Contacts npm only when the policy mode is not off, you are not --offline, and there is no fresh cache. The lookup runs npm view bmad-plus@<channel> version engines --json against the official registry https://registry.npmjs.org/ with a 4 second fetch timeout, no retries and a 6 second cap.
Writes .bmad/update-check.json: the release seen and when (valid 24 hours), or the time of the last failure (it then waits an hour before asking again, unless --refresh).
It is the only BMAD+ command that exists to ask npm (update --latest also queries npm, then downloads the target through npm exec). To stop the lookups entirely, run update-policy --mode off.

Statuses and reasons

Plain output is two lines. The first is Installed: <v>; running: <v>; channel <name>: <target>, with unknown for a missing value. The second is <status>: <reason>, followed by (cached result is stale) when the target comes from an expired cache.

Statuses
Status	Meaning
`update-available`	The channel carries a newer version than the installed one. The reason says whether it may apply (see below).
`current`	Installed version equals the channel version (reason `installed-matches-channel`).
`ahead`	Installed version is newer than the channel (reason `installed-ahead-of-channel`).
`off`	The policy mode is `off` (reason `updates-disabled`). npm was not contacted.
`unknown`	No answer: `offline`, `registry-retry-backoff` (a recent failure), or `registry-unavailable`.
`invalid-runtime`, `invalid-installation`, `invalid-policy`	The running version or clock is unusable; there is no valid manifest; the policy file is invalid. Exit code 1.

When the status is update-available, the reason explains what stands between you and the update. ready-for-authorized-update means the policy authorises it and the files are unchanged: canAutoApply is true. Other reasons: approval-required (policy mode is notify, so a human must approve), outside-allowed-range, prerelease-not-allowed, incompatible-node-version, Complete file ownership inventory is required. (a legacy install), Local changes or an active update require manual review., ownership-readiness-failed.

The JSON line carries: schemaVersion, installedVersion, runningVersion, latestVersion (only on the latest channel), targetVersion, channel, status, checkedAt, source (registry, cache, stale-cache or none), stale, updateAvailable, releaseEligible, versionEligible, canAutoApply, engineCompatible, engines and reason.

Exit codes

Exit codes of update-check
Code	Meaning
0	Any other status, including `unknown` and `off`: not being able to reach npm is not a failure.
1	The status begins with `invalid-`.

Output

The acceptance runs did not exercise this command, so these transcripts are composed from the code’s output templates (versions are placeholders) and marked as simulated.

A newer release the policy does not apply by itselfSimulated

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

Illustrative transcript, not captured from a real run. Source: tools/cli/commands/update-check.js lines 32-37; tools/cli/lib/update-check.js lines 209-231

OfflineSimulated

$ 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"}
# Exit code 0. An assistant treats this as “continue the task” and never claims the version is current.

Illustrative transcript, not captured from a real run. Source: tools/cli/lib/update-check.js lines 161-163

Errors and what to do

Messages of update-check
Message or reason	Cause	What to do
`No BMAD+ installation found in <dir> (missing _bmad/.bmad-plus-install.json).` (on the error stream)	Wrong folder or not installed; the status is `invalid-installation`.	Run from the project or pass `--directory`.
`unknown: registry-unavailable`	npm could not be reached within the time limit.	Retry later, or `--refresh`. Offline machines can ignore it.
`unknown: registry-retry-backoff`	A failure was recorded less than an hour ago.	Use `--refresh` to ask again now.
`invalid-policy: unreadable-or-invalid-update-policy`	`_bmad/update-policy.json` is not valid.	Fix or delete the file, or rewrite it with `update-policy`.
`update-available: incompatible-node-version`	The new release needs a newer Node.js than you run.	Upgrade Node.js, then check again.

Examples

For a script: act only when an automatic update is allowed

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

update-check

Synopsis#

What it reads and writes#

Statuses and reasons#

Exit codes#

Output#

Errors and what to do#

Examples#