---
title: Project Lifecycle
description: Choose the right Better Fullstack command to create, evolve, refresh, generate inside, and diagnose a project.
translationStatus: pending
updated: 2026-08-12
---

Better Fullstack records a generated project's selected stack in `bts.jsonc` and its comparison
baseline in `bts.lock.json`. Those files help later commands classify current-template changes and
local edits. Manifest v2 records CLI, generator, template-set, and schema provenance plus lifecycle
history. Valid v1 manifests migrate deterministically without inventing original provenance.

## Lifecycle at a glance

| Goal                                           | Command                        | Writes by default?                                   |
| ---------------------------------------------- | ------------------------------ | ---------------------------------------------------- |
| Create a project                               | `create` (the default command) | Yes; use `--dry-run` to preview.                     |
| Inspect health and upgrade readiness           | `status`                       | No.                                                  |
| Change selected capabilities                   | `add`                          | Yes; use `--dry-run` to preview.                     |
| Remove one selected non-primary capability     | `remove`                       | No; apply needs the exact plan token.                |
| Apply newer templates to the same stack        | `update`                       | No; apply needs the exact plan token.                |
| Generate an in-project resource                | `gen`                          | Yes; use `--dry-run` to preview.                     |
| Diagnose config, dependencies, env, and checks | `check`                        | Toolchains may write locks, caches, or build output. |

## 1. Create

Preview first when the stack is new or scripted:

<PMTabs
  npm="npm create better-fullstack@latest my-app -- --dry-run"
  pnpm="pnpm create better-fullstack@latest my-app --dry-run"
  bun="bun create better-fullstack@latest my-app --dry-run"
  yarn="yarn create better-fullstack@latest my-app --dry-run"
/>

Remove `--dry-run` to scaffold. Commit the generated `bts.jsonc` and `bts.lock.json`; both are part
of the project's reproducible history.

Choose the workspace layout during creation. `monorepo` is the default. `single-app` is restricted
to thin Next.js and TanStack Start self-backend stacks that do not emit sibling database, auth, API,
service, native, container, or deployment packages; later lifecycle commands preserve the recorded
layout rather than converting an established project in place.

## 2. Evolve the selected stack

Use `add` when the desired configuration changes, for example, adding email, observability, an
capability, or a deploy target. Plan the change before writing:

<PMTabs
  npm="npm create better-fullstack@latest add -- --email resend --dry-run"
  pnpm="pnpm create better-fullstack@latest add --email resend --dry-run"
  bun="bun create better-fullstack@latest add --email resend --dry-run"
  yarn="yarn create better-fullstack@latest add --email resend --dry-run"
/>

Commit or stash local work first. The planner refuses to overwrite edited generated files and
reports any manual-review blockers.

Use `remove` for one exact selected non-primary stack part. It plans by default and requires the
same target plus its review token for transactional apply. Replace primary frontend, backend,
mobile, or database choices through `add` so compatibility and migration checks can run.

## 3. Refresh templates

Use `update` when the stack selection stays the same but newer Better Fullstack templates exist.
The default invocation is already a dry run:

<PMTabs
  npm="npm create better-fullstack@latest update"
  pnpm="pnpm create better-fullstack@latest update"
  bun="bun create better-fullstack@latest update"
  yarn="yarn create better-fullstack@latest update"
/>

Review the categorized plan and its token, then run the exact emitted apply command:

<PMTabs
  npm="npm create better-fullstack@[same-cli-version] update [project-directory] -- --apply --review-token [64-character-token]"
  pnpm="pnpm dlx create-better-fullstack@[same-cli-version] update [project-directory] --apply --review-token [64-character-token]"
  bun="bunx create-better-fullstack@[same-cli-version] update [project-directory] --apply --review-token [64-character-token]"
  yarn="yarn dlx 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. On Windows the CLI labels and quotes it
for PowerShell; on other supported platforms it emits POSIX-shell quoting.

Local edits, secrets, removed files, and conflicts are not selected for automatic writes. Apply
rolls failed writes back and emits a recovery command for successful transactions. Migrated or
manually adopted manifests require the additional lineage acknowledgement shown by their plan.

## 4. Generate inside the project

`gen` is a narrow, experimental in-project generator. Today it can preview and create TypeScript
tRPC/oRPC resource routers:

<PMTabs
  npm="npm create better-fullstack@latest gen resource post -- --dry-run"
  pnpm="pnpm create better-fullstack@latest gen resource post --dry-run"
  bun="bun create better-fullstack@latest gen resource post --dry-run"
  yarn="yarn create better-fullstack@latest gen resource post --dry-run"
/>

## 5. Diagnose and verify

Run `check` after creation, additions, updates, dependency installs, and environment changes:

<PMTabs
  npm="npm create better-fullstack@latest check"
  pnpm="pnpm create better-fullstack@latest check"
  bun="bun create better-fullstack@latest check"
  yarn="yarn create better-fullstack@latest check"
/>

Normal output runs the deterministic target matrix, including supported native ecosystem checks.
JSON mode reports status without running those checks unless you explicitly pass `--run-checks`:

<PMTabs
  npm="npm create better-fullstack@latest check -- --json --run-checks"
  pnpm="pnpm create better-fullstack@latest check --json --run-checks"
  bun="bun create better-fullstack@latest check --json --run-checks"
  yarn="yarn create better-fullstack@latest check --json --run-checks"
/>

With `--run-checks`, JSON changes presentation and captures subprocess output; it does not make
those commands read-only. Missing targets, toolchains, or incomplete execution fail the command.

## Recovery rule

Before any write to an established project, commit or stash your work, run the matching plan/dry
run, and inspect blockers. If a requested architecture change includes a database, ORM, auth, API,
backend, or runtime replacement, plan application-data and schema migrations separately.

Continue with [Add and Remove Capabilities](/docs/cli/add/),
[Update and Check Projects](/docs/cli/update/), or a complete
[stack guide](/guides/).