CLI Reference

Global Flags

These flags apply to every semrel command.

Flag	Default	Description
`--config`	auto-detect	Path to config file (`.semrel.yaml`, `.semrel.yml`, `.semrel.toml`, `.semrel.json`)
`--dry-run`	`false`	Simulate without making any changes
`--env-file`	`.env`	Path to `.env` file to load before running
`--no-color`	`false`	Disable coloured terminal output
`-o, --output`	`text`	Output format: `text` or `json`
`-v, --version`	—	Print version and exit

`semrel release`

Run the full release pipeline.

semrel release [flags]

Pipeline steps

Load and validate .semrel.yaml
Run condition-phase plugins — abort if any fail
Check that the current branch is configured for release
Find the last git tag and collect commits since then
Parse commits against Conventional Commits rules
Calculate the next SemVer version (major / minor / patch)
Generate changelog and release notes
Run pre-tag plugins (e.g. version file updaters)
Commit CHANGELOG.md (unless commit_changelog: false)
Create and push the git tag
Run release-phase plugins (packagers, publishers, providers, hooks)

Flags

Flag	Description
`--dry-run`	Preview the release without making any changes
`--edit`	Open generated release notes in `$EDITOR` before tagging
`--interactive`	Pause for confirmation before tagging (requires a TTY)
`--force-bump-patch-version`	Force a patch release even when no releasable commits are found
`--github-output`	Write release metadata to `$GITHUB_OUTPUT` (GitHub Actions)
`--gitlab-dotenv <file>`	Write release metadata as a dotenv artifact (GitLab CI)
`--output-file <file>`	Write release metadata to a file (`.json` or `.env`)

Note: Plugin failures in --dry-run mode are treated as warnings and do not cause the command to fail. This lets you preview a release version without full credentials configured.

Examples

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

# Edit release notes before tagging
semrel release --edit

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

# Export metadata for GitHub Actions
semrel release --github-output

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

`semrel changelog`

Generate a changelog from unreleased commits without creating a release tag.

semrel changelog [flags]

Flags

Flag	Description
`--write`	Prepend the generated entry to `CHANGELOG.md`
`--since <ref>`	Start from this tag or ref instead of auto-detecting the last tag

Examples

# Preview unreleased changes on stdout
semrel changelog

# Prepend to CHANGELOG.md
semrel changelog --write

# Start from a specific tag
semrel changelog --since v1.0.0

# Machine-readable output
semrel changelog --output json

Exit codes

Code	Meaning
`0`	Unreleased releasable commits found
`2`	Nothing to release (no releasable commits)

`semrel lint`

Validate all commit messages since the last release tag against Conventional Commits.

semrel lint [flags]

Examples

semrel lint
semrel lint --output json

Exit codes

Code	Meaning
`0`	All commits are valid
`1`	One or more commits are invalid

`semrel commitlint`

Validate commit messages against Conventional Commits.

Without arguments, lints all commits since the last release tag — the same scope as semrel lint but with per-commit detail.

semrel commitlint [message...] [flags]

Flags

Flag	Description
`--from <ref>`	Start ref (exclusive) for a commit range
`--to <ref>`	End ref (inclusive) for a commit range (default: `HEAD`)
`--stdin`	Read a single commit message from stdin

Examples

# Lint commits since last release tag (default)
semrel commitlint

# Lint a single message
semrel commitlint "feat(auth): add OAuth2 support"

# Lint a commit range
semrel commitlint --from HEAD~5 --to HEAD

# Lint from stdin (useful as a git commit-msg hook)
echo "fix: typo" | semrel commitlint --stdin

# Machine-readable output
semrel commitlint --output json

`semrel doctor`

Run pre-flight checks before a release.

Checks:

.semrel.yaml exists and is valid
Each configured plugin binary is discoverable
Required environment variables are set (where detectable)
The current branch is a configured release branch
A git repository is present with at least one tag

For GitLab, semrel doctor accepts SEMREL_PLUGIN_TOKEN, GITLAB_TOKEN, or CI_JOB_TOKEN as valid token sources.

semrel doctor [flags]

Flags

Flag	Description
`--online`	Also ping the semrel registry for plugin availability

Examples

semrel doctor
semrel doctor --online
semrel doctor --output json

Exit codes

Code	Meaning
`0`	All checks passed (warnings do not affect exit code)
`1`	One or more checks failed

`semrel config`

Manage the semrel configuration file.

semrel config <subcommand> [flags]

`semrel config init`

Create a new .semrel.yaml interactively or with defaults.

semrel config init [flags]

Flag	Description
`--no-interactive`	Skip prompts and write a minimal default config
`--force`	Overwrite an existing config file

semrel config init
semrel config init --no-interactive
semrel config init --force

`semrel config show`

Print the resolved configuration.

semrel config show
semrel config show --output json

`semrel config validate`

Validate the current configuration file.

semrel config validate

`semrel config set`

Update a single config key in .semrel.yaml.

semrel config set <key> <value>

semrel config set tagPrefix v
semrel config set version_ceiling 2.0.0
semrel config set commit_changelog false
semrel config set tag_exists_strategy skip

`semrel migrate`

Upgrade .semrel.yaml from an older schema version to the current one.

semrel migrate [flags]

Flags

Flag	Description
`--dry-run`	Show pending migrations without writing files
`--no-backup`	Skip writing a timestamped backup before migrating

Examples

semrel migrate
semrel migrate --dry-run
semrel migrate --no-backup

`semrel plugin`

Manage semrel plugins.

semrel plugin <subcommand>

`semrel plugin list`

List all available plugins in the registry.

semrel plugin list [--no-header]

`semrel plugin search`

Search plugins by name, description, or tag.

semrel plugin search <query>

semrel plugin search github
semrel plugin search changelog

`semrel plugin install`

Download and install a plugin binary into .semrel/plugins/.

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

# Install the latest version
semrel plugin install @semrel/github

# Install a specific version
semrel plugin install @semrel/github@1.2.0

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

Use the full @namespace/name reference when the registry entry belongs to a namespace. Bare names such as github only work for plugins that have no namespace in the registry.

When you install into the default project-local directory, semrel also creates or updates .semrel.lock at the repository root.

`semrel plugin update`

Check for newer plugin releases from the registry and optionally install them.

Without arguments, semrel reads .semrel.lock and checks or updates all pinned plugins.

semrel plugin update [name[@version]] [--check]

# Check updates for all plugins pinned in .semrel.lock
semrel plugin update --check

# Install all available updates and refresh .semrel.lock
semrel plugin update

# Update a single plugin
semrel plugin update @semrel/github

`semrel plugin restore`

Install all plugins listed in .semrel.lock into .semrel/plugins/.

semrel plugin restore

The restore command skips binaries that are already present and verifies the checksum for the current platform before installing a missing plugin.

- name: Restore semrel plugins
  run: semrel plugin restore

script:
  - semrel plugin restore

- name: Restore semrel plugins
  run: semrel plugin restore

`semrel update`

Check for a newer semrel release and install it in place.

Fetches the latest release from GitHub Releases and replaces the current executable.

semrel update [flags]

Flags

Flag	Description
`--check`	Only check for a newer version; do not download

Examples

# Check and install the latest release
semrel update

# Check only — no download
semrel update --check

`semrel workspace`

Orchestrate releases across all packages in a monorepo workspace with a single command. Configure the workspace in the root .semrel.yaml — see the Monorepo guide for full details.

semrel workspace <subcommand>

`semrel workspace list`

List all packages configured in the workspace.

semrel workspace list

`semrel workspace release`

Release all workspace packages in dependency order. Packages with no releasable commits since their last tag are skipped automatically.

semrel workspace release [flags]

Flag	Description
`--dry-run`	Preview all package releases without making any changes
`--parallel`	Release independent packages concurrently (subprocess per package)
`--fail-fast`	Stop on the first package failure instead of collecting all errors

Examples

# Preview the entire workspace release
semrel workspace release --dry-run

# Release all packages sequentially
semrel workspace release

# Release independent packages in parallel
semrel workspace release --parallel

Output

[packages/api]     ✓ released
[packages/ui]      – skipped (nothing to release)
[packages/worker]  ✗ failed: …