The `bw` CLI
Generated BrightWeb apps include .brightweb/app-manifest.json, the machine-authoritative record of their template, installed modules, tracked scaffold files, managed files, and migration cursors. docs/ai/app-context.json remains the human-and-agent orientation document; it does not replace the app manifest.
Commands
Run commands from the generated app root, or pass --target-dir.
bw add projects
bw adopt --dry-run
bw diff --list
bw scaffold list
bw remove crm
bw upgrade
bw upgrade projects --through-migration 20260811121700_project_client_meta_preview.sql
bw doctor
Add a module
bw add <moduleKey> resolves the module's requirements in dependency order, updates package and managed config, copies its starter overlay, and appends its migrations. Use --dry-run to inspect the plan first. After applying it, install dependencies and run your normal Supabase migration apply command.
Upgrade an app
bw upgrade [moduleKey] performs the managed package/config update and appends only migrations after each module's recorded cursor. It will not overwrite a tracked scaffold file whose recorded hash has drifted, or any file recorded as owned or skipped, including when --refresh-starters is used. create-bw-app update retains its legacy managed-config synchronization and explicit --refresh-starters drift replacement, but respects tracked owned and skipped intent for every output, including config routes. Use bw upgrade to preserve undecided drift as well.
Use bw upgrade <moduleKey> --through-migration <filename> when a rollout needs a deliberate compatibility boundary. The command still updates packages and managed mounts, but advances only that module's migration cursor through the exact named migration. Later migrations remain pending and appear on the next bw upgrade <moduleKey>. The cutoff requires an explicit module key, must name a shipped migration, and cannot move a cursor backwards; it never places an implicit cutoff on other modules.
Migrations marked bw-migration-safety: destructive are held by default during bw upgrade, including an unqualified upgrade across several modules. The plan stops immediately before the first pending marked migration and reports what was deferred. Applying held migrations requires an explicit module-scoped opt-in:
bw upgrade projects --include-destructive-migrations
The opt-in is deliberately separate from --through-migration: including a pending destructive migration within a cutoff is rejected unless --include-destructive-migrations is also present. Review the SQL, back up affected data, and deploy compatible readers and writers before using it. bw add still installs a new module's complete schema because there is no legacy module data to normalize.
An adopted module with a null migration cursor, or any cursor absent from the shipped history, is blocked from upgrade until an operator explicitly reconciles it. A cursor never silently moves backward. This prevents an unknown legacy history from being treated as a new database.
Upgrade safety is evaluated from the current migration cursor: every pending destructive migration requires explicit opt-in, including later destructive steps after an earlier approved cutoff. An explicit cutoff at the existing cursor does not reauthorize already completed steps.
Adopt an existing app
bw adopt creates .brightweb/app-manifest.json for an app that predates the manifest contract. It reads files only: package metadata, module exposure config, scaffold files, and local migration history. It never connects to the database and never creates, renames, edits, or deletes anything under supabase/migrations.
Start with a preview:
bw adopt --dry-run --owned-surface shell
bw adopt --owned-surface shell
bw adopt --own app/crm/page.tsx --skip app/crm/layout.tsx
Adoption records every tracked scaffold file as current, drifted, or missing; it does not overwrite drift or create missing files. Module migration cursors are inferred in this order:
-- bw-module: <key>@...provenance headers written bybw upgrade.- Flattened BrightWeb migration filenames.
- A leading legacy comment such as
-- Brightweb CRM v1 baseline.
The baseline heuristic stamps only the shipped v1 baseline. If the installed package has later migrations, adoption warns that they are unapplied and the next bw upgrade will plan them. If none of the strategies match, the cursor is null, doctor fails, and migration upgrades stay blocked. Resolve that state with a reviewed override such as:
bw adopt --force --cursor crm=20260316092000_crm_v1.sql
Forced re-adoption reconciles the manifest while preserving existing exact-path owned and skipped decisions and recorded owned surfaces, including paths from removed modules. It also retains unresolved drift baselines and exact migration cursors for removed modules; an unknown retained cursor requires a reviewed --cursor override instead of being discarded or inferred from later files. A cursor repair therefore keeps deliberately absent files absent. Use bw scaffold manage to explicitly return an installed module’s path to management.
Use --allow-uncursored only to make the doctor result advisory while investigating; it does not unblock upgrades. Repeated --owned-surface <name> options record app-owned areas such as shell for doctor to report. The more precise, repeatable --own <path> and --skip <path> options acknowledge existing and missing tracked scaffold files during adoption. A path cannot be owned if it is missing or skipped if it exists.
MQ-style legacy walkthrough
An MQ-style portal has its own baseline filenames and heavily customized starter files. Its migration may begin with -- Brightweb CRM v1 baseline. while the package also ships later CRM migrations. Run:
bw adopt --dry-run --owned-surface shell
Expected output includes drift warnings for customized routes, possibly a missing config/shell.overrides.ts warning, and a baseline warning that the CRM cursor was set to 20260316092000_crm_v1.sql while later package migrations remain unapplied. Review the complete manifest preview and warnings before rerunning without --dry-run. Do not rename or copy legacy migration files for adoption.
Compare scaffold drift
bw diff <relpath> prints a unified diff from the installed CLI template to the app's tracked scaffold file. A clean file exits successfully with identical. List all tracked files and their live state with:
bw diff --list
bw diff app/crm/page.tsx
Workspace apps use packages/create-bw-app/template. Published mode uses the bundled template from the installed CLI; if that template is unavailable, the command warns that comparison is unsupported.
Record scaffold intent
Each .brightweb/app-manifest.json scaffoldFiles.<path> entry may include an intent:
managed(the default whenintentis absent): BrightWeb compares the file with its recorded template hash.owned: the app deliberately forked an existing file, so hash drift is informational.skipped: the app deliberately omits the file, so its absence is informational.
Use the scaffold command to inspect or change those decisions:
bw scaffold list
bw scaffold own app/crm/page.tsx
bw scaffold skip app/crm/layout.tsx
bw scaffold manage app/crm/page.tsx app/crm/layout.tsx
own, skip, and manage accept multiple paths. own requires every path to exist; skip requires every path to be missing. manage returns a path to the default managed state and compares an existing file with the installed template again. Manifest updates are atomic.
Remove a module
bw remove <moduleKey> is plan-only unless --yes is supplied. It refuses removal when another installed module requires the target, removes package wiring and only scaffold files that still match their recorded template hash, leaves drifted files with a warning, and regenerates managed config.
bw remove crm
bw remove crm --yes
Owned and skipped path records remain in the manifest after removal, and re-adding the module respects them. Drifted files also keep their recorded baselines, so retained custom files do not become untracked collisions. Clean removed files return when the module is re-added.
Removal never touches the database or migration history. It prints the module's declared owned database objects as a commented manual-removal notice. Dropping those objects is a separate deliberate operator action; applied migrations remain append-only.
Check app health
bw doctor prints PASS, WARN, and FAIL checks for manifest validity, package/module agreement, exposure flags, module requirements, scaffold drift, required environment names, package provenance, and migration provenance. It never prints environment values.
bw doctor --report
bw doctor --strict
--report records the timestamp and result in the app manifest. --strict makes warnings fail, including the current db-objects skip; live database checks are reserved for a later release.
Package provenance requires installed dependencies and a pnpm-lock.yaml. For each BrightWeb package, doctor verifies the exact version from the current compatibility set, the importer resolution, and a registry sha512 integrity record. Workspace, file, link, and patch dependencies are rejected for this published-app check. If dependencies or the lockfile are missing, the check is reported as INFO because exact registry provenance is not available yet.
Migration provenance goes beyond checking that a filename exists. For every migration through the recorded cursor, doctor verifies the module provenance header when present, a compatible package version, the original source filename, and the SHA-256 content against the installed package. It also validates recorded destructive deferrals and reports reviewed legacy-equivalent hashes separately. An uncursored adopted module cannot receive exact provenance verification.
Scaffold health follows the recorded per-file decision:
| Live state | Intent | Doctor result |
|---|---|---|
| Current | Managed or absent | PASS-counted as current |
| Drifted | Owned | INFO-counted as owned |
| Missing | Skipped | INFO-counted as skipped |
| Drifted | Managed or absent | WARN; fails only with --strict |
| Missing | Managed or absent | WARN; fails only with --strict |
| Missing | Owned | FAIL because intent and reality disagree |
| Existing | Skipped | FAIL because intent and reality disagree |
The scaffold summary reports current, owned, skipped, undecided drift/missing, and intent-mismatch counts. Use bw scaffold own or bw scaffold skip only after reviewing the divergence; these commands record a decision rather than changing app files.
Initial scaffolding, add, remove, and update render managed platform files through one module-aware output planner. The planner rejects missing or undeclared policy keys before writing; missing module-dependent routes are repaired from that planner.
Safe workflow
- Commit or stash app-owned work.
- Run the desired command with
--dry-runwhen available. - Review drift and migration output.
- Apply the command, install dependencies, and apply migrations.
- Run
bw doctor, then exercise the affected routes.
Apps without .brightweb/app-manifest.json must run bw adopt before add, upgrade, diff, remove, or doctor workflows can rely on manifest state.
Related
Version requirements use standard semantic-version range matching, including zero-major caret ranges and prerelease rules. See customization boundaries for app-root preflight, create-once files and safe module removal diagnostics.