CLI Reference

semrel release

Runs the full release pipeline for the current repository.

semrel release [--dry-run] [--config .semrel.yaml] [--force-bump-patch-version] [--edit]

What happens during release

1. semrel loads .semrel.yaml.
2. Configured plugins are resolved from path:, ~/.semrel/plugins/, or $PATH.
3. semrel builds the release context for the current branch, version, tag, bump, changelog, and dry-run state.
4. Condition plugins validate whether the current environment is allowed to publish.
5. semrel determines the current version, analyzes commits, and calculates the next version.
6. Updater plugins can modify tracked files before the release is finalized.
7. semrel creates the release artifacts unless --dry-run is enabled.
8. Hook plugins run with the same release context after success or failure.

Flags

Flag	Description
--dry-run	Simulate the release without creating tags, releases, or other persistent changes
--config	Read configuration from a non-default file
--force-bump-patch-version	Force at least a patch bump even when the analyzer would not bump the version
--edit	Let you edit generated release content before the release is finalized
--github-output	Write release metadata to $GITHUB_OUTPUT for use in downstream GitHub Actions steps
--gitlab-dotenv <file>	Write release metadata as a dotenv artifact file for GitLab CI downstream jobs
--output-file <file>	Write release metadata to a file (.json for JSON, any other extension for dotenv format)

Examples

# Preview a release without making changes
semrel release --dry-run

# Use a non-default config file
semrel release --config .github/semrel.yaml

# Force a patch bump
semrel release --force-bump-patch-version

# Export outputs for GitHub Actions downstream steps
semrel release --github-output

# Export dotenv artifact for GitLab CI
semrel release --gitlab-dotenv semrel.env

# Export as JSON file
semrel release --output-file release.json

semrel lint

Validates the semrel configuration file.

semrel lint [--config .semrel.yaml]

Examples

# Validate the default config
semrel lint

# Validate a specific config file
semrel lint --config ./config/semrel.yaml

semrel commitlint

Validates commit messages and can emit either text or JSON output.

semrel commitlint [--output text|json]

Examples

# Human-readable output
semrel commitlint

# Machine-readable output
semrel commitlint --output json

semrel plugin list

Lists installed plugins.

semrel plugin list [--no-header]

Examples

# List installed plugins
semrel plugin list

# List installed plugins without the table header
semrel plugin list --no-header

semrel plugin search

Searches the registry for plugins.

semrel plugin search <query>

Example

semrel plugin search github

semrel plugin install

Downloads a plugin into the default plugin directory or a custom directory.

semrel plugin install <name[@version]> [--plugin-dir <dir>]

Examples

# Install the latest GitHub provider plugin
semrel plugin install github

# Install a specific plugin version
semrel plugin install github@v0.1.0

# Install into a custom directory
semrel plugin install github --plugin-dir ./tools/plugins

Installed plugins use the semrel-plugin-<name> naming convention. By default, semrel stores them in ~/.semrel/plugins/.