CLI als Standalone-Binary

Die CLI ohne Installer, für CI-Runner, Docker, Linux und macOS.

Aktualisiert am 2026-07-10

Auf CI-Runnern, in Docker-Images und auf Linux- oder macOS-Entwicklungsrechnern ist der Standalone-CLI-Build der richtige Weg. Ein eigenständiges Archiv (die CLI samt gebündelter Runtime), keine separate Runtime-Installation nötig.

Welcher Build für welche Plattform

Datei	Für
`codecharter-X.Y.Z-win-x64.zip`	Windows x64
`codecharter-X.Y.Z-linux-x64.tar.gz`	Linux x64 (glibc-basiert)
`codecharter-X.Y.Z-osx-x64.tar.gz`	macOS Intel
`codecharter-X.Y.Z-osx-arm64.tar.gz`	macOS Apple Silicon

Alle vier sind im Portal unter /downloads verfügbar.

Installation als .NET Global Tool

Wenn Sie bereits das .NET 9 SDK installiert haben, ist die Installation des Pakets CodeCharter.Cli von nuget.org auf jeder Plattform der schnellste Weg:

dotnet tool install --global CodeCharter.Cli
codecharter --version

Aktualisieren auf die neueste Version:

dotnet tool update --global CodeCharter.Cli

Auch das Global Tool benötigt zur Laufzeit eine gültige CodeCharter-Lizenz bzw. einen API-Key, genau wie die Standalone-Archive weiter unten; die Installation des Pakets allein gewährt kein Nutzungsrecht. Siehe CLI-Lizenzierung zur Konfiguration von CODECHARTER_API_KEY oder einer codecharter.license-Datei.

Download und Auspacken

# Beispiel: Linux x64
curl -L -o codecharter.tar.gz \
    -H "Authorization: Bearer $CODECHARTER_API_KEY" \
    https://codecharter.tools/api/v1/cli/linux-x64/latest

mkdir -p /opt/codecharter
tar -xzf codecharter.tar.gz -C /opt/codecharter
chmod +x /opt/codecharter/codecharter
/opt/codecharter/codecharter --version

Das Archiv enthält nur die CLI und ihre Runtime; Regeln werden nicht mitgeliefert. Sie kommen aus den Profilen in Ihrer .codecharter/config.yml, aufgelöst gegen das Portal (mit codecharter restore in den lokalen Cache geladen).

Der API-Key hat eine Doppelrolle: Er autorisiert nicht nur den Download, sondern wird von der CLI über die Umgebungsvariable CODECHARTER_API_KEY auch zur Laufzeit genutzt, um automatisch eine kurzlebige Lizenz vom Portal zu beziehen. Ohne gültige Lizenz beendet sich jeder Befehl mit Exit-Code 6. Siehe CLI-Lizenzierung.

Auf macOS müssen Sie beim ersten Start eventuell den Gatekeeper-Check durchklicken (Systemeinstellungen → Datenschutz → "Trotzdem öffnen") oder das Quarantäne-Attribut entfernen:

xattr -dr com.apple.quarantine /opt/codecharter

Die Binaries sind derzeit nicht notarisiert. Nutzen Sie auf macOS einen der oben genannten Wege.

In Docker

Den API-Key niemals in einen Image-Layer einbacken. ARG schreibt den Wert in die Build-Layer-History und macht ihn aus dem Image extrahierbar. Stattdessen BuildKit Secret Mounts verwenden (erfordert Docker 18.09+ mit DOCKER_BUILDKIT=1 oder BuildKit als Standard).

# syntax=docker/dockerfile:1
FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build
WORKDIR /app
COPY . .
RUN dotnet build -c Release

FROM mcr.microsoft.com/dotnet/runtime:9.0
WORKDIR /app

RUN --mount=type=secret,id=cgkey \
    mkdir -p /opt/codecharter \
    && curl -sSL \
    -H "Authorization: Bearer $(cat /run/secrets/cgkey)" \
    -o codecharter.tar.gz \
    https://codecharter.tools/api/v1/cli/linux-x64/latest \
    && tar -xzf codecharter.tar.gz -C /opt/codecharter \
    && rm codecharter.tar.gz \
    && chmod +x /opt/codecharter/codecharter

ENV PATH="/opt/codecharter:${PATH}"
COPY --from=build /app/publish ./

Build mit:

DOCKER_BUILDKIT=1 docker build --secret id=cgkey,src=<(echo "$CODECHARTER_API_KEY") -t myapp .

Alternativ lassen Sie das codecharter-Binary ganz aus dem Image heraus und führen die Analyse vor dem Docker-Build auf dem CI-Runner aus. analyze erwartet den Pfad zu einer .sln-, .slnx- oder .csproj-Datei:

codecharter analyze MySolution.sln --output sarif:codecharter.sarif
docker build -t myapp .

Caching in CI

Die Archive sind eigenständig und einige Dutzend Megabyte groß. Wenn Ihr CI-Provider Caching unterstützt, cachen Sie das ausgepackte Verzeichnis statt des Archivs. Auspacken ist die teurere Operation im Vergleich zum Download.

Die offizielle GitHub Action nutzt die Standalone-Archive nicht; sie führt CodeCharter aus einem Container-Image aus. Siehe GitHub Actions.

Automatische Updates

Die CLI hält sich selbst aktuell. Bei jedem Lauf, direkt nach der Lizenzprüfung, startet sie im Hintergrund eine schnelle Prüfung auf ein neueres Release und lädt es, falls eines veröffentlicht ist. Das Update läuft außerhalb des Laufs und wird erst beim nächsten Start aktiv: Der gestartete Befehl läuft immer auf seiner aktuellen Version zu Ende, die neuere Version wird erst bei einem späteren Start aktiv. Kein Befehl wartet je auf das Update, und ein Binary wird nie mitten im Lauf ausgetauscht, sodass auch der langlebige mcp-Server nie mitten in einer Sitzung gestört wird.

Die Prüfung ist auf einmal pro 24 Stunden gedrosselt (eine kleine Statusdatei merkt sich, wann sie zuletzt lief), sodass die meisten Läufe gar keine Netzwerkarbeit verursachen.

Wie das Update eingespielt wird, hängt von der Installationsart ab:

.NET Global Tool (dotnet tool install --global CodeCharter.Cli): Die CLI führt für Sie dotnet tool update --global CodeCharter.Cli aus.
Standalone-Archiv / Docker: Die CLI lädt das passende Archiv vom Portal (mit derselben kurzlebigen Lizenz, die die Lizenzprüfung gerade erneuert hat), prüft dessen SHA-256 und tauscht es atomar in das Installationsverzeichnis, sobald kein codecharter-Prozess diese Dateien mehr offen hält. Die vorherige Version bleibt als .bak-Verzeichnis daneben für ein Rollback erhalten.

Status und vorbereitete Downloads liegen unter Ihrem benutzerbezogenen Konfigurationsverzeichnis, also $XDG_CONFIG_HOME/codecharter, %APPDATA%\CodeCharter oder ~/.config/codecharter: self-update.json (die Status- und Drossel-Datei) und staging/<version>/ (ein geprüftes Release, das auf seine Aktivierung wartet).

Deaktivieren (CI)

Für reproduzierbare Pipelines pinnen Sie in der Regel eine Version und schalten das Auto-Update ab. Beide Wege unterdrücken die Prüfung:

# Pro Lauf:
codecharter analyze MySolution.sln --skip-update

# Oder einmalig für die ganze Pipeline über die Umgebungsvariable:
export CODECHARTER_SKIP_UPDATE=1

CODECHARTER_UPDATE_INTERVAL überschreibt das Drossel-Intervall in ganzen Sekunden (0 erzwingt eine Prüfung bei jedem Lauf, praktisch zum Testen des Update-Pfads):

export CODECHARTER_UPDATE_INTERVAL=3600   # höchstens einmal pro Stunde prüfen

Versions-Pinning

Statt /latest/ können Sie eine konkrete Version pinnen:

https://codecharter.tools/api/v1/cli/linux-x64/1.0.12

Der Versions-Selektor akzeptiert auch Präfixe wie 1.0 oder v1; geliefert wird das neueste passende Release. Download-Antworten enthalten einen X-CodeCharter-Sha256-Header, mit dem Ihre Pipeline die Integrität des Archivs prüfen kann. Bei abgelaufener Subscription liefert der Download-Endpunkt HTTP 402.

Wir empfehlen das Pinnen für reproduzierbare Builds. Siehe Versionierung.

PATH-Setup

Wenn das CLI-Verzeichnis nicht im PATH liegt, können Sie den vollen Pfad nutzen. Für ein persistentes PATH-Setup auf einer Workstation:

# Linux/macOS, in .bashrc oder .zshrc
export PATH="/opt/codecharter:$PATH"

# Windows -- liest und schreibt den dauerhaften User-PATH (bleibt nach Neustart)
$current = [Environment]::GetEnvironmentVariable("PATH", "User")
[Environment]::SetEnvironmentVariable("PATH", "$current;C:\codecharter", "User")