vnxt (vx) - Automated Version Bumping CLI Tool

Features

🚀

Automatic Semantic Versioning

Detects version bumps from conventional commit messages

📝

Auto Changelog

Generates and maintains CHANGELOG.md automatically

🏷️

Configurable Tag Prefix

Customise git tag format via .vnxtrc.json

🔍

Pre-flight Checks

Verifies working directory before making changes

🔬

Dry Run Mode

Preview changes without committing anything

⚙️

Configurable

Project-level configuration via .vnxtrc.json

🎨

Colored Output

Beautiful terminal colors for better readability

🤫

Quiet Mode

Minimal output perfect for CI/CD pipelines

📦

Automated npm Publishing

Trigger npm releases via GitHub Actions Trusted Publishing

Installation

npm (all platforms)

$ npm install -g vnxt

After installation, you can use either vnxt or the shorthand vx

Scoop (Windows)

$ scoop bucket add vnxt https://github.com/n-orrow/scoop-vnxt

$ scoop install vnxt

Requires Scoop and Node.js (scoop install nodejs)

Chocolatey (Windows)

⏳ Pending moderation — will be available on the Chocolatey community repository shortly.

$ choco install vnxt

Requires Chocolatey and Node.js (choco install nodejs)

Homebrew (macOS/Linux)

$ brew tap n-orrow/vnxt

$ brew install vnxt

Requires Homebrew. Node.js will be installed automatically as a dependency.

Install from Source

$ git clone https://github.com/n-orrow/vnxt.git

$ cd vnxt

$ npm link

Quick Start

# Simple version bump (auto-detects patch from "fix:")

$ vx -m "fix: resolve RFID reader bug"

📝 Auto-detected: patch version bump (fix)

🔼 Bumping version...

🚀 Pushing to remote...

✅ Version bump complete!

# Feature addition (auto-detects minor from "feat:")

$ vx -m "feat: add heatmap visualization"

# Breaking change (auto-detects major from "BREAKING")

$ vx -m "BREAKING: redesign API structure"

Usage

Command Line Options

-m, --message <msg> Commit message (required, or use interactive mode)

-t, --type <type> Version type: patch, minor, major (auto-detected from message)

-sv, --set-version <v> Set a specific version (e.g., 2.0.0-beta.1)

-vv, --vnxt-version Show the installed vnxt version

-gv, --get-version Show the current project's version

-p, --push Push to remote with tags

-dnp, --no-push Prevent auto-push (overrides config)

--publish Push and trigger npm publish via GitHub Actions (implies --push)

-c, --changelog Update CHANGELOG.md

-d, --dry-run Show what would happen without making changes

-a, --all [mode] Stage files before versioning (tracked, all, interactive, patch)

-r, --release Generate release notes file (saved to release-notes/)

-q, --quiet Minimal output (errors only)

-h, --help Show help message

Automatic Version Detection

vnxt automatically detects the version bump type from your commit message:

"major:" → major version bump

"minor:" → minor version bump

"patch:" → patch version bump

"feat:" or "feature:" → minor version bump

"fix:" → patch version bump

"BREAKING" → major version bump

You can override auto-detection with the -t flag.

Custom Versions

Set specific version numbers for pre-releases:

$ vx -sv 2.0.0-beta.1 -m "beta: initial release candidate"

$ vx -sv 1.5.0-rc.2 -m "release candidate 2"

Changelog Generation

Automatically update CHANGELOG.md:

$ vx -m "feat: add user authentication" -c

Creates/updates CHANGELOG.md:

# Changelog

## [1.2.0] - 2024-02-10
- feat: add user authentication

## [1.1.0] - 2024-02-09
- feat: add dashboard

Release Notes

Generate formatted release notes file:

$ vx -m "feat: major feature release" -r

Creates release-notes/v1.2.0.md (respects your tagPrefix config). You'll be prompted to add optional context. --publish also auto-generates release notes.

Configuration

Create a .vnxtrc.json file in your project root:

{
  "autoChangelog": true,
  "defaultType": "patch",
  "requireCleanWorkingDir": false,
  "autoPush": true,
  "defaultStageMode": "tracked",
  "tagPrefix": "v",
  "colors": true
}

Configuration Options

autoChangelog boolean default: true

Automatically update CHANGELOG.md on every bump

defaultType string default: "patch"

Default version bump type if not auto-detected

requireCleanWorkingDir boolean default: false

Require clean git working directory before bumping

autoPush boolean default: true

Automatically push to remote after bumping

defaultStageMode string default: "tracked"

Default staging mode when using -a flag (tracked, all, interactive, patch)

tagPrefix string default: "v"

Prefix for git tags. Use "v" for v1.2.3, "" for 1.2.3, or "release-" for release-1.2.3

colors boolean default: true

Enable colored terminal output (disable for logging systems)

Workflow Examples

Quick Fix

$ vx -m "fix: resolve login bug"

Feature Release

$ vx -m "feat: add dashboard analytics"

Major Release with Documentation

$ vx -m "BREAKING: new API structure" -r

Dry Run (Preview Changes)

$ vx -m "feat: new feature" -d

🔬 DRY RUN MODE - No changes will be made

Would perform the following actions:

1. Bump minor version

2. Commit with message: "feat: new feature"

3. Create git tag with annotation

4. Update CHANGELOG.md

5. Push to remote with tags

Interactive Mode

$ vx

🤔 Interactive mode

Commit message: ▋

Complete Workflow

# Make changes to your code...

# Dry run to preview

$ vx -m "feat: add new API endpoint" -d

# Execute with changelog, release notes, and push

$ vx -m "feat: add new API endpoint" -c -r

Quiet Mode (CI/CD)

$ vx -m "chore: automated update" -q

# Minimal output - only errors shown

Publish to npm

# Batch changes without publishing...

$ vx -m "feat: add feature one"

$ vx -m "fix: fix something"

# Ready to release - triggers npm publish

$ vx -m "feat: final feature" --publish

🚀 Remote: Pushed with tags

📦 npm: Publishing triggered (publish/v1.9.3)

Check Version

$ vx -vv

vnxt v1.9.3

$ vx -gv

my-package v2.4.1

Pre-flight Checks

vnxt performs several checks before making changes:

✅ Verifies no uncommitted changes (unless using -a)
✅ Warns if not on main/master branch
✅ Checks for remote repository (if pushing)

🔍 Running pre-flight checks...

⚠️ Warning: You're on branch 'feature/new-dashboard', not main/master

✅ Pre-flight checks passed

Troubleshooting

Not a Git Repository

If you see this error:

❌ Not a git repository. Run `git init` first.

Initialize git in your project directory:

$ git init

Uncommitted Changes Error

Either commit your changes first, or use the -a flag to stage all changes:

$ vx -m "your message" -a

Permission Denied (Windows PowerShell)

If you get execution policy errors:

PS> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Command Not Found After Installation

Make sure npm's global bin directory is in your PATH:

$ npm config get prefix

# Add the bin subdirectory to your PATH

Requirements

Node.js 12.x or higher
npm 6.x or higher
Git installed and configured

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

# 1. Fork the repository

# 2. Create your feature branch

$ git checkout -b feature/amazing-feature

# 3. Commit your changes

$ git commit -m 'feat: add amazing feature'

# 4. Push to the branch

$ git push origin feature/amazing-feature

# 5. Open a Pull Request