CLI Usage
Relevant source files
The following files were used as context for generating this wiki page:
The semver project includes a command-line utility that provides a JavaScript implementation of the Semantic Versioning specification. It allows users to validate, sort, compare, and increment versions directly from the terminal. The tool is primarily used to check if specific versions satisfy defined ranges or to automate versioning tasks in development workflows.
The utility is registered in the project's metadata and is accessible after installation via the semver command. It supports a variety of flags to modify parsing behavior, such as loose mode for non-compliant strings or strict mode for enforcing rigid adherence to the specification.
Sources: README.md:43-46, package.json:28-30
Command Execution and Logic Flow
The CLI operates by taking one or more version strings as positional arguments and applying specified transformations or filters based on provided options. If multiple versions are supplied without specific filtering flags, the utility prints the valid versions sorted by SemVer precedence in ascending order.
The following diagram illustrates the high-level logic flow when the CLI processes input:
The program exits successfully (status 0) if any valid version satisfies all supplied ranges and failure if no satisfying versions are found.
Sources: README.md:73-81, semver.js:1062-1080
CLI Options and Configuration
The semver utility supports several flags that map directly to the internal options used by the library's functions.
Primary Options
| Option | Shorthand | Description |
|---|---|---|
--range <range> | -r | Prints only versions that match the specified range. |
--increment [<level>] | -i | Increments a version by a level (major, minor, patch, etc.). Default is 'patch'. |
--preid <id> | N/A | Identifier for pre-release increments (e.g., 'beta' in 1.2.4-beta.0). |
--loose | -l | Interprets versions and ranges loosely. |
--include-prerelease | -p | Includes prerelease versions in range matching. |
--strict | -s | Rejects versions with leading 'v' or 'V' prefixes. |
--coerce | -c | Attempts to coerce a string into a valid SemVer format. |
Sources: README.md:52-71, internal/constants.js:19-27
Increment Levels
When using the --increment flag, the CLI supports specific release types defined in the system's constants.
major: Increments the major version (e.g., 1.2.3 -> 2.0.0).minor: Increments the minor version (e.g., 1.2.3 -> 1.3.0).patch: Increments the patch version (e.g., 1.2.3 -> 1.2.4).premajor: Bumps to the next major version and creates a prerelease.preminor: Bumps to the next minor version and creates a prerelease.prepatch: Bumps to the next patch version and creates a prerelease.prerelease: Increments the prerelease component or creates a new one if none exists.
Sources: internal/constants.js:19-27, functions/inc.js:10-25
Version Manipulation
Coercion Logic
When the --coerce flag is used, the CLI utilizes the coerce() function to extract a version from non-compliant strings. This is a forgiving process that identifies the first digit and consumes characters until a partial or full version is formed.
// Example of internal coercion logic
const major = match[2]
const minor = match[3] || '0'
const patch = match[4] || '0'
const prerelease = options.includePrerelease && match[5] ? `-${match[5]}` : ''
return parse(`${major}.${minor}.${patch}${prerelease}${build}`, options)
Sources: functions/coerce.js:51-57, README.md:204-213
Range Satisfaction
If a range is provided via --range, the CLI evaluates each version against the range using internal satisfies logic. Range parsing involves desugaring advanced syntax (like Tildes ~ or Carets ^) into primitive comparators.
Sources: semver.js:591-620, README.md:92-110
Conclusion
The semver CLI serves as a robust interface for the underlying versioning engine. It allows developers to perform complex operations like range filtering and version incrementing through a simple command-line interface, ensuring consistent version management across different environments.