Wiki

CLI uversion

Référence complète du CLI uVersion : toutes les commandes, flags, exemples, JSON output, exit codes.

Le binaire uversion couvre l'intégralité des opérations VCS disponibles dans le client desktop, avec en plus une sortie --json machine-readable pour l'automatisation (CI/CD, scripts d'onboarding, intégration tooling tiers). Tout le contenu de cette page est destiné aux développeurs et aux admins studio.

Installation

Sur Windows, le binaire uversion.exe est inclus dans l'installeur du client desktop et ajouté automatiquement au PATH utilisateur (%LOCALAPPDATA%\uVersion). L'entrée PATH est dédoublonnée à chaque mise à jour et retirée à la désinstallation. Ouvrez un nouveau terminal et tapez :

uversion --help

Sur macOS, c'est automatique : au premier lancement, le client desktop crée un lien vers le binaire embarqué dans ~/.local/bin/uversion et s'assure que ce dossier est sur le PATH (via ~/.zprofile). Lancez l'application une fois, ouvrez un nouveau terminal, et la commande uversion est disponible. Pour le faire à la main vers un autre emplacement du PATH :

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

Sur Linux, le CLI n'est pas encore bundlé dans les paquets .deb / .AppImage. Compilez-le depuis les sources si vous en avez besoin :

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

Pour vérifier la version installée :

$ uversion --version

Cheatsheet : toutes les commandes

L'ensemble des commandes disponibles, dans l'ordre où on les rencontre typiquement :

Commande	Ce qu'elle fait
`uversion login <url> -u <user>`	S'authentifier sur un serveur
`uversion logout`	Effacer les identifiants stockés
`uversion repos`	Lister les repositories accessibles
`uversion clone <repo> [path]`	Cloner un repository
`uversion info`	Afficher l'état du workspace + user courant
`uversion status [paths...]`	Voir les fichiers modifiés / nouveaux / supprimés / locked
`uversion checkout <paths...>`	Verrouiller des fichiers pour édition
`uversion checkin <paths...> -m "..."`	Uploader et committer les changements
`uversion revert <paths...>`	Annuler les changements locaux, release les locks
`uversion sync`	Récupérer les changements depuis le serveur (repo entier)
`uversion content <path> --revision <rev>`	Télécharger une version spécifique d'un fichier
`uversion log`	Historique des commits
`uversion lock list`	Voir tous les locks actifs du repo
`uversion lock release <paths...>`	Release un lock sans toucher au fichier
`uversion lock heartbeat`	Prolonge l'expiration de tous les locks détenus (jobs CI longs)
`uversion trust <url>`	Épingler l'empreinte TLS auto-signée d'un serveur (TOFU, interactif ; `--yes` pour scripter)
`uversion mistrust <url>`	Retirer l'empreinte épinglée d'un serveur
`uversion trusted`	Lister les serveurs avec empreinte épinglée

Toutes les commandes (sauf uversion content) acceptent --json pour produire une sortie machine-readable (voir JSON output). Toutes les commandes acceptent aussi --help pour le détail des flags.

Authentication

`uversion login`

S'authentifie auprès d'un serveur uVersion. Le JWT retourné est stocké dans le keyring système (Windows Credential Manager, macOS Keychain, libsecret sur Linux) et partagé avec le client desktop et les plugins éditeur.

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

Flag	Description
`-u, --username`	Nom d'utilisateur
`-p, --password`	Mot de passe. Si omis, prompt silencieux (pas d'echo)

Exemples :

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

Supprime le token du keyring système. La prochaine commande nécessitant l'authentification redemandera le mot de passe.

$ uversion logout
✓ Credentials cleared

Repositories

`uversion repos`

Liste les repositories auxquels l'utilisateur courant a accès.

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

Clone un repository localement. Si local_path est omis, un dossier nommé d'après le repo est créé dans le working directory courant.

uversion clone <repo_name_or_id> [local_path]

Exemples :

$ 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

Files

`uversion status`

Affiche l'état des fichiers du workspace courant : modifiés, nouveaux (untracked), supprimés, locked par d'autres.

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

Exemples :

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

Acquiert un lock exclusif sur les fichiers ciblés et les rend writable sur disque.

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

Flag	Description
`--force`	Force le checkout même si le fichier est locked par un autre user. Nécessite la capability `force_unlock` (admin par défaut). Audité.
`--add`	Autorise le checkout de chemins encore absents localement (nouveaux fichiers)

Exemples :

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

Upload les fichiers modifiés et les commit au serveur en une transaction atomique. Les locks sont release automatiquement après succès.

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

Flag	Description
`-m, --message`	Message de commit (obligatoire)
`-a, --all`	Inclure tous les fichiers modifiés dans le workspace, pas seulement ceux passés en argument

Exemples :

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

Discard les changements locaux d'un ou plusieurs fichiers, restore la version serveur, release les locks correspondants.

uversion revert <paths...>

Exemples :

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

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

`uversion sync`

Télécharge les derniers changements depuis le serveur et les applique au workspace local.

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

Flag	Description
`-f, --force`	Sync complet : re-télécharge tous les fichiers, pas seulement le delta depuis le dernier sync. Utile en cas de workspace corrompu.

Exemples :

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

Télécharge une version spécifique d'un fichier (par numéro de révision) sans toucher au workspace local. Utile pour comparer, archiver, ou récupérer un état historique sans faire un revert.

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

Exemples :

$ 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

History

`uversion log`

Historique des commits du repository courant, optionnellement filtré par fichier.

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

Flag	Description
`-n, --limit`	Nombre d'entrées à afficher (défaut : 20)
`-p, --path`	Filtre par chemin de fichier

Exemples :

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

Affiche tous les locks actifs dans le repository courant.

uversion lock list [--json]

Exemples :

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

Release manuellement un ou plusieurs locks sans toucher au contenu local du fichier. À utiliser quand vous voulez « rendre » un asset sans avoir fait de modifs (typiquement, vous l'avez checkout par erreur, ou vous abandonnez le travail commencé sans envoyer).

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

Exemples :

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

`uversion lock heartbeat`

Prolonge l'expiration de tous les locks détenus par l'utilisateur courant. Pas nécessaire pour le workflow normal ; utilisé par les jobs CI qui tiennent un lock pendant longtemps, pour que les admins voient que le lock est encore actif.

uversion lock heartbeat

Exemple typique en CI :

$ while build_in_progress; do
    uversion lock heartbeat
    sleep 300
  done

Info

`uversion info`

Affiche les informations du workspace courant, de l'utilisateur authentifié, et de l'état de sync.

$ 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

Toutes les commandes acceptent le flag --json pour produire une sortie machine-readable à la place de l'affichage humain. Indispensable pour scripter le CLI dans des pipelines.

Exemple : `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
  }
}

Exemple : `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 }
      ]
    }
  ]
}

Gestion des erreurs

En cas d'échec, le CLI écrit Error: <message> sur stderr et sort avec le code 1. Les erreurs ne sont pas émises en JSON sur stdout : en mode --json, seule la sortie de succès est structurée. Dans vos scripts, testez le code de sortie (non-zéro = échec).

Patterns courants

Onboarding d'un nouveau membre d'équipe

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

Workflow quotidien (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"

Script d'audit : qui a quoi de locké ?

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

Récupérer un asset à une révision passée (sans toucher au workspace)

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

Variables d'environnement & exit codes

Variables d'environnement

Variable	Description
`RUST_LOG`	Contrôle la verbosité des logs (écrits sur stderr), ex. `RUST_LOG=debug`. Niveau par défaut : `warn`. C'est la seule variable d'environnement lue par le CLI.

L'URL serveur et le nom d'utilisateur proviennent de config.toml (%APPDATA%/uversion/uVersion/config/), le token du keyring système : aucune variable UV_* n'est lue.

Exit codes

Code	Signification
`0`	Succès
`1`	Toute erreur applicative (auth, permission, réseau, serveur, IO, hors workspace, conflit, validation…). Le CLI ne distingue pas les erreurs par code de sortie.
`2`	Erreur d'analyse des arguments, `--help` ou `--version` (convention clap)

Exemple d'utilisation en script bash :

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

Installation

Cheatsheet : toutes les commandes

Authentication

uversion login

uversion logout

Repositories

uversion repos

uversion clone

Files

uversion status

uversion checkout

uversion checkin

uversion revert

uversion sync

uversion content

History

uversion log

Locks

uversion lock list

uversion lock release

uversion lock heartbeat

Info

uversion info

JSON output

Exemple : uversion status --json

Exemple : uversion log --json -n 1

Gestion des erreurs

Patterns courants

Onboarding d'un nouveau membre d'équipe

Workflow quotidien (artist / programmer)

Script d'audit : qui a quoi de locké ?

Récupérer un asset à une révision passée (sans toucher au workspace)

CI nightly build

Variables d'environnement & exit codes

Variables d'environnement

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`

Exemple : `uversion status --json`

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