DocsCLI

Update and Check Projects

Inspect project health, diagnose generated targets, and apply current-template changes to an existing project.

Three commands maintain a project after it is scaffolded. status answers whether anything needs attention without running anything. check executes the generated target matrix and tells you whether the project actually builds. update compares the project with the current templates and applies the difference under a review token.

Operational contract

Command	Preconditions	Writes	Recovery
`status`	A generated project with `bts.jsonc`.	Nothing. It never executes generated toolchains.	Not applicable.
`check`	`bts.jsonc`, installed dependencies, and every toolchain the generated targets need.	No scaffold source or config. Invoked build tools may write their normal caches and output.	Not applicable.
`update`	`bts.jsonc`; apply also needs a valid versioned `bts.lock.json`.	Only `--apply` and `--record-baseline` write files.	Apply snapshots bounded paths, rolls failed writes back, and returns a one-command recovery ID.

Local edits, conflicts, secrets, lockfiles, and template removals are never silently overwritten or deleted.

Status

status gives a fast, read-only answer to three questions: does Better Fullstack recognize this project, what recovery and provenance guarantees are available, and is a template update worth reviewing?

npx -y create-better-fullstack@latest status .

Use --json for automation. The result includes dependency and environment diagnostics, manifest provenance and recovery eligibility, plus a compact upgrade summary grouped into drift, merges, new files, local edits, conflicts, manual review, and template removals.

status is intentionally non-executable. Run check to verify every generated target, then update to inspect exact file changes and obtain an apply token.

Check

check validates a scaffolded project. doctor is the older name for the same command and stays available.

npm create better-fullstack@latest check -- --skip-checks

It reads and validates bts.jsonc, checks whether dependencies are installed for the detected package manager or ecosystem, reports missing required environment variables from .env.example files, discovers every executable frontend, backend, mobile, and database target from the stack graph, runs each target's generated type/build contract in deterministic order, and reports each target directory, toolchain, planned commands, executed commands, status, and reason. It exits non-zero for failed targets, missing targets or toolchains, and incomplete execution.

Check flags

Flag	Behavior
positional project directory	Project directory to diagnose. Defaults to the current directory.
`--skip-checks`	Skip generated type/build checks and only inspect config, dependencies, and env files.
`--json`	Print structured JSON. Without `--run-checks`, ecosystem checks are skipped and reported as a warning so machine consumers keep a fast, toolchain-independent gate.
`--run-checks`	With `--json`: execute the identical complete target matrix. The command exits non-zero for failed or incomplete verification.

Update

update re-renders the stack recorded in bts.jsonc and compares it with the scaffold baseline in bts.lock.json. Its default behavior is a dry-run plan; it does not write files unless --apply or --record-baseline is explicit.

npm create better-fullstack@latest update

Three-way classification

The engine compares the baseline, current template render, and current disk contents. It classifies files as unchanged, template drift, structured merge, new, locally edited, conflict, removed, or manual review. package.json and .env.example can use structured merges. Lockfiles, secrets, conflicts, and local edits are never silently overwritten; removed template files are not deleted.

Update modes

Flag	Behavior
no mode flag / `--dry-run`	Print the plan without writing.
`--apply`	Transactionally write actionable drift, merges, and new files; requires the token below.
`--review-token <token>`	Exact token from the categorized plan being applied.
`--acknowledge-unproven-manifest-v1`	Required only for migrated/adopted manifests with unverified original lineage.
`--recover <transaction-id>`	Restore every path bound to a successful or interrupted transaction.
`--check`	CI gate: exit non-zero when actionable template drift exists.
`--record-baseline`	Manually adopt current bytes as a baseline; this is not generator-lineage proof.
`--json`	Print categorized paths, hashes, counts, and the review token as structured JSON.
positional project directory	Target directory; defaults to the current directory.

The write/check/baseline modes are mutually exclusive. --dry-run cannot be combined with --apply or --record-baseline.

Recommended workflow

Run update --json and review categorized actionable paths, conflicts, manual entries, hashes, provenance, and recovery eligibility.
Pass that plan's exact token. The emitted command adds the lineage acknowledgement only when the manifest was migrated or manually adopted.

npm create better-fullstack@[same-cli-version] update [project-directory] -- --apply --review-token [64-character-token]

Use the exact version-pinned command emitted by the plan. It is labeled and quoted for PowerShell on Windows and for a POSIX shell on other supported platforms.

Inspect the resulting diff and save the returned recovery command until verification passes.
Resolve remaining files manually, run check, then run the generated project's tests.

Apply rechecks the reviewed config, manifest, intended hashes, observed path/symlink state, and each actionable file preimage. Those checks detect ordinary concurrent edits, but they are not a guarantee against an active local filesystem adversary. If a later check fails, operation-owned writes are restored; a concurrent edit is preserved and reported instead of being overwritten.

update updates generated project templates. The maintainer-only update-deps command updates the generator repository's dependency catalog and is unrelated.