Introduction

Storm is a CLI that keeps changelog entries close to your code. It grew from a few principles:

1. Plain text first. Every unreleased change is a Markdown file that lives in your repo, making reviews and rebases simple.
2. Deterministic releases. Given the same .changes directory, Storm will always write the same CHANGELOG.md section.
3. Interactive when helpful, scriptable everywhere. TUIs exist for reviews and diffs, but every action prints machine-readable summaries for CI.

Why Storm?

Storm sits between git log and CHANGELOG.md. It understands conventional commits, keeps notes in version control, and prefers deterministic text files over generated blobs. The CLI is written in Go, so it ships as a single binary that runs anywhere your repository does.

• Local-first workflow: no external services or databases.
• Deterministic releases: storm release is idempotent and can run in CI.
• Composable commands: each subcommand prints useful summaries for scripts.

Quick Preview

# Extract commits into .changes entries
storm generate --since v1.2.0 --interactive

# Review pending notes
storm unreleased review

# Cut a new release and update package.json
storm release --bump minor --toolchain package.json --tag

Need the details? Head to the Quickstart for a guided flow or read the manual for every flag and exit code.

Architecture Overview

.git/
.changes/
CHANGELOG.md

• storm generate and storm unreleased add populate .changes/.
• storm check and your CI ensure nothing merges without an entry.
• storm release merges the queue into CHANGELOG.md, optionally creates a tag, and can update external manifests.

Toolchain-aware versioning

The bump and release commands understand common ecosystem manifests:

Manifest	Alias	Notes
Cargo.toml	cargo, rust	Updates [package] version.
pyproject.toml	pyproject, python, poetry	Supports [project] and [tool.poetry].
package.json	npm, node, package	Edits the top-level version field.
deno.json	deno	Updates the root version.

Pass specific paths or the literal interactive to launch the toolchain picker TUI.

TUIs everywhere

Storm shares a consistent palette (internal/style) across Bubble Tea experiences:

• Commit selector for storm generate --interactive.
• Unreleased review for curating .changes entries.
• Diff viewer for storm diff with split/unified modes.
• Toolchain picker accessible via --toolchain interactive.

Each interface supports familiar Vim-style navigation (↑/↓, g/G, space to select, q to quit) and degrades gracefully when no TTY is available.

Suggested Workflow

1. Developers add .changes entries alongside feature branches.
2. Pull requests run storm check --since <last-release>.
3. Release engineers run storm generate (if needed) then storm release.
4. CI tags the release and publishes artifacts.

Need concrete steps? See the Quickstart or jump to the manual.