semverctl

CLI for bumping and setting SemVer values in JSON/YAML files and Git tags

Features

• ✨ Semantic Versioning - Strict SemVer 2.0.0 compliance with prerelease and build metadata support
• 📁 File + Tag Workflows - Explicit bump/set file and bump/set tag commands
• 🏷️ Git Tag Releases - Bump from latest stable vX.Y.Z tag or set explicit tags
• 🎯 Path Navigation - Dot-notation paths for nested version fields (e.g., .app.version)
• 🔢 Numeric Bumping - Bump individual numeric fields for object-style versions
• 🧪 Dry-Run Mode - Preview changes with unified diff output
• 🤖 Automation-Friendly JSON - --json output for machine-readable success/error payloads
• 🔒 Safety Checks - Tag operations require a clean repository state
• 🌐 Cross-Platform - Linux, macOS, and Windows support (CGO-free)
• ⚡ Zero Dependencies - Pure Go implementation with no runtime dependencies
• 📦 Multiple Distribution Channels - Go install, npm, uv/PyPI, and GitHub Releases

Usage

Quickstart

# Install globally
npm i -g @metalagman/semverctl@latest

# Bump patch version in package.json
semverctl bump file package.json

# Bump minor version in Helm Chart.yaml
semverctl bump file Chart.yaml --minor

# Create a new git tag for the next release
semverctl bump tag --push

Node.js (package.json)

# Bump patch in package.json
semverctl bump file package.json

# Bump major version for a breaking change
semverctl bump file package.json --major

# Preview what would change without modifying the file
semverctl bump file package.json --minor --dry-run

Helm (Chart.yaml)

Helm Charts have two version fields: version (the chart version) and appVersion (the version of the application contained in the chart).

# Bump the Chart version (default .version path)
semverctl bump file Chart.yaml --patch

# Bump the appVersion explicitly
semverctl bump file Chart.yaml --minor --path appVersion

# Preview Helm chart changes
semverctl bump file Chart.yaml --major --dry-run

Git Tags

Create and push tags for your releases.

# Create and push the next patch tag (e.g., v1.0.1)
semverctl bump tag --push

# Create the next minor tag (e.g., v1.1.0) without pushing
semverctl bump tag --minor

# Preview tag creation
semverctl bump tag --major --dry-run

CLI Reference

Bump File Version

Bump the semantic version in a specific JSON or YAML file:

# Bump patch in a file
semverctl bump file package.json

# Bump specific version component
semverctl bump file package.json --minor
semverctl bump file package.json --major

# Bump version at a custom path
semverctl bump file config.yaml --path .app.version

# Preview changes without modifying the file
semverctl bump file package.json --dry-run

# Machine-readable output for automation
semverctl bump file package.json --dry-run --json

Set File Version

Set an explicit version value in a specific file:

# Set version to 1.2.3 in a file
semverctl set file 1.2.3 package.json

# Set version at a custom path
semverctl set file 2.0.0 config.yaml --path .app.version

# Preview changes
semverctl set file 1.0.0 package.json --dry-run

# Machine-readable output for automation
semverctl set file 1.2.3 package.json --json

Bump Tag

Bump from the latest stable git tag (vX.Y.Z) and create a new annotated tag:

# Create next patch tag
semverctl bump tag

# Create next minor tag
semverctl bump tag --minor

# Preview tag creation
semverctl bump tag --dry-run

# Create and push tag to origin
semverctl bump tag --push

# Machine-readable output for automation
semverctl bump tag --dry-run --json

Set Tag

Create an explicit annotated git tag:

# Accepts 1.2.3 or v1.2.3
semverctl set tag 1.2.3
semverctl set tag v2.0.0

# Preview tag creation
semverctl set tag 2.1.0 --dry-run

# Create and push tag to origin
semverctl set tag 2.1.0 --push

# Machine-readable output for automation
semverctl set tag 2.1.0 --json

Numeric Bump

For object-style version fields (e.g., { "Major": 1, "Minor": 2, "Patch": 3 }), you can bump numeric scalar values:

semverctl bump file config.json --numeric --path .version.Patch

This increments the numeric value at the specified path by 1.

Installation

Go

go install github.com/metalagman/semverctl/cmd/semverctl@latest

npm (Node.js)

npx @metalagman/semverctl version

# Or install globally
npm install -g @metalagman/semverctl
semverctl version

uv/Pip (Python)

uvx semverctl version

# Or install
uv pip install semverctl
semverctl version

Pre-built Binaries

Download pre-built binaries from GitHub Releases:

# Linux/macOS
curl -L https://github.com/metalagman/semverctl/releases/latest/download/semverctl-linux-amd64 -o semverctl
chmod +x semverctl
sudo mv semverctl /usr/local/bin/

# Verify checksum (recommended)
curl -L https://github.com/metalagman/semverctl/releases/latest/download/checksums.txt -o checksums.txt
sha256sum -c checksums.txt

Path Syntax

Paths use dot notation to navigate nested structures:

• .version - Top-level version field
• .app.version - Nested version field
• .package.version - Deeply nested field

The leading dot is optional: version and .version are equivalent.

File Formats

Supported formats:

• JSON (.json)
• YAML (.yaml, .yml)

Strict SemVer

semverctl follows the Semantic Versioning 2.0.0 specification:

• Versions must be in format MAJOR.MINOR.PATCH
• Prerelease and build metadata are supported: 1.0.0-alpha+build.123
• Leading zeros are not allowed in numeric components
• When bumping, prerelease and build metadata are cleared

Dry-Run Mode

Use --dry-run to preview file changes or tag actions without mutation:

semverctl bump file package.json --dry-run
semverctl bump tag --dry-run

For file commands, this outputs a unified diff showing what would change.

JSON Output

Use --json for machine-readable automation output:

semverctl bump tag --dry-run --json
semverctl set tag 1.2.3 --json
semverctl bump file package.json --dry-run --json

When --json is enabled, both success and failure responses are printed as JSON to stdout. Failures still return a non-zero exit code.

Exit Codes

• 0 - Success
• 1 - Error (invalid arguments, file not found, parse error, etc.)

License

MIT License - see LICENSE file for details.