lvlup 🎩

A CLI tool to help you manage your package versions easily.

1. Getting Started

Step 1: Install the package

First install the package by running:

npm install lvlup

Step 2: Run the init command

When it's your first time using the CLI, you need to run the init command.

At the root of your project, run:

npx lvlup init

You are now ready to use the CLI tool 🙂

Step 3: Add your first experience

Run the following:

npx lvlup add

and follow the prompts.

---

2. Core Concepts

lvlup

As the name of the package suggests, LvLup is all about leveling up your package. We took the boring concept of package versioning, and added a small form of gamification to it.

Experience

An experience is a contributor's intent to release, stored as data within a file.

With lvlup, you essentially take a package, add some experience to it, and when it's ready - it levels up and bumps to the next level, i.e. the next version number.

Contributors to a repository should be able to declare an intent to release, creating experience file(s), and multiple experiences would then be used to calculate the next level (next version).

lvlup makes sure that an experience is only used once for the purpose of leveling up a package.

---

3. Your new Workflow

Your team just started working on a to-be-released branch called RELEASE-123 (made-up name). A contributor branched out of RELEASE-123, and checked out to some side-branch. When this contributor is done working on a new feature, a bugfix, or a major change oin their side-branch, they should run:

npx lvlup add

and answer the prompted questions. An experience file is then created, holding the new information as data.

The experience file should be committed, and be included in the PR to be merged into branch RELEASE-123.

The lvlup add command can occur many times either by the same contributor (on the same side-branch branch), or by multiple contributors (on different side branches, also to be merged into RELEASE-123).

When the maintainer wants to release the package, after all desired PRs to RELEASE-123 branch had been merged, they should checkout to the HEAD of RELEASE-123, and run:

npx lvlup bump

followed by the command:

npx lvlup publish

The mentioned commands are explained further down below.

---

4. Commands

1. init

lvlup init

This command sets up the .lvlup folder at the root of your project. It generates a README.md and a config.json file. The config file has to be found within the .lvlup dir in order for the tool to work. You should run the init command once, when you are setting up lvlup.

2. add

lvlup add [FLAGS]

By default this command is interactive: it asks for semver bump type (major | minor | patch), then a summary of the changes, then confirmation. You can pass flags to pre-fill answers—any value you omit is still prompted. When --level is given together with --message or --message-file, the command runs fully non-interactively (no prompts, confirmation skipped).

Once confirmed, experience file be written as a Markdown file that contains the summary and YAML front matter which stores the package's name that will be released and the semver bump types for it.

For example, an experience file that minor bumps axios would look like this:

---
"axios": minor
---

A description of the minor changes.

If you want to modify the experience file after it's generated, it's completely fine. You can even write your own experience files yourself if you want, just don't forget to commit them.

Inside your .lvlup/config.json, if you were to set the commit.afterAdd option to true, the add command will create and also commit the experience file.

By default, add requires uncommitted git changes (add.requireGitChanges defaults to true). Set "requireGitChanges": false under add to allow running add on a clean working tree.

• --skip — skips the final "are you sure?" confirmation (other prompts still run unless you pass enough flags for a fully non-interactive run).
• --editor EditorType — use an external editor for the summary when not using --message / --message-file. EditorType: vim | vi | nano | code (VsCode).
• -l, --level — semver bump type. Omit to be prompted.
• -m, --message — summary text (CHANGELOG). Cannot be combined with --message-file. Omit to be prompted (or use --editor).
• -f, --message-file — read the summary from a file. Cannot be combined with --message. Omit to be prompted.

Fully non-interactive (scripts, CI, AI agents): pass --level and exactly one of --message or --message-file.

lvlup add --level minor --message "Add widget API"
lvlup add -l patch -m "Fix null handling"
lvlup add --level major --message-file ./release-notes.md

Partial flags (hybrid): e.g. lvlup add --level minor prompts only for the summary; lvlup add -m "Fix typo" prompts only for semver level.

3. bump

lvlup bump

Levels up your package.
Updates the version of the package according to all experience files found under .lvlup since the last release (WHETHER THEY ARE COMMITTED OR NOT ! So make sure they are committed).

Will also create/append to a CHANGELOG file using the summaries from the experience files.

We recommend making sure changes made from this command are merged back into the main branch before you run publish.

This command will read, and then delete, experience files found on disk, ensuring that they are only used once.

4. publish

lvlup publish

Publishes the package to a dedicated registry. Because this command assumes that last commit is the release commit you should not commit any changes between calling bump and publish. These commands are separate to enable you to check if release commit is accurate.

5. status

lvlup status

The status command provides information about all the experience files that currently exist in a nice tabular view.