vnxt (vx)

A lightweight CLI tool for automated version bumping with changelog generation and git integration.

Features

• 🚀 Automatic semantic version detection from commit messages
• 📝 Automatic CHANGELOG.md generation
• 🏷️ Git tag annotation with configurable prefix
• 🔍 Pre-flight checks for clean working directory
• 🔬 Dry-run mode to preview changes
• 📋 Release notes generation
• ⚙️ Project-level configuration support
• 💬 Interactive mode when no arguments provided
• 🎨 Colored terminal output for better readability
• 🤫 Quiet mode for CI/CD environments
• 📦 Automated npm publishing via GitHub Actions Trusted Publishing

Installation

npm (all platforms)

npm install -g vnxt

Scoop (Windows)

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

Chocolatey (Windows)

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

choco install vnxt

Homebrew (macOS/Linux)

brew tap n-orrow/vnxt
brew install vnxt

From Source

Bash/macOS/Linux:

git clone https://github.com/n-orrow/vnxt.git
cd vnxt
chmod +x vnxt.js
npm link

PowerShell/Windows:

git clone https://github.com/n-orrow/vnxt.git
cd vnxt
npm link

After installation, you can use either vnxt or the shorter alias vx:

vx --help

Usage

Basic Examples

Bash/PowerShell:

# Simple version bump (auto-detects patch from "fix:")
vnxt -m "fix: resolve RFID reader bug"
# or use the shorter alias:
vx -m "fix: resolve RFID reader bug"

# 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"

# With changelog and push to remote
vx -m "feat: add new dashboard" -c -p

# Interactive mode (prompts for input)
vx

Command Line Options

All options work with both vnxt and vx:

-m, --message <msg>      Commit message (required unless using 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 (prompts if no mode)
                         Modes: tracked, all, interactive (i), patch (p)
-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 (anywhere in message) or breaking: → major version bump

You can override this with the -t flag.

Dry Run

Preview what will happen without making changes:

Bash/PowerShell:

vx -m "feat: new feature" -d

Output:

🔬 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. (Skipping push - use --push to enable)

✓ Dry run complete. Use without -d to apply changes.

Custom Versions

Set a specific version number (useful for pre-releases):

Bash/PowerShell:

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 with version history:

Bash/PowerShell:

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 a formatted release notes file:

Bash/PowerShell:

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

You'll be prompted to add optional context before the file is created. Release notes are saved to release-notes/v1.2.0.md (respects your tagPrefix config):

# Release v1.2.0

Released: 2024-02-10 at 14:32:00 UTC
Author: Your Name

## Changes
feat: major feature release

## Installation
npm install [email protected]

## Full Changelog
See CHANGELOG.md for complete version history.

Note: --publish automatically generates release notes too, so -r is only needed for standalone bumps where you want the file without publishing.

File Staging Options

vnxt offers flexible file staging with the -a flag:

Bash/PowerShell:

# Interactive prompt (asks which mode to use)
vx -m "chore: update" -a

# Specific modes
vx -m "fix: bug" -a tracked      # Stage tracked files only (git add -u)
vx -m "feat: new" -a all         # Stage all changes (git add -A)
vx -m "refactor: code" -a i      # Interactive selection (git add -i)
vx -m "fix: typo" -a p           # Patch mode (git add -p)

Staging Modes:

• tracked - Only staged tracked files that have been modified/deleted (default)
• all - Stages all changes, respects .gitignore for new files
• interactive or i - Opens git's interactive staging mode
• patch or p - Opens patch mode for selective staging

Note: If you run vx without any files staged and without the -a flag, vnxt will prompt you interactively to choose a staging mode.

Quiet Mode

Minimize terminal output for CI/CD environments:

Bash/PowerShell:

vx -m "feat: new feature" -q

In quiet mode:

• ✅ Errors still display
• ❌ Progress messages hidden
• ❌ Summary stats hidden
• ❌ Git diff output hidden

Perfect for automated workflows where you only want to see failures.

Check Version

Display the installed vnxt version:

Bash/PowerShell:

vx -vv
# or
vnxt --vnxt-version

Output:

vnxt v1.9.3

Display the current project's version:

Bash/PowerShell:

vx -gv
# or
vnxt --get-version

Output:

my-package v2.4.1

npm Publish

Trigger an automated npm publish via GitHub Actions using Trusted Publishing (OIDC):

Bash/PowerShell:

vx -m "feat: new feature" --publish

This will:

1. Prompt for optional release notes context
2. Bump the version and commit
3. Auto-generate a release notes file in release-notes/
4. Push with a standard v* tag
5. Push an additional publish/v* tag
6. GitHub Actions detects the publish/v* tag and publishes to npm automatically

This means you can batch up multiple changes without publishing to npm each time:

vx -m "feat: add something"         # bump only
vx -m "fix: fix something"          # bump only
vx -m "feat: final thing" --publish # bump + publish everything

Note: --publish implies --push, so -p is not required.

Custom Tag Prefix

Control the prefix used for git tags via .vnxtrc.json:

{
  "tagPrefix": "v"
}

Options:

• "v" → v1.8.0 (default)
• "" → 1.8.0 (no prefix)
• "release-" → release-1.8.0 (useful in monorepos)

Complete Workflow Example

Bash/PowerShell:

# 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 -p

Configuration

Create a .vnxtrc.json file in your project root to set defaults:

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

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | autoChangelog | boolean | true | Automatically update CHANGELOG.md on every bump | | defaultType | string | "patch" | Default version bump type if not auto-detected | | requireCleanWorkingDir | boolean | false | Require clean git working directory before bumping | | autoPush | boolean | true | Automatically push to remote after bumping | | defaultStageMode | string | "tracked" | Default staging mode when using -a flag | | tagPrefix | string | "v" | Prefix for git tags (e.g., "v1.2.3") | | colors | boolean | true | Enable colored terminal output |

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)

Example output:

🔍 Running pre-flight checks...

⚠️  Warning: You're on branch 'feature/new-dashboard', not main/master
✅ Pre-flight checks passed

Interactive Mode

Run vnxt (or vx) without arguments for guided prompts:

Bash/PowerShell:

vx

Output:

🤔 Interactive mode

Commit message: feat: add new feature
Version type (patch/minor/major) [patch]: minor

📝 Auto-detected: minor version bump (feature)

🔍 Running pre-flight checks...
...

Workflow Examples

Quick Fix

Bash/PowerShell:

vx -m "fix: resolve login bug"

Feature Release

Bash/PowerShell:

vx -m "feat: add dashboard analytics" -c -p

Major Release with Full Documentation

Bash/PowerShell:

vx -m "BREAKING: new API structure" -c -r -p

Local Development (No Push)

Bash/PowerShell:

vx -m "chore: refactor code" -a

CI/CD Pipeline

Bash/PowerShell:

# Quiet mode - only shows errors
vx -m "chore: automated update" -q

Publish to npm

Bash/PowerShell:

# Batch changes then publish when ready
vx -m "feat: add feature one"
vx -m "fix: fix something"
vx -m "feat: final feature" --publish

Check Installed Version

Bash/PowerShell:

vx -vv

Troubleshooting

Not a Git Repository

If you see this error:

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

You're trying to use vnxt in a directory that isn't a git repository. Initialize git first:

Bash/PowerShell:

git init

Permission Denied (Windows PowerShell)

If you get execution policy errors:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Uncommitted Changes Error

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

Bash/PowerShell:

vx -m "your message" -a

Command Not Found After Installation

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

Bash:

npm config get prefix
# Add the bin subdirectory to your PATH

PowerShell:

npm config get prefix
# Add the bin subdirectory to your PATH in System Environment Variables

Requirements

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

Version Management

This project uses vnxt for version bumping with the following configuration:

• Auto-push enabled (autoPush: true)
• Auto-changelog enabled (autoChangelog: true)
• Clean working directory not required (requireCleanWorkingDir: false)

See .vnxtrc.json for full configuration.

Author

Nate Orrow - Software Developer

License

MIT License - see LICENSE file for details

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