semver-cli

A comprehensive semantic versioning CLI tool. Parse, compare, bump, sort, validate, and manipulate version strings directly from the command line. Fully compliant with the SemVer 2.0.0 specification.

Features

• Parse version strings into their components (major, minor, patch, prerelease, build)
• Compare two versions with proper SemVer precedence rules
• Bump major, minor, patch, or prerelease components
• Range check with support for ^, ~, wildcards, comparison operators, and compound expressions
• Sort lists of versions (ascending or descending)
• Validate version strings against the SemVer spec
• Diff between two versions to see what changed
• Next version suggestions from current version
• Filter versions by range constraints
• Find latest version from a list (with --stable flag)
• Stdin support for piping and scripting

Installation

No dependencies required. Just download and run:

# Clone the repository
git clone https://github.com/Anuar-boop/semver-cli.git
cd semver-cli

# Make executable (optional)
chmod +x semver_cli.py

# Run directly
python3 semver_cli.py --help

Or add an alias to your shell:

alias semver='python3 /path/to/semver_cli.py'

Usage

Parse a Version

$ python3 semver_cli.py parse 1.2.3-beta.1+build.42
Major:      1
Minor:      2
Patch:      3
Prerelease: beta.1
Build:      build.42
Stable:     False

Compare Two Versions

$ python3 semver_cli.py compare 1.0.0 2.0.0
1.0.0 < 2.0.0

$ python3 semver_cli.py compare 1.0.0-alpha 1.0.0
1.0.0-alpha < 1.0.0

Exit codes: 0 = first is greater, 1 = equal, 2 = first is less.

Bump Versions

$ python3 semver_cli.py bump 1.2.3 major
2.0.0

$ python3 semver_cli.py bump 1.2.3 minor
1.3.0

$ python3 semver_cli.py bump 1.2.3 patch
1.2.4

$ python3 semver_cli.py bump 1.2.3-alpha.1 prerelease --tag alpha
1.2.3-alpha.2

$ python3 semver_cli.py bump 1.2.3 prerelease --tag beta
1.2.4-beta.1

Range Checking

# Comparison operators
$ python3 semver_cli.py range 1.5.0 ">=1.0.0"
1.5.0 satisfies '>=1.0.0'

# Caret ranges (compatible with major)
$ python3 semver_cli.py range 1.9.0 "^1.2.3"
1.9.0 satisfies '^1.2.3'

# Tilde ranges (compatible with minor)
$ python3 semver_cli.py range 1.2.9 "~1.2.3"
1.2.9 satisfies '~1.2.3'

# Wildcard ranges
$ python3 semver_cli.py range 1.5.0 "1.x"
1.5.0 satisfies '1.x'

# Compound ranges
$ python3 semver_cli.py range 1.5.0 ">=1.0.0 <2.0.0"
1.5.0 satisfies '>=1.0.0 <2.0.0'

# OR ranges
$ python3 semver_cli.py range 3.0.0 "^1.0.0 || ^3.0.0"
3.0.0 satisfies '^1.0.0 || ^3.0.0'

Sort Versions

$ python3 semver_cli.py sort 3.0.0 1.0.0 2.0.0-beta 2.0.0
1.0.0
2.0.0-beta
2.0.0
3.0.0

# Descending order
$ python3 semver_cli.py sort -r 3.0.0 1.0.0 2.0.0
3.0.0
2.0.0
1.0.0

# From stdin
echo -e "3.0.0\n1.0.0\n2.0.0" | python3 semver_cli.py sort -

Validate

$ python3 semver_cli.py validate 1.2.3
Valid: 1.2.3

$ python3 semver_cli.py validate "not-a-version"
Invalid: Invalid semantic version: 'not-a-version'

Diff Between Versions

$ python3 semver_cli.py diff 1.2.3 2.0.0
Changed: major
  1.2.3 -> 2.0.0

$ python3 semver_cli.py diff 1.2.3 1.2.4
Changed: patch
  1.2.3 -> 1.2.4

Next Version Suggestions

$ python3 semver_cli.py next 1.2.3
Current:          1.2.3
Next patch:       1.2.4
Next minor:       1.3.0
Next major:       2.0.0
Next alpha:       1.2.4-alpha.1
Next beta:        1.2.4-beta.1
Next rc:          1.2.4-rc.1

Filter Versions by Range

$ python3 semver_cli.py filter -r ">=2.0.0" 1.0.0 2.0.0 2.5.0 3.0.0
2.0.0
2.5.0
3.0.0

Find Latest Version

$ python3 semver_cli.py latest 1.0.0 2.0.0-beta 2.0.0 3.0.0-rc.1
3.0.0-rc.1

$ python3 semver_cli.py latest --stable 1.0.0 2.0.0-beta 2.0.0 3.0.0-rc.1
2.0.0

Scripting Examples

# Get the latest stable version from git tags
git tag | python3 semver_cli.py sort - | python3 semver_cli.py latest --stable -

# Check if current version meets minimum requirement
python3 semver_cli.py range "$(cat VERSION)" ">=2.0.0" && echo "OK" || echo "Too old"

# Auto-bump patch version
NEW=$(python3 semver_cli.py bump "$(cat VERSION)" patch)
echo "$NEW" > VERSION

License

MIT - Copyright (c) 2026 Anuar AX