Wiki

CLI uversion

Vollständige uVersion-CLI-Referenz: alle Befehle, Flags, Beispiele, JSON output, Exit-Codes.

Die uversion-Binärdatei deckt jede VCS-Operation ab, die im Desktop-Client verfügbar ist, und bietet zusätzlich eine maschinenlesbare --json-Ausgabe für die Automatisierung (CI/CD, Onboarding-Skripte, Integration von Drittanbieter-Tools). Alle Inhalte dieser Seite richten sich an Entwickler und Studio-Admins.

Installation

Unter Windows ist die uversion.exe-Binärdatei im Installer des Desktop-Clients enthalten und wird automatisch zum Benutzer-PATH hinzugefügt (%LOCALAPPDATA%\uVersion). Der PATH-Eintrag wird bei jedem Update entdoppelt und bei der Deinstallation entfernt. Öffnen Sie ein neues Terminal und tippen Sie:

uversion --help

Unter macOS geschieht dies automatisch: Beim ersten Start erstellt der Desktop-Client einen Link zur eingebetteten Binärdatei unter ~/.local/bin/uversion und stellt sicher, dass dieser Ordner im PATH liegt (über ~/.zprofile). Starten Sie die App einmal, öffnen Sie ein neues Terminal, und der Befehl uversion ist verfügbar. Um dies manuell an einen anderen Ort im PATH zu legen:

ln -s /Applications/uVersion.app/Contents/Resources/uversion /usr/local/bin/uversion

Unter Linux ist das CLI noch nicht in den .deb- / .AppImage-Paketen gebündelt. Bauen Sie es bei Bedarf aus den Quellen:

git clone https://github.com/jeremweb/uversion
cargo build -p uversion-cli --release
sudo cp target/release/uversion /usr/local/bin/

So prüfen Sie die installierte Version:

$ uversion --version

Cheatsheet: alle Befehle

Alle verfügbaren Befehle, in der Reihenfolge, in der man ihnen typischerweise begegnet:

Befehl	Was er tut
`uversion login <url> -u <user>`	Bei einem Server authentifizieren
`uversion logout`	Gespeicherte Anmeldedaten löschen
`uversion repos`	Zugängliche Repositories auflisten
`uversion clone <repo> [path]`	Ein Repository klonen
`uversion info`	Workspace-Status + aktuellen Benutzer anzeigen
`uversion status [paths...]`	Geänderte / neue / gelöschte / gesperrte Dateien anzeigen
`uversion checkout <paths...>`	Dateien zum Bearbeiten sperren
`uversion checkin <paths...> -m "..."`	Änderungen hochladen und committen
`uversion revert <paths...>`	Lokale Änderungen verwerfen, die Locks freigeben
`uversion sync`	Änderungen vom Server abrufen (gesamtes Repo)
`uversion content <path> --revision <rev>`	Eine bestimmte Version einer Datei herunterladen
`uversion log`	Commit-Verlauf
`uversion lock list`	Alle aktiven Locks im Repo anzeigen
`uversion lock release <paths...>`	Ein Lock freigeben, ohne die Datei anzufassen
`uversion lock heartbeat`	Ablauf aller gehaltenen Locks verlängern (lange CI-Jobs)
`uversion trust <url>`	Den selbstsignierten TLS-Fingerprint eines Servers anheften (TOFU, interaktiv; `--yes` zum Skripten)
`uversion mistrust <url>`	Den angehefteten Fingerprint eines Servers entfernen
`uversion trusted`	Server mit angeheftetem Fingerprint auflisten

Alle Befehle (außer uversion content) akzeptieren --json, um eine maschinenlesbare Ausgabe zu erzeugen (siehe JSON output). Alle Befehle akzeptieren auch --help für die Details der Flags.

Authentifizierung

`uversion login`

Authentifiziert bei einem uVersion-Server. Das zurückgegebene JWT wird im System-Keyring gespeichert (Windows Credential Manager, macOS Keychain, libsecret unter Linux) und mit dem Desktop-Client sowie den Editor-Plugins geteilt.

uversion login <server_url> -u <username> [-p <password>]

Flag	Description
`-u, --username`	Benutzername
`-p, --password`	Passwort. Wenn weggelassen, eine stille Eingabeaufforderung (keine Anzeige)

Beispiele:

$ uversion login https://uversion.mygamestudio.com -u alice
Password: ********
✓ Authenticated as alice (role: artist)

$ uversion login http://192.168.1.100:3000 -u bob -p $UV_PASSWORD
✓ Authenticated as bob (role: programmer)

$ uversion login https://uversion.mygamestudio.com -u ci-nightly -p "$UV_PASSWORD"
✓ Authenticated as ci-nightly (role: programmer)

`uversion logout`

Entfernt das Token aus dem System-Keyring. Der nächste Befehl, der eine Authentifizierung erfordert, fragt erneut nach dem Passwort.

$ uversion logout
✓ Credentials cleared

Repositories

`uversion repos`

Listet die Repositories auf, auf die der aktuelle Benutzer Zugriff hat.

$ uversion repos
ID     Name                           Description
----------------------------------------------------------------------
1      hero-rpg                       Main RPG project
2      shared-assets                  Shared asset library
12     prototype-fps                  R&D prototype FPS

`uversion clone`

Klont ein Repository lokal. Wenn local_path weggelassen wird, wird ein nach dem Repo benannter Ordner im aktuellen Arbeitsverzeichnis erstellt.

uversion clone <repo_name_or_id> [local_path]

Beispiele:

$ uversion clone hero-rpg
Cloning hero-rpg to ./hero-rpg...
✓ 8,432 files in 47s (14.2 GB downloaded, 6.1 GB on disk after dedup)

$ uversion clone hero-rpg D:\Projects\HeroRPG
$ uversion clone 1                              # par ID au lieu du nom

Dateien

`uversion status`

Zeigt den Status der Dateien im aktuellen Workspace an: geändert, neu (nicht verfolgt), gelöscht, von anderen gesperrt.

uversion status [paths...] [--json]

Beispiele:

$ uversion status
Modified:
  M  Content/Maps/MainLevel.umap (locked by alice)
New:
  A  Content/Textures/NewTexture.png
Deleted:
  D  Content/OldAsset.uasset
Locked by others:
  L  Content/Characters/Hero.uasset  (locked by bob)

1 modified, 1 new, 1 deleted, 1 locked by others

$ uversion status Content/Maps                  # filtre par dossier
$ uversion status --json | jq '.summary'        # extraction scriptable

`uversion checkout`

Erwirbt ein exklusives Lock auf die Zieldateien und macht sie auf der Festplatte beschreibbar.

uversion checkout <paths...> [--force] [--add] [--json]

Flag	Description
`--force`	Erzwingt das Checkout, auch wenn die Datei von einem anderen Benutzer gesperrt ist. Erfordert die Berechtigung `force_unlock` (standardmäßig Admin). Auditiert.
`--add`	Erlaubt das Checkout von Pfaden, die lokal noch nicht vorhanden sind (neue Dateien)

Beispiele:

$ uversion checkout Content/Maps/MainLevel.umap
✓ Lock acquired: Content/Maps/MainLevel.umap

$ uversion checkout Content/Characters/Hero.uasset Content/Characters/Villain.uasset
✓ Lock acquired: Content/Characters/Hero.uasset
✓ Lock acquired: Content/Characters/Villain.uasset

$ uversion checkout Content/Maps/MainLevel.umap   # déjà locked par bob
✗ Locked by bob since 2026-05-15T08:42:11Z. Use --force if you have permission, or request release.

$ uversion checkout --force Content/Maps/MainLevel.umap   # admin force-steal
⚠ Forced lock takeover (was bob)
✓ Lock acquired: Content/Maps/MainLevel.umap

`uversion checkin`

Lädt die geänderten Dateien hoch und committet sie in einer einzigen atomaren Transaktion an den Server. Die Locks werden nach Erfolg automatisch freigegeben.

uversion checkin [paths...] -m <message> [--all] [--json]

Flag	Description
`-m, --message`	Commit-Nachricht (erforderlich)
`-a, --all`	Bezieht jede geänderte Datei im Workspace ein, nicht nur die als Argument übergebenen

Beispiele:

$ uversion checkin Content/Maps/MainLevel.umap -m "Fixed lighting in main level"
Validating 1 file...
✓ All validation rules passed
Uploading: [####################] 100% · 84 MB
✓ Committed as 7f3a9b1 (1 file, 84 MB uploaded, 0 deduped)

$ uversion checkin --all -m "Weekly art update"   # tout le workspace
$ uversion checkin Content/Characters/ -m "Updated character meshes"

`uversion revert`

Verwirft lokale Änderungen an einer oder mehreren Dateien, stellt die Serverversion wieder her und gibt die zugehörigen Locks frei.

uversion revert <paths...>

Beispiele:

$ uversion revert Content/Maps/MainLevel.umap
✓ Reverted: Content/Maps/MainLevel.umap (lock released)

$ uversion revert Content/Characters/        # revert récursif par dossier

`uversion sync`

Lädt die neuesten Änderungen vom Server herunter und wendet sie auf den lokalen Workspace an.

uversion sync [--force] [--json]

Flag	Description
`-f, --force`	Vollständiger Sync: lädt jede Datei erneut herunter, nicht nur das Delta seit dem letzten Sync. Nützlich bei einem beschädigten Workspace.

Beispiele:

$ uversion sync
Syncing from revision 41 → 47...
✓ 12 files updated, 3 added, 1 deleted (1.4 GB downloaded)

$ uversion sync --force                      # re-télécharge tout

`uversion content`

Lädt eine bestimmte Version einer Datei (nach Revisionsnummer) herunter, ohne den lokalen Workspace anzufassen. Nützlich zum Vergleichen, Archivieren oder Abrufen eines historischen Zustands, ohne ein Revert durchzuführen.

uversion content <path> [-r <revision>] [-o <file>]

Beispiele:

$ uversion content Content/Maps/MainLevel.umap --revision 12 --output ./snapshot.umap
✓ Downloaded MainLevel.umap @ rev 12 → ./snapshot.umap (84 MB)

$ uversion content Content/Characters/Hero.uasset --revision 12 --output ./hero-v12.uasset

Verlauf

`uversion log`

Commit-Verlauf des aktuellen Repositories, optional nach Datei gefiltert.

uversion log [-n <limit>] [-p <path>] [--json]

Flag	Description
`-n, --limit`	Anzahl der anzuzeigenden Einträge (Standard: 20)
`-p, --path`	Nach Dateipfad filtern

Beispiele:

$ uversion log
commit 7f3a9b1c2d... (HEAD)
Author: alice
Date:   2026-05-15T08:30:00Z

    Fixed lighting in main level

    Content/Maps/MainLevel.umap (rev 12)

commit 6e2b8a0...
Author: bob
Date:   2026-05-14T17:22:00Z

    Hero pose pass

    Content/Characters/Hero.uasset (rev 8)

$ uversion log -n 5                                      # 5 derniers commits
$ uversion log --path Content/Maps/MainLevel.umap        # historique d'un fichier
$ uversion log --json -n 50 | jq '.commits[].hash'       # extract hashes en CI

Locks

`uversion lock list`

Zeigt alle aktiven Locks im aktuellen Repository an.

uversion lock list [--json]

Beispiele:

$ uversion lock list
File                                     User            Acquired
----------------------------------------------------------------------
Content/Maps/MainLevel.umap             alice           2026-05-15T08:42:11Z
Content/Characters/Hero.uasset          bob             2026-05-14T17:00:00Z
Content/UI/HUD.uasset                   alice           2026-05-15T09:15:00Z

3 locks active

`uversion lock release`

Gibt manuell ein oder mehrere Locks frei, ohne den lokalen Inhalt der Datei anzufassen. Verwenden Sie es, wenn Sie ein Asset „zurückgeben“ möchten, ohne Änderungen vorgenommen zu haben (typischerweise, wenn Sie es versehentlich per Checkout ausgecheckt haben oder begonnene Arbeit ohne Einreichen aufgeben).

uversion lock release <paths...> [--json]

Beispiele:

$ uversion lock release Content/Maps/MainLevel.umap
✓ Lock released: Content/Maps/MainLevel.umap

`uversion lock heartbeat`

Verlängert den Ablauf aller Locks, die der aktuelle Benutzer hält. Für den normalen Workflow nicht erforderlich; wird von CI-Jobs verwendet, die ein Lock lange halten, damit Admins sehen, dass das Lock noch aktiv ist.

uversion lock heartbeat

Typisches Beispiel in CI:

$ while build_in_progress; do
    uversion lock heartbeat
    sleep 300
  done

Info

`uversion info`

Zeigt die Informationen des aktuellen Workspace, des authentifizierten Benutzers und des Sync-Status an.

$ uversion info
User: alice (lead)

Repository: hero-rpg (id: 1)
Server:     https://uversion.mygamestudio.com
Workspace:  alice-cli (ws-abc123)
Local path: D:\Projects\HeroRPG
Last sync:  revision 42 (2 hours ago)

Files: 8,432 (5 modified, 2 locked by you, 3 locked by others)

JSON output

Alle Befehle akzeptieren das Flag --json, um eine maschinenlesbare Ausgabe anstelle der menschenlesbaren Anzeige zu erzeugen. Unverzichtbar, um das CLI in Pipelines zu skripten.

Beispiel: `uversion status --json`

{
  "files": [
    {
      "path": "Content/Maps/MainLevel.umap",
      "status": "modified",
      "lock": { "user": "alice", "acquired_at": "2026-05-15T08:42:11Z" }
    },
    {
      "path": "Content/Textures/NewTexture.png",
      "status": "new",
      "lock": null
    }
  ],
  "summary": {
    "modified": 1,
    "new": 1,
    "deleted": 0,
    "locked_by_others": 0
  }
}

Beispiel: `uversion log --json -n 1`

{
  "commits": [
    {
      "hash": "7f3a9b1c2d...",
      "author": "alice",
      "date": "2026-05-15T08:30:00Z",
      "message": "Fixed lighting in main level",
      "files": [
        { "path": "Content/Maps/MainLevel.umap", "action": "modified", "revision": 12 }
      ]
    }
  ]
}

Fehlerbehandlung

Bei einem Fehler schreibt das CLI Error: <message> auf stderr und beendet sich mit Code 1. Fehler werden nicht als JSON auf stdout ausgegeben: Im --json-Modus ist nur die Erfolgsausgabe strukturiert. Testen Sie in Ihren Skripten den Exit-Code (ungleich null = Fehler).

Gängige Muster

Onboarding eines neuen Teammitglieds

uversion login https://uversion.mygamestudio.com -u newdev
uversion repos                                  # confirme l'accès
uversion clone hero-rpg ~/Projects/HeroRPG     # download initial

Täglicher Workflow (artist / programmer)

# Début de journée
uversion sync

# Avant d'éditer
uversion checkout Content/Maps/MainLevel.umap

# ... édition dans Unreal Editor ou Rider ...

# Commit en fin de journée
uversion checkin --all -m "Updated main level + hero animations"

Audit-Skript: Wer hat was gesperrt?

uversion lock list --json | jq -r '.locks[] | "\(.user)\t\(.path)\t\(.acquired_at)"'

Ein Asset in einer vergangenen Revision abrufen (ohne den Workspace anzufassen)

uversion log --path Content/Characters/Hero.uasset -n 10    # repère le commit voulu
uversion content Content/Characters/Hero.uasset --revision 6e2b8a0 --output ~/backup/Hero-v8.uasset

CI-Nightly-Build

uversion login "$UV_SERVER" -u ci-nightly -p "$UV_PASSWORD"
uversion clone hero-rpg ./project
cd project
uversion sync --json > sync.log

# Tenir le lock pendant un long cook
uversion checkout Content/Cooking/Distribution.uasset
( while pgrep RunUAT; do uversion lock heartbeat; sleep 300; done ) &

# ... build / cook ...

uversion lock release Content/Cooking/Distribution.uasset

Umgebungsvariablen & Exit-Codes

Umgebungsvariablen

Variable	Description
`RUST_LOG`	Steuert die Ausführlichkeit der Logs (auf stderr geschrieben), z. B. `RUST_LOG=debug`. Standardstufe: `warn`. Dies ist die einzige Umgebungsvariable, die das CLI liest.

Server-URL und Benutzername stammen aus config.toml (%APPDATA%/uversion/uVersion/config/), das Token aus dem System-Keyring: keine UV_*-Variable wird gelesen.

Exit-Codes

Code	Bedeutung
`0`	Erfolg
`1`	Jeder Anwendungsfehler (Auth, Berechtigung, Netzwerk, Server, IO, außerhalb des Workspace, Konflikt, Validierung…). Das CLI unterscheidet Fehler nicht nach Exit-Code.
`2`	Fehler beim Parsen der Argumente, `--help` oder `--version` (clap-Konvention)

Beispielverwendung in einem Bash-Skript:

uversion checkin --all -m "Nightly"
if [ $? -ne 0 ]; then
  echo "Checkin failed, see logs (stderr)"
  exit 1
fi

Installation

Cheatsheet: alle Befehle

Authentifizierung

uversion login

uversion logout

Repositories

uversion repos

uversion clone

Dateien

uversion status

uversion checkout

uversion checkin

uversion revert

uversion sync

uversion content

Verlauf

uversion log

Locks

uversion lock list

uversion lock release

uversion lock heartbeat

Info

uversion info

JSON output

Beispiel: uversion status --json

Beispiel: uversion log --json -n 1

Fehlerbehandlung

Gängige Muster

Onboarding eines neuen Teammitglieds

Täglicher Workflow (artist / programmer)

Audit-Skript: Wer hat was gesperrt?

Ein Asset in einer vergangenen Revision abrufen (ohne den Workspace anzufassen)

CI-Nightly-Build

Umgebungsvariablen & Exit-Codes

Umgebungsvariablen

Exit-Codes

`uversion login`

`uversion logout`

`uversion repos`

`uversion clone`

`uversion status`

`uversion checkout`

`uversion checkin`

`uversion revert`

`uversion sync`

`uversion content`

`uversion log`

`uversion lock list`

`uversion lock release`

`uversion lock heartbeat`

`uversion info`

Beispiel: `uversion status --json`

Beispiel: `uversion log --json -n 1`