CLI-Referenz

Diese Referenz ist nach Befehlen gegliedert:

• der top-level Publish-Befehl: pubm [version]
• Verwaltungsbefehle wie init, secrets und sync
• Changeset-Workflows unter pubm changesets ...
• der Befehl pubm snapshot für Vorschau- und Test-Releases

Für den Alltag ist der wichtigste Befehl:

pubm

Wenn du pubm ohne Versionsargument aufrufst, landest du im interaktiven Ablauf. Dort kannst du im Terminal die nächste Version waehlen, bevor die Release-Pipeline weiterlaeuft.

Befehlsuebersicht

Befehl	Zweck
pubm [version]	Fuehrt die Publish-Pipeline mit einem Release-Typ oder einer expliziten SemVer aus.
pubm snapshot [tag]	Veröffentlicht Snapshot-Versionen für Vorschau und Tests.
pubm init	Interaktiver Setup-Wizard für Paketerkennung, Konfiguration, Changesets, CI-Workflows und Coding-Agent-Skills.
pubm setup-skills	Coding-Agent-Skills herunterladen und installieren (Claude Code, Codex, Gemini).
pubm secrets sync	Schiebt lokal gespeicherte Tokens über gh in GitHub Secrets.
pubm sync --discover	Durchsucht das Repository nach Versionsverweisen außerhalb von Manifest-Dateien.
pubm update	Aktualisiert die CLI selbst auf die neueste veröffentlichte Version.
pubm changesets add	Erstellt ein neues Changeset.
pubm changesets status	Zeigt ausstehende Changesets und ihre Versionssprung-Auswirkung.
pubm changesets version	Verbraucht Changesets und schreibt neue Versionen.
pubm changesets changelog	Rendert Changelog-Text aus ausstehenden Changesets.
pubm changesets migrate	Migriert von .changeset/ nach .pubm/.

Top-level Publish-Befehl

Syntax

pubm [version] [flags]

[version] kann sein:

• ein SemVer-Versionssprungtyp: patch, minor, major
• ein Pre-Release-Versionssprungtyp: prepatch, preminor, premajor, prerelease
• eine explizite Version wie 1.8.0

Wenn du die Version weglässt:

• interaktive Terminals koennen nach der nächsten Version fragen
• CI-Laeufe verlangen, dass die Version nicht interaktiv aufgeloest wird

Interaktive Nutzung

pubm

Typischer Ablauf:

1. pubm ausführen
2. patch, minor oder major waehlen
3. pubm durch Checks, Build, Tagging und Publish weiterlaufen lassen

Haeufige Beispiele

pubm
pubm --dry-run
pubm 1.8.0
pubm --registry npm,jsr
pubm --tag beta

Publish-Flags

Flag	Standard	Beschreibung
-d, --dry-run	false	Zeigt den Task-Graphen an, ohne den Git-Zustand zu ändern oder zu veröffentlichen.
--mode <mode>	local	Ausführungsmodus: local (interaktiv) oder ci (nicht interaktiv, tag-basiert).
--phase <phase>	-	Pipeline-Phase: prepare (validieren und Dry-Run) oder publish (vom neuesten Tag veröffentlichen).
--release-draft	false	Erstellt einen Draft-GitHub-Release statt eines veröffentlichten Releases.
-b, --branch <name>	main	Verlangt, dass der aktuelle Branch vor dem Release uebereinstimmt.
-a, --any-branch	false	Deaktiviert den Branch-Schutz für den aktuellen Lauf.
-t, --tag <name>	latest	Verwendet einen bestimmten Dist-Tag wie beta oder next.
-c, --contents <path>	none	Wechselt vor dem Release-Flow in ein Unterverzeichnis.
--registry <registries>	npm,jsr	Kommagetrennte Ziel-Registries. Unterstützt npm, jsr, crates oder benutzerdefinierte Registry-URLs.
--test-script <script>	test	Script-Name für den Test-Schritt.
--build-script <script>	build	Script-Name für den Build-Schritt.
--no-save-token	false	Speichert unterstützte Tokens nicht für spätere Laeufe.
--dangerously-allow-unpublish	false	Erlaubt Registry-Unpublish/Yank während des Rollbacks in Nicht-TTY-Umgebungen.
--locale <locale>	en	Sprache der CLI-Ausgabe festlegen. Unterstützt: en, ko, zh-cn, fr, de, es.
--create-pr	false	Erstellt einen Pull Request für den Version-Bump anstatt direkt zu pushen.

Flags zur Pipeline-Steuerung

Flag	Beschreibung
--no-pre-check	Überspringt Voraussetzungen wie Branch- und Working-Tree-Prüfung.
--no-condition-check	Überspringt Pflichtprüfungen wie Token- und Registry-Validierung.
--no-tests	Überspringt den Test-Schritt.
--no-build	Überspringt den Build-Schritt.
--no-publish	Laeuft bis zum Publish, veröffentlicht Artefakte aber nicht wirklich.
--skip-release	Überspringt die GitHub-Release-Erstellung.

Ausführungsmodi

Interaktiver lokaler Lauf

Der normale Modus für lokale Releases:

pubm

Verhalten:

• startet mit interaktiver Versionsauswahl, wenn kein Versionsargument angegeben ist
• Prompts koennen erscheinen, wenn erforderliche Informationen fehlen
• Tests und Build laufen, sofern sie nicht uebersprungen werden
• Versionierung, Publish, Push und GitHub-Release-Schritte laufen in dieser Reihenfolge

Dry-Run-Modus

pubm --dry-run

Verwende den Dry-Run-Modus, wenn du den Task-Plan ohne Nebenwirkungen ansehen willst.

CI-Vorbereitungsmodus

pubm --mode ci --phase prepare

CI-Vorbereitung:

• sammelt fehlende Tokens interaktiv ein
• kann sie mit GitHub Secrets synchronisieren
• schaltet auf nicht interaktives Verhalten um, um CI nachzubilden
• fuehrt Prüfungen für Voraussetzungen und Bedingungen aus
• fuehrt Publish für konfigurierte Registries als Dry-Run aus

CI-Publish-Modus

pubm --mode ci --phase publish

Der CI-Publish-Modus veröffentlicht vom neuesten Git-Tag und erstellt einen GitHub Release über die API. Verwende ihn, wenn Versionssprung und Tagging vorher schon in der Pipeline passiert sind. Mit --release-draft erstellst du statt eines veröffentlichten Releases einen Draft.

Umgebungsvariablen

Variable	Zweck
NODE_AUTH_TOKEN	npm-Authentifizierung in CI
JSR_TOKEN	jsr-Authentifizierung
CARGO_REGISTRY_TOKEN	Authentifizierung für crates.io
PUBM_LOCALE	Sprache der CLI-Ausgabe (en, ko, zh-cn, fr, de, es)

Prompts werden automatisch deaktiviert, wenn:

• stdin kein TTY ist
• der Prozess auf einer erkannten CI-Plattform laeuft

pubm snapshot

Veröffentlicht Snapshot-Versionen für Vorschau und Tests. Unterstützt Einzelpaket- und Monorepo-Projekte.

pubm snapshot [tag]

Option	Beschreibung
[tag]	Snapshot-Tag (Standard: snapshot)
-f, --filter <name>	Pakete nach Name oder Pfad filtern (wiederholbar)
-d, --dry-run	Simulieren ohne Nebeneffekte
--no-tests	Tests ueberspringen
--no-build	Build ueberspringen
-b, --branch <name>	Ziel-Branch (Standard: main)
-a, --any-branch	Veröffentlichung von beliebigem Branch erlauben

Beispiele

# Snapshot aller Pakete
pubm snapshot

# Snapshot mit eigenem Tag
pubm snapshot beta

# Snapshot bestimmter Pakete
pubm snapshot --filter @pubm/core --filter pubm

pubm init

Interaktiver Setup-Wizard für pubm. Erfordert ein TTY.

pubm init

Der Wizard führt diese Schritte der Reihe nach aus:

1. Paketerkennung: durchsucht das Repository nach Manifest-Dateien (package.json, jsr.json, deno.json, deno.jsonc, Cargo.toml) und Workspace-Konfiguration, bestaetigt dann die erkannten Pakete und Registries.
2. Grundkonfiguration: fragt nach dem Release-Branch und der Versionierungsstrategie (independent oder fixed).
3. Release-Optionen: fragt nach Changelog-Erzeugung und GitHub-Release-Entwuerfen.
4. Workflow-Setup: bietet an, den Changesets-Workflow zu aktivieren (erstellt .pubm/changesets/, .github/workflows/changeset-check.yml und aktualisiert .gitignore) und CI-Release-Workflows zu erzeugen (.github/workflows/release.yml).
5. Coding-Agent-Skills: bietet an, Coding-Agent-Skills für Claude Code, Codex CLI oder Gemini CLI herunterzuladen und zu installieren. Das entspricht pubm setup-skills.

Eine pubm.config.ts-Datei wird nur erstellt, wenn deine Auswahl von den Standardwerten abweicht. Wenn alle Werte den Standardwerten entsprechen, wird keine Config-Datei geschrieben.

Dieser Befehl akzeptiert keine Flags oder Optionen. Alle Konfiguration wird interaktiv abgefragt.

pubm setup-skills

Coding-Agent-Skills für die Verwendung mit pubm herunterladen und installieren.

pubm setup-skills

Unterstützte Agenten und ihre Installationspfade:

Agent	Skill-Verzeichnis
Claude Code	.claude/skills/pubm/
Codex CLI	.agents/skills/pubm/
Gemini CLI	.gemini/skills/pubm/

Skills werden aus dem pubm-GitHub-Repository heruntergeladen (neuester Release-Tag, mit Fallback auf den main-Branch).

Dieser Befehl ist auch als letzter Schritt von pubm init verfügbar.

pubm secrets sync

Schiebt lokal gespeicherte Tokens mit der gh-CLI in GitHub Secrets.

pubm secrets sync
pubm secrets sync --registry npm
pubm secrets sync --registry npm,jsr

Flag	Standard	Beschreibung
--registry <registries>	npm,jsr,crates	Beschraenkt die Secret-Synchronisierung auf bestimmte Registries.

Hinweise:

• erfordert, dass gh installiert und authentifiziert ist
• nutzt lokal gespeicherte Tokens, daher solltest du pubm --mode ci --phase prepare zuerst ausführen, wenn noch nichts gespeichert wurde

pubm sync --discover

Durchsucht das Repository nach Versionsverweisen außerhalb von Manifest-Dateien.

pubm sync --discover

Der Befehl ist dazu gedacht, Version-Sync-Plugins einzurichten. Er ueberspringt häufige generierte Verzeichnisse und Lockfiles und gibt dann Kandidaten-Dateien sowie JSON-Pfade oder passende Zeilen aus, die du in Plugin-Config uebernehmen kannst.

pubm update

Aktualisiert die installierte pubm-CLI auf die neueste veröffentlichte Version.

pubm update

Changeset-Befehle

Alle Befehle für den Changeset-Lebenszyklus liegen unter pubm changesets.

pubm changesets add

Erstellt ein neues Changeset.

pubm changesets add
pubm changesets add --empty
pubm changesets add --packages @acme/core,@acme/react --bump minor --message "Add public metrics API."

Flag	Beschreibung
--empty	Erstellt eine leere Changeset-Datei.
--packages <list>	Kommagetrennte Paketnamen für die nicht interaktive Erstellung.
--bump <type>	Einer von patch, minor, major.
--message <text>	Zusammenfassung für den Changeset-Body und das Changelog.

pubm changesets status

Prüft ausstehende Changesets.

pubm changesets status
pubm changesets status --verbose
pubm changesets status --since origin/main

Flag	Beschreibung
--verbose	Gibt die Zusammenfassung jedes erfassten Changesets aus.
--since <ref>	Prüft ab einem Git-Ref.

pubm changesets version

Verbraucht Changesets, aktualisiert Manifest-Versionen, schreibt Changelogs und committet das Ergebnis.

Für Pakete ohne ausstehende Changeset-Dateien kann pubm changesets version auf Conventional Commits zurückfallen, um den Bump-Typ zu bestimmen. Dieses Verhalten wird durch die Konfigurationsoption versionSources gesteuert. Weitere Details im Konfigurationsleitfaden.

pubm changesets version
pubm changesets version --dry-run

Flag	Beschreibung
--dry-run	Gibt den Plan für Version und Changelog aus, ohne Dateien zu schreiben.

pubm changesets changelog

Erzeugt Changelog-Text aus ausstehenden Changesets.

pubm changesets changelog
pubm changesets changelog --dry-run
pubm changesets changelog --version 1.8.0

Flag	Beschreibung
--dry-run	Zeigt den Changelog-Ausgang an, ohne CHANGELOG.md zu schreiben.
--version <ver>	Verwendet eine bestimmte Abschnittsueberschrift statt Unreleased.

pubm changesets migrate

Verschiebt ausstehende Dateien vom alten .changeset/-Layout nach .pubm/.

pubm changesets migrate

Exitcodes

pubm gibt einen von null verschiedenen Exitcode zurück, wenn:

• eine Voraussetzung oder Pflichtprüfung fehlschlaegt
• die Versionsauflösung nicht abgeschlossen werden kann
• ein Publish auf einem Ziel fehlschlaegt
• ein Subcommand ungueltige Eingaben erhält

Im normalen Publish-Modus fuehren Fehler nach Möglichkeit auch zu einem Rollback.

Beispielhafte Befehlsmuster

Erstes lokales Release in einem neuen Repository

pubm init
pubm changesets add
pubm changesets version
pubm --mode ci --phase prepare
pubm --dry-run
pubm

Lokale CI-Probe

pubm --mode ci --phase prepare

Nur den aktuell getaggten Release in CI veröffentlichen

pubm --mode ci --phase publish

Gespeicherte Tokens nach der Vorbereitung synchronisieren

pubm secrets sync