Boilerstone CLI

@lonestone/boilerstone-cli creates a project from the boilerplate, sets up your machine, and keeps the project in sync with later releases.

The map shows every command, what it reads and writes, and the order to run them in. Pick a flow to follow it step by step, or click a node to see what it does. The top is the boilerplate repository and the bottom is your project. Only the release passes from one to the other.

For why the upgrade system exists, read Boilerplate upgrades.

Map

OverviewCreate a projectJoin a projectConnect a project without .boilerstone/Run an upgradePublish a release

Dim the boilerplate side

• Command to know
• Less common command
• File or state
• Human step or release
• Boilerplate repository
• Boundary: the release
• Your project
• Then
• Writes or creates
• Reads

Maintainerintentions promoteon the release PRMaintainermigration-intentions/boilerplate onlyMaintainer · CIintentions lintin CIReleaseRelease vX.Y.Zgit tag + npm, same versionStartonboardproject without .boilerstone/Startinit my-appcreates a projectStartbootstraprun by onboardFilepackage.jsonboilerplate and rock scriptsFileboilerplate.jsonthe versioned stateLocal machinepnpm rocksafe to run againFile.env + Dockerlocal, not versionedFile · gitrefs/boilerstone/v*tags of the boilerplateUpgradeupgrade statusread onlyUpgradeversions listread onlyUpgradeupgrade pathread onlyUpgradeupgradecreates a branchGit branchupgrade/vA-to-vBcreated by upgradeFolder.boilerstone/upgrade/ignored by git, disposableHuman stepApply the intentionsagent or youUpgradeupgrade recordwrites to the stateUpgradeupgrade finishlast commitHuman stepOpen the PRa human mergesFile · finalboilerplate.jsonsame file, updatedFile · finalpackage.jsonsame file, rock pinned

Cheat sheet

Collapse

The commands

Click a node on the map to see what it does. Pick a flow at the top to follow it step by step.

Outside a project

• pnpm dlx @lonestone/boilerstone-cli init my-appCopy
  Create a project.
• pnpm dlx @lonestone/boilerstone-cli@X.Y.Z init my-appCopy
  Create a project on a given release.
• pnpm dlx @lonestone/boilerstone-cli onboardCopy
  Connect a project that has no .boilerstone/, at its root.

Inside a project

• pnpm rockCopy
  Set up your machine.
• pnpm boilerplate upgrade statusCopy
  See where the project stands.
• pnpm boilerplate upgradeCopy
  Prepare an upgrade to the latest release.
• pnpm boilerplate upgrade record --id <id> --appliedCopy
  Record an applied intention.
• pnpm boilerplate upgrade finish --to X.Y.ZCopy
  Close the upgrade.

Less often

• pnpm boilerplate upgrade path --to X.Y.ZCopy
  See the intentions before you prepare.
• pnpm boilerplate versions listCopy
  List the available releases.
• pnpm dlx @lonestone/boilerstone-cli bootstrapCopy
  Wire a .boilerstone/ that is already there.
• pnpm boilerplate upgrade initCopy
  Create boilerplate.json by hand.

Boilerplate maintainer

• pnpm boilerplate intentions lintCopy
  Check the intentions.
• pnpm boilerplate intentions promote --to X.Y.ZCopy
  File the intentions of a release.
• pnpm boilerplate intentions syncCopy
  Regenerate the READMEs of the releases.

Step by step

Create a project

pnpm dlx @lonestone/boilerstone-cli init my-app

1. Run it in the folder that will hold the project. The folder name becomes the scope @my-app/*.
2. The CLI clones the release that has its own version, into a temporary folder.
3. It writes the boilerplate and rock scripts as pnpm dlx. There is no dependency on the CLI.
4. It creates boilerplate.json with the starting version.
5. It installs the dependencies, formats the code, then runs pnpm rock.
6. rock creates the .env files, asks for the ports, and offers Docker and the migrations. Then make your first commit.

Join a project

pnpm install && pnpm rock

1. Clone the repository of the project, then run pnpm install and pnpm rock.
2. rock creates the missing .env files and starts Docker if you want. You can run it again at any time.

Connect a project without .boilerstone/

pnpm dlx @lonestone/boilerstone-cli onboard

Caution

Does the project already have a .boilerstone/ (created in v1.0.0 or v1.1.0)? Do not use onboard: run an upgrade. The adopt-published-cli intention moves it to the published CLI. Run an upgrade

1. For a project that has no .boilerstone/ yet. Run it at the root, with a clean worktree.
2. It fetches .boilerstone/ and the boilerstone-upgrade skills from the release.
3. It runs bootstrap.
4. bootstrap adds the boilerplate script. It touches neither rock nor the dependencies.
5. bootstrap creates boilerplate.json and asks for the starting version. Answer 0.0.0 if you are not sure. onboard then offers a commit.

Run an upgrade

pnpm boilerplate upgrade

1. pnpm boilerplate upgrade status: current version, clean worktree, available releases. Nothing changes.
2. pnpm boilerplate upgrade: targets the latest release, fetches the tags, lets you choose the intentions.
3. It creates the branch upgrade/vA-to-vB.
4. It publishes .boilerstone/upgrade/: numbered intentions, references, upgrade-session.md.
5. With the agent (/boilerstone-upgrade) or by hand: approve the apply / skip table, then one intention at a time, with validation and a commit.
6. After each intention: upgrade record --id <id> --applied, or --skipped --reason "…".
7. When everything is handled: upgrade finish --to X.Y.Z.
8. The new version is written to boilerplate.json.
9. rock moves to the new version.
10. Final commit, PR, then a human merges.

Publish a release

pnpm boilerplate intentions promote --to X.Y.Z

1. Every PR of the boilerplate adds an intention in unreleased/, or carries the no-intention label.
2. CI runs intentions lint and the “Intention gate” check.
3. On the release PR: pnpm boilerplate intentions promote --to X.Y.Z.
4. On merge, Release Please creates the tag vX.Y.Z and CI publishes @lonestone/boilerstone-cli@X.Y.Z.

Good to know

Two ways to call the CLI

Outside a project, with pnpm dlx @lonestone/boilerstone-cli <command>. Inside a project, pnpm boilerplate always runs the latest CLI, and pnpm rock runs the CLI of the release of the project. There is nothing to install.

Choose a release

To create a given release, pin the CLI: pnpm dlx @lonestone/boilerstone-cli@X.Y.Z init my-app. The CLI prints its version when it starts, because pnpm dlx may reuse a cached copy of @latest for a while after a release.

With an AI agent

Run /boilerstone-upgrade in Claude Code, or the skill of the same name in Cursor. The agent proposes, you approve. To read the state, it uses --json on upgrade status and upgrade path.

A fork or a private mirror

When you run init or onboard, set BOILERPLATE_REPO=<url>. The address is kept in boilerplate.json for the upgrades.

Target another folder

The upgrade commands accept --project <path>. Otherwise they look for the project from the current folder.

Undo everything

During an upgrade: leave the branch, delete it, and remove .boilerstone/upgrade/. To leave the system: delete .boilerstone/ and the boilerplate script.