Wiki

CLI uversion

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

Le binaire uversion couvre les mêmes opérations de versionnage que le client desktop, avec en plus une sortie --json exploitable par un programme, pour l'automatisation : intégration continue, scripts d'accueil, outillage maison. Cette page s'adresse aux développeurs et aux administrateurs de 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, c'est automatique aussi, exactement comme sur macOS. Le client desktop est distribué en AppImage, et cette AppImage contient le binaire uversion. Au premier lancement, l'application le place dans ~/.local/bin/uversion et s'assure que ce dossier est sur le PATH. Lancez l'application une fois, ouvrez un nouveau terminal, et la commande est disponible :

uversion --help

Vous n'avez rien à compiler. Sur Linux, le client desktop se distribue uniquement en AppImage, et c'est elle qui apporte le CLI. Pour placer le binaire ailleurs sur le PATH, copiez-le depuis ~/.local/bin :

sudo cp ~/.local/bin/uversion /usr/local/bin/uversion

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...>`	Réserver des fichiers pour édition (pose un verrou)
`uversion checkin <paths...> -m "..."`	Envoyer et valider les changements
`uversion revert <paths...>`	Annuler les changements locaux et relâcher les verrous
`uversion sync`	Récupérer les changements depuis le serveur (dépôt entier)
`uversion content <path> --revision <n>`	Télécharger une version précise d'un fichier
`uversion log`	Historique des commits
`uversion lock list`	Voir tous les verrous du dépôt
`uversion lock release <paths...>`	Relâcher un verrou sans toucher au fichier
`uversion lock heartbeat`	Signaler que vos verrous sont toujours utilisés (pour la supervision)
`uversion trust <url>`	Mémoriser l'empreinte du certificat auto-signé d'un serveur (interactif ; `--yes` pour scripter)
`uversion mistrust <url>`	Oublier l'empreinte mémorisée d'un serveur
`uversion trusted`	Lister les serveurs dont l'empreinte est mémorisée

Toutes les commandes sauf uversion content acceptent --json, qui remplace l'affichage lisible par une sortie exploitable par un programme (voir JSON output). Toutes acceptent --help pour le détail des options.

checkout, checkin et revert acceptent aussi --paths-file <fichier>, indispensable dès qu'on travaille à l'échelle d'un projet Unreal. Voir Listes de chemins volumineuses.

Authentication

`uversion login`

S'authentifie auprès d'un serveur uVersion. Le serveur remet un jeton de session (un JWT, pour JSON Web Token), que le CLI range dans le gestionnaire de mots de passe du système : le Gestionnaire d'identification sur Windows, le Trousseau sur macOS, libsecret sur Linux. Ce jeton est partagé avec le client desktop, le plugin Unreal et le plugin Rider : se connecter d'un côté connecte les autres, et se déconnecter les déconnecte tous.

uversion login <url_serveur> -u <utilisateur> [-p <mot_de_passe>]

Option	Description
`-u, --username`	Nom d'utilisateur
`-p, --password`	Déconseillé. Voir l'encadré ci-dessous. Si l'option est omise, le CLI lit la variable d'environnement `UVERSION_PASSWORD`, et à défaut demande le mot de passe de façon interactive, sans écho à l'écran.

Pour scripter une connexion, utilisez UVERSION_PASSWORD, jamais -p

Sur un système multi-utilisateur, la ligne de commande de chaque processus est lisible par les autres comptes de la machine : ps sous Linux et macOS, le Gestionnaire des tâches ou wmic sous Windows. Un mot de passe passé en argument y apparaît en clair, y compris s'il vient d'une variable, puisque le shell la remplace par sa valeur avant de lancer le programme. Il finit aussi dans l'historique du shell et souvent dans les journaux de la chaîne d'intégration continue.

Le CLI lit UVERSION_PASSWORD précisément pour éviter cela, et affiche un avertissement sur la sortie d'erreur quand -p est employé.

Exemples :

$ uversion login https://uversion.mygamestudio.com -u alice
Password:
Logged in as alice (artist)

# Sur un serveur de studio, en interne. Le port par défaut est 8443, en HTTPS.
$ uversion login https://192.168.1.100:8443 -u bob
Password:
Logged in as bob (programmer)

# Compte d'intégration continue : le mot de passe passe par l'environnement,
# jamais par la ligne de commande.
$ export UVERSION_PASSWORD="$SECRET_FROM_VAULT"
$ uversion login "$UV_SERVER" -u ci-nightly
Logged in as ci-nightly (programmer)

À la première connexion à un serveur qui présente un certificat auto-signé, le CLI affiche l'empreinte du certificat et vous demande de la confirmer, puis la mémorise. C'est le principe de la confiance au premier contact, le même que SSH : on accepte une identité une fois, et toute présentation d'une identité différente par la suite est signalée. Si l'empreinte change, le CLI refuse la connexion et vous prévient : c'est soit un renouvellement légitime du certificat, soit une interception de votre trafic par un tiers. La manœuvre délibérée est alors uversion mistrust <url>, puis une nouvelle connexion.

`uversion logout`

Efface le jeton du gestionnaire de mots de passe du système et invalide côté serveur toutes les sessions de ce compte. Comme le jeton est partagé, cela déconnecte aussi le client desktop, le plugin Unreal et le plugin Rider, sur toutes vos machines.

$ uversion logout
Logged out (alice)

$ uversion logout       # si aucune session n'était ouverte
Already logged out

Quel compte agit ? Celui du workspace, pas le dernier connecté

C'est le point qui surprend le plus, et il vaut mieux le connaître avant de scripter quoi que ce soit : l'identité utilisée n'est pas celle de la dernière connexion, c'est celle du workspace dans lequel vous vous trouvez.

Un workspace, c'est un dossier cloné, reconnaissable à son sous-dossier .uversion. Le fichier .uversion/config.toml y enregistre le serveur et le compte propriétaire :

[repository]
id = "1"
name = "hero-rpg"
server_url = "https://uversion.mygamestudio.com"

[workspace]
id = "..."
name = "alice-cli"
owner = "alice"
last_synced_revision = 42

Dès que vous êtes dans un workspace, server_url et owner font autorité : status, checkout, checkin, revert, sync, log, content, lock et info s'authentifient comme owner, sur server_url.

Seules login, logout, repos et clone utilisent la configuration partagée entre tous les workspaces (%APPDATA%/uversion/uVersion/config/config.toml sous Windows), qui suit le compte actif du client desktop.

Pourquoi. Un même poste sert souvent plusieurs comptes, par exemple un freelance qui travaille pour deux studios. Sans cette règle, tous les workspaces agiraient sous le compte actif du moment : un dossier cloné par alice mais utilisé alors que bob est actif poserait ses verrous au nom de bob, verrait ses propres fichiers comme « verrouillés par quelqu'un d'autre », et se ferait refuser ses envois.

Pour changer l'identité d'un workspace, modifiez le champ owner dans .uversion/config.toml, et assurez-vous que ce compte s'est connecté au moins une fois sur cette machine (uversion login), pour que son jeton soit présent. Vérifiez ensuite avec uversion info, qui affiche le compte réellement utilisé.

Limite connue : un même nom d'utilisateur sur deux serveurs

Le jeton est rangé sous le seul nom d'utilisateur, sans le serveur. Si le même nom existe sur deux serveurs uVersion différents, les deux se partagent une seule et même entrée : se connecter au second remplace le jeton du premier. Utilisez des noms distincts, ou n'employez qu'un serveur à la fois depuis une même machine.

Repositories

`uversion repos`

Liste les dépôts auxquels le compte a accès. Cette commande utilise la configuration partagée, pas celle d'un workspace : elle répond donc pour le compte de votre dernière connexion.

$ 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 repos          # si aucun dépôt n'est accessible
No repositories found

`uversion clone`

Récupère un dépôt en local. Si le chemin est omis, un dossier nommé d'après le dépôt est créé dans le répertoire courant. Le clone crée aussi le sous-dossier .uversion, qui fait du dossier un workspace et enregistre le serveur et le compte propriétaire.

Le transfert applique la déduplication : le contenu est découpé en blocs, et un bloc déjà présent n'est stocké qu'une fois, même s'il apparaît dans plusieurs fichiers. C'est pourquoi l'espace occupé sur disque est souvent nettement inférieur au volume téléchargé.

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`

Pose un verrou exclusif sur les fichiers ciblés et les rend modifiables sur disque. Les fichiers suivis sont en lecture seule tant qu'ils ne sont pas réservés : c'est ce qui évite que deux personnes modifient le même asset binaire en parallèle.

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

Option	Description
`--paths-file`	Lire des chemins supplémentaires depuis un fichier, un par ligne. Voir Listes de chemins volumineuses.
`--force`	Prend le verrou même s'il est détenu par quelqu'un d'autre. Réservé aux comptes qui détiennent la capacité `force_unlock`, c'est-à-dire aux rôles `admin` et `lead`. Voir ci-dessous.
`--add`	Autorise la réservation de chemins encore absents en local, pour de nouveaux fichiers.

Ce que fait vraiment --force

L'option prend le verrou de quelqu'un d'autre. Elle est gardée par la capacité force_unlock, détenue par les rôles admin et lead. Un compte qui ne l'a pas reçoit un refus explicite, avec le recours à suivre : le demander à un administrateur, ou utiliser le bouton « Demander la libération » du client desktop, qui prévient la personne concernée.

Quand un vol a effectivement eu lieu, il est inscrit au journal d'audit, avec les chemins concernés et le nom des personnes à qui les verrous ont été pris. Rien n'est écrit si l'option était présente mais qu'aucun verrou d'autrui n'a changé de main : dans les scripts, le drapeau est souvent systématique, et un journal rempli d'événements sans objet est un journal que personne ne relit.

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

# Fichier déjà réservé par bob
$ uversion checkout Content/Maps/MainLevel.umap
✗ File is locked (bob)

# Compte sans la capacité force_unlock
$ uversion checkout --force Content/Maps/MainLevel.umap
Error: Taking a lock held by another user requires the force_unlock capability
(admin or lead). Ask an administrator, or use Request Release to ask the holder.

# Compte admin ou lead : le vol passe, et il est tracé
$ uversion checkout --force Content/Maps/MainLevel.umap
✓ Lock acquired: Content/Maps/MainLevel.umap

`uversion checkin`

Envoie les fichiers modifiés et les valide sur le serveur en une seule transaction : soit tout passe, soit rien. Les verrous sont relâchés automatiquement en cas de succès.

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

Option	Description
`-m, --message`	Message de commit. Obligatoire.
`-a, --all`	Inclure tous les fichiers modifiés du workspace, pas seulement ceux passés en argument.
`--paths-file`	Lire des chemins supplémentaires depuis un fichier, un par ligne. Voir Listes de chemins volumineuses.

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`

Abandonne les changements locaux d'un ou plusieurs fichiers, restaure la version du serveur et relâche les verrous correspondants.

uversion revert <paths...> [--paths-file <fichier>] [--json]

Exemples :

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

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

Listes de chemins volumineuses : `--paths-file`

checkout, checkin et revert acceptent --paths-file <fichier> : un fichier texte contenant un chemin par ligne. Les chemins ainsi lus s'ajoutent à ceux passés en argument, ils ne les remplacent pas.

À quoi ça sert. Sur un projet Unreal, une opération porte couramment sur plusieurs milliers de fichiers. Les passer tous en arguments se heurte à une limite du système : sous Windows, une ligne de commande ne peut pas dépasser 32 767 caractères, ce qui représente environ 500 chemins d'asset. Au-delà, la commande échoue avant même d'avoir démarré, avec un message d'erreur du système qui ne dit rien du problème réel. --paths-file supprime cette limite : le fichier peut en contenir autant qu'il faut.

Réserver tous les fichiers modifiés d'un dossier, quel qu'en soit le nombre :

$ uversion status --json \
    | jq -r '.files[] | select(.status == "modified") | .path' > /tmp/changed.txt
$ wc -l /tmp/changed.txt
3184 /tmp/changed.txt

$ uversion checkout --paths-file /tmp/changed.txt

Puis envoyer exactement le même lot :

$ uversion checkin --paths-file /tmp/changed.txt -m "Import de la passe d'éclairage"

Sous Windows, en PowerShell :

PS> (uversion status --json | ConvertFrom-Json).files |
      Where-Object { $_.status -eq "modified" } |
      ForEach-Object { $_.path } |
      Set-Content -Encoding utf8 changed.txt

PS> uversion checkout --paths-file changed.txt

C'est également le mécanisme qu'emploie le plugin Rider pour transmettre un ensemble de modifications volumineux.

`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 précise d'un fichier sans toucher au workspace local. Utile pour comparer, archiver, ou récupérer un état passé sans faire de revert.

uversion content <path> [-r <numéro_de_révision>] [-o <fichier>]

--revision attend un nombre entier, pas une empreinte de commit

C'est le numéro de révision du fichier : un compteur qui vaut 1 à sa première version, 2 à la deuxième, et ainsi de suite. Passer une empreinte de commit comme 6e2b8a0 fait échouer la commande dès l'analyse des arguments.

Le numéro se lit dans uversion log --path <fichier>, où chaque ligne de fichier l'affiche entre parenthèses. Omettre --revision télécharge la dernière version.

Exemples :

$ uversion content Content/Maps/MainLevel.umap --revision 12 --output ./snapshot.umap

$ uversion content Content/Characters/Hero.uasset -r 8 -o ./hero-v8.uasset

# Sans --output, le contenu est écrit sur la sortie standard
$ uversion content Config/DefaultEngine.ini -r 3 > DefaultEngine-v3.ini

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...
Author: alice
Date:   2026-05-15 08:30:00 UTC

    Fixed lighting in main level

    Content/Maps/MainLevel.umap (rev 12)

commit 6e2b8a0...
Author: bob
Date:   2026-05-14 17:22:00 UTC

    Hero pose pass

    Content/Characters/Hero.uasset (rev 8)
    Content/Characters/OldHero.uasset (deleted, rev 9)

$ uversion log -n 5                                  # 5 derniers commits
$ uversion log --path Content/Maps/MainLevel.umap    # historique d'un fichier

Une ligne marquée deleted est une révision de suppression : elle porte un numéro comme les autres, mais n'a pas de contenu à télécharger.

Locks

Un verrou n'expire jamais

Il tient jusqu'à ce qu'il soit explicitement relâché : par uversion checkin, par uversion revert, par uversion lock release, ou par un déverrouillage forcé d'administrateur. Aucune expiration automatique n'existe, ni au bout d'une heure, ni au bout d'un mois. Un fichier réservé et oublié le reste jusqu'à ce que quelqu'un intervienne.

Par conséquent, uversion lock heartbeat ne prolonge rien. Cette commande dit seulement « ces verrous me servent encore », pour que les administrateurs distinguent un verrou actif d'un verrou abandonné.

`uversion lock list`

Affiche tous les verrous du dépôt 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

S'il n'y a rien à afficher, la commande écrit No active locks.

`uversion lock release`

Relâche un ou plusieurs verrous sans toucher au contenu local du fichier. À utiliser pour « rendre » un asset qu'on n'a pas modifié : réservé par erreur, ou travail abandonné sans envoi.

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

Exemples :

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

Cette commande ne relâche que vos propres verrous. Pour retirer celui de quelqu'un d'autre, il faut passer par l'administration, ou par uversion checkout --force si vous êtes admin ou lead.

`uversion lock heartbeat`

Signale que les verrous détenus par le compte courant sont toujours utilisés. Cela ne les prolonge pas : rien n'expire. C'est un signal de supervision, pour qu'un administrateur qui inspecte la liste des verrous voie lesquels sont encore actifs. Inutile dans le travail quotidien ; utile pour un traitement automatisé qui garde un fichier réservé pendant des heures.

$ uversion lock heartbeat
3 lock(s) extended

$ uversion lock heartbeat        # si vous ne détenez aucun verrou
No locks to extend

Exemple en intégration continue :

$ while build_in_progress; do
    uversion lock heartbeat
    sleep 300
  done

Info

`uversion info`

Affiche le compte utilisé et l'état du workspace courant. C'est la commande à lancer en premier quand quelque chose se comporte de façon inattendue : elle montre sous quelle identité le CLI agit réellement, qui est celle du propriétaire du workspace et non forcément celle de votre dernière connexion (voir Quel compte agit ?).

$ uversion info
User: alice (lead)

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

Hors d'un workspace, ou sans session valide :

$ uversion info
User: not logged in

Workspace: not in a uVersion workspace

La commande ne compte pas les fichiers et n'affiche pas de résumé des modifications : c'est le rôle de uversion status.

JSON output

Toutes les commandes sauf content acceptent --json, qui remplace l'affichage lisible par une sortie structurée. C'est ce qui rend le CLI scriptable.

Plusieurs commandes renvoient un tableau à la racine

log, lock list et repos produisent directement un tableau JSON, sans objet englobant. Il n'y a donc ni clé commits, ni clé locks, ni clé repositories : c'est .[] qu'il faut écrire dans jq, pas .commits[]. Une expression qui vise une clé inexistante ne produit rien du tout, sans message d'erreur.

Exemple : `uversion status --json`

{
  "files": [
    {
      "path": "Content/Maps/MainLevel.umap",
      "status": "locked",
      "locked_by": "alice",
      "is_owned": true,
      "version": 12
    },
    {
      "path": "Content/Textures/NewTexture.png",
      "status": "new",
      "locked_by": null,
      "is_owned": false,
      "version": 0
    }
  ],
  "summary": {
    "modified": 1,
    "new": 1,
    "deleted": 0,
    "locked_by_others": 0
  }
}

Les valeurs possibles de status :

Valeur	Signification
`modified`	Le fichier est modifiable sur disque, sans verrou posé
`locked`	Réservé par vous
`locked_other`	Réservé par quelqu'un d'autre, nommé dans `locked_by`
`new`	Présent en local, inconnu du serveur
`deleted`	Présent sur le serveur, absent en local
`tracked`	Suivi et intact. N'apparaît que si vous avez filtré par chemin

Notez que summary.modified additionne modified et locked, puisque les deux désignent un fichier sur lequel vous travaillez.

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

[
  {
    "commit_hash": "7f3a9b1c2d...",
    "message": "Fixed lighting in main level",
    "author": "alice",
    "created_at": "2026-05-15T08:30:00Z",
    "files": [
      {
        "path": "Content/Maps/MainLevel.umap",
        "revision_number": 12,
        "file_size": 84934656,
        "is_delete": false
      }
    ]
  }
]

Exemple : `uversion lock list --json`

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "file_id": 12345,
    "file_path": "Content/Maps/MainLevel.umap",
    "user_id": 12,
    "username": "alice",
    "acquired_at": "2026-05-15T08:42:11Z",
    "expires_at": "2126-05-15T08:42:11Z"
  }
]

L'échéance à 2126 n'est pas une coquille : la colonne ne peut pas rester vide en base, le serveur y écrit donc une valeur repoussée de cent ans. Les verrous n'expirent pas. N'affichez pas ce champ à un utilisateur et ne construisez rien dessus.

Gestion des erreurs

En cas d'échec, le CLI écrit Error: <message> sur la sortie d'erreur et se termine avec le code 1. Les erreurs ne sont jamais émises en JSON sur la sortie standard : avec --json, seul le résultat d'un succès est structuré. Dans un script, testez le code de sortie, pas le contenu de la sortie.

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 réservé quoi ?

lock list --json renvoie un tableau à la racine. On itère donc avec .[], et les champs sont username, file_path et acquired_at :

uversion lock list --json | jq -r '.[] | "\(.username)\t\(.file_path)\t\(.acquired_at)"'

Les fichiers réservés par une personne donnée :

uversion lock list --json | jq -r '.[] | select(.username == "bob") | .file_path'

Extraire les empreintes de commit

Là aussi le tableau est à la racine, et le champ s'appelle commit_hash :

uversion log --json -n 50 | jq -r '.[].commit_hash'

Les commits d'une personne, avec leur message :

uversion log --json -n 200 \
  | jq -r '.[] | select(.author == "alice") | "\(.commit_hash[0:8])  \(.message)"'

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

uversion content attend un numéro de révision, pas une empreinte de commit. Repérez-le dans l'historique du fichier, où il s'affiche entre parenthèses :

$ uversion log --path Content/Characters/Hero.uasset -n 10
commit 6e2b8a0...
Author: bob
Date:   2026-05-14 17:22:00 UTC

    Hero pose pass

    Content/Characters/Hero.uasset (rev 8)

$ uversion content Content/Characters/Hero.uasset --revision 8 --output ~/backup/Hero-v8.uasset

Ou en une fois, pour la dernière révision d'un fichier :

REV=$(uversion log --json --path Content/Characters/Hero.uasset -n 1 \
  | jq -r '.[0].files[] | select(.path == "Content/Characters/Hero.uasset") | .revision_number')
uversion content Content/Characters/Hero.uasset --revision "$REV" --output ./Hero.uasset

Build nocturne en intégration continue

Le mot de passe passe par UVERSION_PASSWORD, jamais par -p : la ligne de commande d'un processus est lisible par les autres comptes de la machine.

export UVERSION_PASSWORD="$SECRET_FROM_VAULT"
uversion login "$UV_SERVER" -u ci-nightly
unset UVERSION_PASSWORD

uversion clone hero-rpg ./project
cd project
uversion sync --json > sync.log

# Réserver un fichier pour la durée du cook, et signaler qu'il sert toujours
uversion checkout Content/Cooking/Distribution.uasset
( while pgrep RunUAT; do uversion lock heartbeat; sleep 300; done ) &

# ... build et cook ...

uversion lock release Content/Cooking/Distribution.uasset

Variables d'environnement & exit codes

Variables d'environnement

Variable	Description
`UVERSION_PASSWORD`	Mot de passe utilisé par `uversion login` quand l'option `-p` est absente. C'est la façon recommandée d'automatiser une connexion : contrairement à un argument de ligne de commande, une variable d'environnement n'est pas exposée aux autres comptes de la machine. Si elle est vide ou absente, le CLI demande le mot de passe de façon interactive.
`RUST_LOG`	Verbosité des journaux, écrits sur la sortie d'erreur. Par exemple `RUST_LOG=debug`. Niveau par défaut : `warn`.

Aucune variable UV_* n'est lue. Le serveur et le compte proviennent de .uversion/config.toml quand vous êtes dans un workspace, et sinon de la configuration partagée (%APPDATA%/uversion/uVersion/config/config.toml sous Windows). Le jeton de session vient du gestionnaire de mots de passe du système. Voir Quel compte agit ?.

Codes de sortie

Code	Signification
`0`	Succès. C'est aussi le code renvoyé par `--help` et par `--version`, qui ne sont pas des erreurs.
`1`	Toute erreur applicative : authentification, permission, réseau, serveur, écriture disque, hors workspace, conflit, validation. Le CLI ne distingue pas les causes par le code de sortie ; le détail est sur la sortie d'erreur.
`2`	Erreur d'analyse des arguments : option inconnue, valeur manquante, sous-commande invalide.

Exemple en script shell :

if ! uversion checkin --all -m "Nightly"; then
  echo "Checkin failed, see stderr"
  exit 1
fi

Installation

Cheatsheet : toutes les commandes

Authentication

uversion login

uversion logout

Quel compte agit ? Celui du workspace, pas le dernier connecté

Repositories

uversion repos

uversion clone

Files

uversion status

uversion checkout

uversion checkin

uversion revert

Listes de chemins volumineuses : --paths-file

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

Exemple : uversion lock list --json

Gestion des erreurs

Patterns courants

Onboarding d'un nouveau membre d'équipe

Workflow quotidien (artist / programmer)

Script d'audit : qui a réservé quoi ?

Extraire les empreintes de commit

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

Build nocturne en intégration continue

Variables d'environnement & exit codes

Variables d'environnement

Codes de sortie

`uversion login`

`uversion logout`

`uversion repos`

`uversion clone`

`uversion status`

`uversion checkout`

`uversion checkin`

`uversion revert`

Listes de chemins volumineuses : `--paths-file`

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

Exemple : `uversion lock list --json`