Lizenzdatei

Jedes CLI-Archiv, das im Kundenportal heruntergeladen wird, kann eine Datei mit dem Namen codecharter.license enthalten. Sie ist ein signiertes JWS-Token und bindet den Download an den Kunden, der ihn ausgelöst hat. Ohne gültige Lizenz weigert sich die CLI zu starten und beendet sich mit Exit-Code 6.

Mit Lizenz oder ohne Lizenz herunterladen

Auf der Downloads-Seite finden Sie pro Asset zwei Buttons:

• Mit Lizenz herunterladen liefert das Archiv mit Ihrer persönlichen codecharter.license bereits eingebettet. Das ist die schnellste Variante und reicht aus, solange dasselbe Konto sowohl den Download als auch die CI-Workflows verantwortet.
• Ohne Lizenz liefert das generische, kunden-agnostische Archiv ohne eingebettete Lizenz. Sinnvoll, wenn Sie in Ihrer CI/CD-Pipeline die Lizenz separat aus einem Secret-Store mounten, einen internen Mirror pflegen oder den Build deterministisch von einer Customer-Identität trennen wollen.

Beide Varianten erfordern ein aktives Abonnement. Der Unterschied liegt ausschließlich darin, ob die Lizenz im Archiv enthalten ist; die Inhalte des CLI selbst sind identisch.

Nicht an eine Maschine gebunden

Die Lizenzdatei ist an kein Gerät gebunden. Es gibt keinen Aktivierungsschritt, keinen Aktivierungszähler und keinen Hardware-Fingerabdruck, die Prüfung ist ein reiner Offline-Signaturcheck. Sie können dieselbe codecharter.license auf so viele Maschinen kopieren, wie die Sitz-Bedingungen Ihres Plans abdecken; genau so rollen Sie CodeCharter im Team aus. Siehe Was als Entwickler-Sitz zählt.

Wo die CLI nach der Lizenz sucht

Die CLI prüft folgende Pfade in dieser Reihenfolge und nimmt die erste Datei, die existiert:

1. Der Pfad, der per --license <pfad> übergeben wurde.
2. Die Umgebungsvariable CODECHARTER_LICENSE (muss ein Dateipfad zu einer Lizenzdatei sein, nicht der Token-Inhalt; der Dateiname selbst ist beliebig).
3. codecharter.license direkt neben dem CLI-Binary.
4. codecharter.license im aktuellen Arbeitsverzeichnis.
5. $XDG_CONFIG_HOME/codecharter/codecharter.license (Linux/macOS).
6. %APPDATA%\CodeCharter\codecharter.license (Windows).
7. $HOME/.config/codecharter/codecharter.license (Fallback für Unix-Systeme ohne XDG_CONFIG_HOME).

Die einfachste Variante: die codecharter.license aus dem heruntergeladenen Archiv neben das CLI-Binary kopieren. Damit funktionieren alle Aufrufe ohne weitere Konfiguration.

Automatische Erneuerung in der CI (API-Key)

In der CI laden Sie normalerweise gar keine Lizenz herunter. Stattdessen hinterlegen Sie Ihren Portal-API-Key als CI-Secret (CODECHARTER_API_KEY). Beim Start stellt die CLI daraus eine kurzlebige Lizenz aus (standardmäßig 24h) und cacht sie im benutzereigenen Konfigverzeichnis (Pfad 5/6/7 oben), wobei sie kurz vor Ablauf automatisch erneuert wird. Die Laufzeit ist immer auf das Ende des Abonnements begrenzt, kurz vor dem Abo-Ende kann die ausgestellte Lizenz also weniger als 24h gültig sein. Es gibt keinen Daemon und nichts zu planen: ein frischer Runner holt sich eine Lizenz, ein langlebiger Runner erneuert nur, wenn die gecachte Lizenz unter eine Stunde Restlaufzeit fällt.

So bleibt der API-Key das einzige langlebige Geheimnis. Eine geleakte gecachte Lizenz läuft innerhalb von 24h von selbst ab, und ein Widerruf des Keys im Portal deaktiviert jede daraus abgeleitete Lizenz im selben Fenster, ganz ohne Schlüsselrotation.

Die Erneuerung authentifiziert sich ausschließlich über den API-Key. Die vorhandene Lizenzdatei wird nie an das Portal zurückgeschickt, eine geleakte codecharter.license kann also nicht für eine neue Lizenz verwendet werden.

Ist das Portal kurz nicht erreichbar, während eine noch gültige Lizenz gecacht ist, nutzt die CLI diese weiter bis sie wirklich abläuft (Fail-open) und gibt eine Warnung aus, damit ein kurzer Netzausfall den Build nicht abbricht.

Zwei Overrides werden immer respektiert und von der Erneuerung nie angefasst: ein per --license übergebener Pfad und die Umgebungsvariable CODECHARTER_LICENSE. Damit können Sie eine bestimmte Datei festnageln, die CLI schreibt nur in den verwalteten Cache-Ort.

Die Erneuerung spricht standardmäßig https://codecharter.tools an. Wer einen internen Mirror des Portals betreibt, setzt die Umgebungsvariable CODECHARTER_PORTAL_URL auf dessen Basis-URL, dann nutzt die Erneuerung diesen.

Offline- oder Dauer-Runner

Ein Runner ohne Zugriff auf codecharter.tools kann nicht erneuern. Geben Sie ihm stattdessen eine vollständige codecharter.license aus dem Portal: Auf der Downloads-Seite gibt es den Button codecharter.license herunterladen, der nur das Token als Datei liefert. Legen Sie die Datei auf einen der Suchpfade oder lassen Sie CODECHARTER_LICENSE darauf zeigen. Die CLI entscheidet rein anhand der Restlaufzeit, nicht anhand der Herkunft der Lizenz: Solange die Datei mehr als eine Stunde Restlaufzeit hat, wird der API-Key-Pfad nie betreten.

Beachten Sie dabei: Eine vollständige Lizenz ist nur bis zum Ende Ihres aktuellen Abrechnungszeitraums gültig. Bei einem Monatsplan läuft sie also nach spätestens einem Monat ab und muss nach jeder Verlängerung neu heruntergeladen werden. Für Runner, die länger als einen Abrechnungszyklus leben und Netzzugriff haben, ist die oben beschriebene automatische Erneuerung per CODECHARTER_API_KEY die bessere Wahl; die separate Lizenzdatei bleibt für wirklich offline laufende Maschinen reserviert.

Was geprüft wird

Beim Start jedes gateten Subbefehls (analyze, validate, init, lsp, docs, test, restore, update, verify, push, mcp install sowie des mcp-Servers selbst) führt die CLI folgende Checks durch:

• Die Datei kann gelesen werden.
• Der Inhalt ist ein gültiges JWS-Token mit alg: RS256.
• Die Signatur passt zu einem der im Binary eingebetteten öffentlichen Schlüssel. Während einer Schlüsselrotation kennt das Binary mehrere Schlüssel parallel.
• Das exp-Claim (Ablaufdatum) liegt in der Zukunft. Der Check toleriert bis zu fünf Minuten Uhrenabweichung.
• Optionale min_ver/max_ver-Claims schließen die laufende CLI-Version nicht aus.

Schlägt einer dieser Checks fehl, beendet sich die CLI mit Exit-Code 6 und schreibt eine kurze Diagnose auf stderr.

Häufige Fehlermeldungen

No codecharter.license file found

Keine der Suchpfade enthielt eine Lizenzdatei. Lade das aktuelle Archiv aus dem Portal neu herunter und kopiere codecharter.license neben das CLI-Binary, oder setze CODECHARTER_LICENSE auf den Pfad zur Datei.

Could not read '<pfad>'

Eine Lizenzdatei wurde gefunden, ließ sich aber nicht öffnen, typischerweise wegen fehlender Dateiberechtigungen. Stelle sicher, dass der Benutzer, der die CLI ausführt, Lesezugriff auf die Datei hat.

License at '<pfad>' is not a valid JWS

Die Datei wurde gefunden, ist aber keine gültige JWS-Struktur. Mögliche Ursachen sind eine versehentlich überschriebene Datei, ein Zeilenende-Umbau durch ein Versionierungssystem oder eine Datei aus einer sehr alten Portal-Version. Lade die Lizenz neu aus dem Portal.

License at '<pfad>' is not signed by a key this CLI trusts

Das Token ist syntaktisch sauber, aber von einem Schlüssel signiert, den diese CLI nicht kennt. Tritt typischerweise bei einem Mismatch zwischen einer Lizenz aus einer alten Portal-Generation und einer aktuelleren CLI auf. Lösung: die aktuelle CLI-Version aus dem Portal neu ziehen.

License expired on <datum>

Das Token ist signaturseitig in Ordnung, aber das Ablaufdatum aus der Subscription ist überschritten. Verlängere die Subscription im Portal und lade danach das Archiv erneut herunter. Der Ablauf-Check toleriert fünf Minuten Uhrenabweichung, eine leicht abweichende Systemuhr löst diesen Fehler also nicht aus.

License requires CLI >= <version> / License only covers CLI <= <version>

Die Lizenz wurde mit einer Versionsklammer ausgestellt, die diese CLI nicht einschließt. Lösung: Lizenz im Portal neu erzeugen oder eine CLI-Version innerhalb der Klammer verwenden.

Datenschutz

Die Prüfung läuft komplett offline. Es findet kein Phone-Home statt, die CLI braucht keinen Netzwerkzugriff, um die Lizenz zu validieren. Die Signatur ist ausreichend.

Im Token stehen: User-ID (UUID), Account-Email, Plan-Name, Ausstellungs- und Ablaufdatum, der Name des Ausstellers, eine zufällige Lizenz-ID sowie die optionalen CLI-Versionsgrenzen (min_ver/max_ver). Diese Werte sind für den Lizenznehmer ohnehin offensichtlich; sie sind kein Geheimnis, sondern der Anker der Lizenz selbst.