CLI-Referenz

Globale Flags

Diese Flags gelten für jeden semrel-Befehl.

Flag	Standard	Beschreibung
`--config`	Auto-Erkennung	Pfad zur Konfigurationsdatei (`.semrel.yaml`, `.semrel.yml`, `.semrel.toml`, `.semrel.json`)
`--dry-run`	`false`	Simulation ohne Änderungen
`--env-file`	`.env`	Pfad zur `.env`-Datei, die vor dem Ausführen geladen wird
`--no-color`	`false`	Farbausgabe im Terminal deaktivieren
`-o, --output`	`text`	Ausgabeformat: `text` oder `json`
`-v, --version`	—	Version ausgeben und beenden

`semrel release`

Führe die vollständige Release Pipeline aus.

semrel release [flags]

Pipeline-Schritte

.semrel.yaml laden und validieren
condition-phase Plugins ausführen — bei Fehler abbrechen
Prüfen, ob der aktuelle Branch für Releases konfiguriert ist
Den letzten git-Tag finden und Commits seitdem sammeln
Commits anhand der Regeln von Conventional Commits parsen
Die nächste SemVer-Version berechnen (major / minor / patch)
Changelog und Release Notes erzeugen
pre-tag Plugins ausführen (z. B. Versionsdatei-Updater)
CHANGELOG.md committen (außer bei commit_changelog: false)
Den git-Tag erstellen und pushen
release-phase Plugins ausführen (Packager, Publisher, Provider, Hooks)

Flags

Flag	Beschreibung
`--dry-run`	Release ohne Änderungen vorschauen
`--edit`	Erzeugte Release Notes vor dem Tagging in `$EDITOR` öffnen
`--interactive`	Vor dem Tagging auf Bestätigung warten (benötigt ein TTY)
`--force-bump-patch-version`	Ein Patch-Release erzwingen, auch wenn keine releasbaren Commits gefunden wurden
`--github-output`	Release-Metadaten nach `$GITHUB_OUTPUT` schreiben (GitHub Actions)
`--gitlab-dotenv <file>`	Release-Metadaten als dotenv-Artefakt schreiben (GitLab CI)
`--output-file <file>`	Release-Metadaten in eine Datei schreiben (`.json` oder `.env`)

Hinweis: Plugin-Fehler im Modus --dry-run werden als Warnungen behandelt und lassen den Befehl nicht fehlschlagen. So kannst du eine Release-Version auch ohne vollständig konfigurierte Zugangsdaten vorschauen.

Beispiele

# 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`

Erzeuge einen Changelog aus unreleasten Commits, ohne einen Release-Tag zu erstellen.

semrel changelog [flags]

Flags

Flag	Beschreibung
`--write`	Den erzeugten Eintrag am Anfang von `CHANGELOG.md` einfügen
`--since <ref>`	Statt des letzten Tags bei diesem Tag oder Ref starten

Beispiele

# 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	Bedeutung
`0`	Unreleaste releasbare Commits gefunden
`2`	Nichts zu releasen (keine releasbaren Commits)

`semrel lint`

Validiere alle Commit-Messages seit dem letzten Release-Tag anhand von Conventional Commits.

semrel lint [flags]

Beispiele

semrel lint
semrel lint --output json

Exit-Codes

Code	Bedeutung
`0`	Alle Commits sind gültig
`1`	Ein oder mehrere Commits sind ungültig

`semrel commitlint`

Validiere Commit-Messages anhand von Conventional Commits.

Ohne Argumente lintet der Befehl alle Commits seit dem letzten Release-Tag — derselbe Scope wie semrel lint, aber mit Details pro Commit.

semrel commitlint [message...] [flags]

Flags

Flag	Beschreibung
`--from <ref>`	Start-Ref (exklusiv) für einen Commit-Bereich
`--to <ref>`	End-Ref (inklusiv) für einen Commit-Bereich (Standard: `HEAD`)
`--stdin`	Eine einzelne Commit-Message von stdin lesen

Beispiele

# 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`

Führe Pre-Flight-Checks vor einem Release aus.

Checks:

.semrel.yaml existiert und ist gültig
Jede konfigurierte Plugin-Binärdatei ist auffindbar
Erforderliche Umgebungsvariablen sind gesetzt (soweit erkennbar)
Der aktuelle Branch ist ein konfigurierter Release-Branch
Ein git-Repository mit mindestens einem Tag ist vorhanden

Für GitLab akzeptiert semrel doctor SEMREL_PLUGIN_TOKEN, GITLAB_TOKEN oder CI_JOB_TOKEN als gültige Token-Quellen.

semrel doctor [flags]

Flags

Flag	Beschreibung
`--online`	Zusätzlicher Ping an die semrel Registry, um Plugin-Verfügbarkeit zu prüfen

Beispiele

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

Exit-Codes

Code	Bedeutung
`0`	Alle Checks bestanden (Warnungen beeinflussen den Exit-Code nicht)
`1`	Ein oder mehrere Checks sind fehlgeschlagen

`semrel config`

Verwalte die semrel-Konfigurationsdatei.

semrel config <subcommand> [flags]

`semrel config init`

Erstelle eine neue .semrel.yaml interaktiv oder mit Standardwerten.

semrel config init [flags]

Flag	Beschreibung
`--no-interactive`	Prompts überspringen und eine minimale Standardkonfiguration schreiben
`--force`	Eine vorhandene Konfigurationsdatei überschreiben

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

`semrel config show`

Die aufgelöste Konfiguration ausgeben.

semrel config show
semrel config show --output json

`semrel config validate`

Die aktuelle Konfigurationsdatei validieren.

semrel config validate

`semrel config set`

Einen einzelnen Konfigurationsschlüssel in .semrel.yaml aktualisieren.

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`

.semrel.yaml von einer älteren Schema-Version auf die aktuelle aktualisieren.

semrel migrate [flags]

Flags

Flag	Beschreibung
`--dry-run`	Ausstehende Migrationen anzeigen, ohne Dateien zu schreiben
`--no-backup`	Kein Backup mit Zeitstempel vor der Migration schreiben

Beispiele

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

`semrel plugin`

Verwalte semrel-Plugins.

semrel plugin <subcommand>

`semrel plugin list`

Alle verfügbaren Plugins in der Registry auflisten.

semrel plugin list [--no-header]

`semrel plugin search`

Plugins nach Namen, Beschreibung oder Tag durchsuchen.

semrel plugin search <query>

semrel plugin search github
semrel plugin search changelog

`semrel plugin install`

Lade eine Plugin-Binärdatei herunter und installiere sie nach .semrel/plugins/.

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

# Die neueste Version installieren
semrel plugin install @semrel/provider-github

# Eine bestimmte Version installieren
semrel plugin install @semrel/provider-github@1.2.0

# In ein benutzerdefiniertes Verzeichnis installieren
semrel plugin install @semrel/provider-github --plugin-dir ~/.semrel/plugins

Verwende die vollständige Referenz @namespace/name, wenn der Registry-Eintrag zu einem Namespace gehört. Nackte Namen wie github funktionieren nur für Plugins ohne Namespace in der Registry.

Wenn du in das projektlokale Standardverzeichnis installierst, erzeugt oder aktualisiert semrel außerdem .semrel.lock im Repository-Root.

`semrel plugin update`

Prüfe auf neuere Plugin-Releases in der Registry und installiere sie optional.

Ohne Argumente liest semrel .semrel.lock und prüft oder aktualisiert alle gepinnten Plugins.

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

# Updates für alle in .semrel.lock gepinnten Plugins prüfen
semrel plugin update --check

# Alle verfügbaren Updates installieren und .semrel.lock aktualisieren
semrel plugin update

# Einzelnes Plugin aktualisieren
semrel plugin update @semrel/provider-github

`semrel plugin restore`

Installiere alle in .semrel.lock aufgeführten Plugins nach .semrel/plugins/.

semrel plugin restore

Der Restore-Befehl überspringt bereits vorhandene Binärdateien und verifiziert vor der Installation eines fehlenden Plugins die Prüfsumme für die aktuelle Plattform.

- name: Restore semrel plugins
  run: semrel plugin restore

script:
  - semrel plugin restore

- name: Restore semrel plugins
  run: semrel plugin restore

`semrel update`

Prüfe, ob es ein neueres semrel-Release gibt, und installiere es direkt an Ort und Stelle.

Holt das neueste Release von GitHub Releases und ersetzt die aktuelle Executable.

semrel update [flags]

Flags

Flag	Beschreibung
`--check`	Nur auf eine neuere Version prüfen; nichts herunterladen

Beispiele

# Check and install the latest release
semrel update

# Check only — no download
semrel update --check

`semrel workspace`

Alle Packages eines Monorepo-Workspace mit einem einzigen Befehl releasen. Den Workspace in der Root-.semrel.yaml konfigurieren — vollständige Details im Monorepo-Guide.

semrel workspace <subbefehl>

`semrel workspace list`

Alle im Workspace konfigurierten Packages auflisten.

semrel workspace list

`semrel workspace release`

Alle Workspace-Packages in Abhängigkeitsreihenfolge releasen. Packages ohne neue Commits seit dem letzten Tag werden automatisch übersprungen.

semrel workspace release [flags]

Flag	Beschreibung
`--dry-run`	Alle Package-Releases vorschauen, ohne Änderungen vorzunehmen
`--parallel`	Unabhängige Packages gleichzeitig releasen (Subprocess je Package)
`--fail-fast`	Beim ersten Fehler stoppen, statt alle Fehler zu sammeln

Beispiele

# Gesamten Workspace-Release vorschauen
semrel workspace release --dry-run

# Alle Packages sequentiell releasen
semrel workspace release

# Unabhängige Packages parallel releasen
semrel workspace release --parallel

Ausgabe

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