Quickstart

This walkthrough gets you from zero to a published changelog entry in a few minutes. It mirrors the default workflow baked into the CLI.

1. Install the CLI

go install github.com/stormlightlabs/git-storm/cmd/storm@latest

Verify the binary is available:

storm version

2. Capture unreleased changes

Create a .changes entry manually or generate them from commits.

Option A — Manual entry

storm unreleased add \
  --type added \
  --scope cli \
  --summary "Add bump command"

Option B — From git history

storm generate --since v1.2.0 --interactive

Use the commit selector TUI to pick which commits become entries. Storm writes Markdown files such as .changes/2025-03-01-add-bump-command.md.

3. Review pending entries

storm unreleased review

The Bubble Tea UI lets you edit summaries, delete noise, or mark entries as ready. In non-interactive environments, fall back to storm unreleased list --json.

4. Dry-run a release

storm release --bump patch --dry-run

This prints the new CHANGELOG section without modifying files. When the output looks right, re-run without --dry-run.

5. Publish and tag

storm release --bump patch --toolchain package.json --tag

• --bump patch derives the next version from the previous release.
• --toolchain package.json keeps your npm manifest in sync.
• --tag creates an annotated git tag containing the release notes.

Follow up with standard git commands:

git add CHANGELOG.md package.json .changes
git commit -m "Release v$(storm bump --bump patch)"
git push origin main --tags

6. Enforce entries in CI (optional)

storm check --since v1.2.0

The command exits non-zero when commits are missing .changes files, making it ideal for pre-merge checks.

Next steps

• Skim the Introduction to understand the design.
• Explore every flag in the manual.