Wiki

CLI uversion

Referencia completa de la CLI de uVersion: todos los comandos, flags, ejemplos, JSON output, códigos de salida.

El binario uversion cubre las mismas operaciones de control de versiones que el cliente de escritorio, y añade una salida --json aprovechable por un programa, para la automatización: integración continua, scripts de incorporación, herramientas propias. Esta página está dirigida a desarrolladores y administradores de estudio.

Instalación

En Windows, el binario uversion.exe se incluye en el instalador del cliente de escritorio y se añade automáticamente al PATH del usuario (%LOCALAPPDATA%\uVersion). La entrada del PATH se desduplica en cada actualización y se retira al desinstalar. Abra un nuevo terminal y escriba:

uversion --help

En macOS es automático: en el primer lanzamiento, el cliente de escritorio crea un enlace al binario incrustado en ~/.local/bin/uversion y se asegura de que esa carpeta esté en el PATH (mediante ~/.zprofile). Ejecute la aplicación una vez, abra un nuevo terminal, y el comando uversion estará disponible. Para hacerlo a mano hacia otra ubicación del PATH:

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

En Linux también es automático, exactamente igual que en macOS. El cliente de escritorio se distribuye como AppImage, y esa AppImage contiene el binario uversion. En el primer lanzamiento, la aplicación lo coloca en ~/.local/bin/uversion y se asegura de que esa carpeta esté en el PATH. Ejecute la aplicación una vez, abra un nuevo terminal, y el comando estará disponible:

uversion --help

No hay nada que compilar. En Linux, el cliente de escritorio se distribuye únicamente como AppImage, y es ella la que aporta la CLI. Para colocar el binario en otro lugar del PATH, cópielo desde ~/.local/bin:

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

Para comprobar la versión instalada:

$ uversion --version

Chuleta: todos los comandos

El conjunto de comandos disponibles, en el orden en que uno los encuentra habitualmente:

Comando	Qué hace
`uversion login <url> -u <user>`	Autenticarse en un servidor
`uversion logout`	Borrar las credenciales almacenadas
`uversion repos`	Listar los repositorios accesibles
`uversion clone <repo> [path]`	Clonar un repositorio
`uversion info`	Mostrar el estado del workspace + usuario actual
`uversion status [paths...]`	Ver los archivos modificados / nuevos / eliminados / bloqueados
`uversion checkout <paths...>`	Reservar archivos para edición (pone un bloqueo)
`uversion checkin <paths...> -m "..."`	Subir y confirmar los cambios
`uversion revert <paths...>`	Descartar los cambios locales y liberar los bloqueos
`uversion sync`	Recuperar los cambios desde el servidor (repositorio entero)
`uversion content <path> --revision <n>`	Descargar una versión concreta de un archivo
`uversion log`	Historial de commits
`uversion lock list`	Ver todos los bloqueos del repositorio
`uversion lock release <paths...>`	Liberar un bloqueo sin tocar el archivo
`uversion lock heartbeat`	Señalar que sus bloqueos siguen en uso (para la supervisión)
`uversion trust <url>`	Memorizar la huella del certificado autofirmado de un servidor (interactivo; `--yes` para automatizar)
`uversion mistrust <url>`	Olvidar la huella memorizada de un servidor
`uversion trusted`	Listar los servidores cuya huella está memorizada

Todos los comandos salvo uversion content aceptan --json, que reemplaza la visualización legible por una salida aprovechable por un programa (véase JSON output). Todos aceptan --help para el detalle de las opciones.

checkout, checkin y revert también aceptan --paths-file <fichier>, indispensable en cuanto se trabaja a la escala de un proyecto Unreal. Véase Listas de rutas voluminosas.

Autenticación

`uversion login`

Se autentica ante un servidor uVersion. El servidor entrega un token de sesión (un JWT, por JSON Web Token), que la CLI guarda en el gestor de contraseñas del sistema: el Administrador de credenciales en Windows, el Llavero en macOS, libsecret en Linux. Este token se comparte con el cliente de escritorio, el plugin de Unreal y el plugin de Rider: conectarse por un lado conecta a los demás, y desconectarse los desconecta a todos.

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

Opción	Descripción
`-u, --username`	Nombre de usuario
`-p, --password`	Desaconsejado. Véase el recuadro más abajo. Si se omite la opción, la CLI lee la variable de entorno `UVERSION_PASSWORD`, y en su defecto pide la contraseña de forma interactiva, sin eco en pantalla.

Para automatizar una conexión, use UVERSION_PASSWORD, nunca -p

En un sistema multiusuario, la línea de comandos de cada proceso es legible por las demás cuentas de la máquina: ps en Linux y macOS, el Administrador de tareas o wmic en Windows. Una contraseña pasada como argumento aparece allí en texto claro, incluso si proviene de una variable, ya que la shell la reemplaza por su valor antes de lanzar el programa. También acaba en el historial de la shell y a menudo en los registros de la cadena de integración continua.

La CLI lee UVERSION_PASSWORD precisamente para evitar esto, y muestra una advertencia en la salida de error cuando se emplea -p.

Ejemplos:

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

En la primera conexión a un servidor que presenta un certificado autofirmado, la CLI muestra la huella del certificado y le pide que la confirme, luego la memoriza. Es el principio de la confianza en el primer contacto, el mismo que SSH: se acepta una identidad una vez, y toda presentación posterior de una identidad diferente se señala. Si la huella cambia, la CLI rechaza la conexión y le avisa: es o bien una renovación legítima del certificado, o bien una interceptación de su tráfico por un tercero. La maniobra deliberada es entonces uversion mistrust <url>, seguida de una nueva conexión.

`uversion logout`

Borra el token del gestor de contraseñas del sistema e invalida en el servidor todas las sesiones de esta cuenta. Como el token se comparte, esto también desconecta el cliente de escritorio, el plugin de Unreal y el plugin de Rider, en todas sus máquinas.

$ uversion logout
Logged out (alice)

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

¿Qué cuenta actúa? La del workspace, no la última conectada

Es el punto que más sorprende, y conviene conocerlo antes de automatizar nada: la identidad utilizada no es la de la última conexión, es la del workspace en el que se encuentra.

Un workspace es una carpeta clonada, reconocible por su subcarpeta .uversion. El archivo .uversion/config.toml registra allí el servidor y la cuenta propietaria:

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

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

En cuanto está en un workspace, server_url y owner mandan: status, checkout, checkin, revert, sync, log, content, lock e info se autentican como owner, contra server_url.

Solo login, logout, repos y clone usan la configuración compartida entre todos los workspaces (en Windows %APPDATA%/uversion/uVersion/config/config.toml), que sigue a la cuenta activa del cliente de escritorio.

Por qué. Un mismo equipo sirve a menudo a varias cuentas, por ejemplo un freelance que trabaja para dos estudios. Sin esta regla, todos los workspaces actuarían bajo la cuenta activa del momento: una carpeta clonada por alice pero usada mientras bob está activo pondría sus bloqueos en nombre de bob, vería sus propios archivos como «bloqueados por otra persona», y vería rechazados sus envíos.

Para cambiar la identidad de un workspace, modifique el campo owner en .uversion/config.toml, y asegúrese de que esa cuenta se haya conectado al menos una vez en esta máquina (uversion login), para que su token esté presente. Compruebe luego con uversion info, que muestra la cuenta realmente utilizada.

Límite conocido: un mismo nombre de usuario en dos servidores

El token se guarda bajo el solo nombre de usuario, sin el servidor. Si el mismo nombre existe en dos servidores uVersion diferentes, ambos comparten una única y misma entrada: conectarse al segundo reemplaza el token del primero. Use nombres distintos, o emplee un solo servidor a la vez desde una misma máquina.

Repositorios

`uversion repos`

Lista los repositorios a los que la cuenta tiene acceso. Este comando usa la configuración compartida, no la de un workspace: responde, por tanto, por la cuenta de su última conexión.

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

Recupera un repositorio en local. Si se omite la ruta, se crea una carpeta con el nombre del repositorio en el directorio actual. El clon crea también la subcarpeta .uversion, que convierte la carpeta en un workspace y registra el servidor y la cuenta propietaria.

La transferencia aplica la deduplicación: el contenido se divide en bloques, y un bloque ya presente se almacena una sola vez, aunque aparezca en varios archivos. Por eso el espacio ocupado en disco suele ser bastante menor que el volumen descargado.

uversion clone <repo_name_or_id> [local_path]

Ejemplos:

$ 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

Archivos

`uversion status`

Muestra el estado de los archivos del workspace actual: modificados, nuevos (untracked), eliminados, bloqueados por otros.

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

Ejemplos:

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

Pone un bloqueo exclusivo sobre los archivos indicados y los hace modificables en disco. Los archivos rastreados son de solo lectura mientras no estén reservados: es lo que evita que dos personas modifiquen el mismo asset binario en paralelo.

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

Opción	Descripción
`--paths-file`	Leer rutas adicionales desde un archivo, una por línea. Véase Listas de rutas voluminosas.
`--force`	Toma el bloqueo aunque lo tenga otra persona. Reservado a las cuentas que poseen la capacidad `force_unlock`, es decir, los roles `admin` y `lead`. Véase más abajo.
`--add`	Autoriza la reserva de rutas aún ausentes en local, para archivos nuevos.

Lo que hace realmente --force

La opción toma el bloqueo de otra persona. Está protegida por la capacidad force_unlock, que poseen los roles admin y lead. Una cuenta que no la tiene recibe un rechazo explícito, con el recurso a seguir: pedírselo a un administrador, o usar el botón «Solicitar la liberación» del cliente de escritorio, que avisa a la persona afectada.

Cuando un robo ha tenido lugar efectivamente, queda registrado en el diario de auditoría, con las rutas afectadas y el nombre de las personas a quienes se les quitaron los bloqueos. No se escribe nada si la opción estaba presente pero ningún bloqueo ajeno cambió de manos: en los scripts, la bandera suele ser sistemática, y un diario lleno de eventos sin objeto es un diario que nadie relee.

Ejemplos:

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

Sube los archivos modificados y los confirma en el servidor en una sola transacción: o pasa todo, o nada. Los bloqueos se liberan automáticamente en caso de éxito.

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

Opción	Descripción
`-m, --message`	Mensaje de commit. Obligatorio.
`-a, --all`	Incluir todos los archivos modificados del workspace, no solo los pasados como argumento.
`--paths-file`	Leer rutas adicionales desde un archivo, una por línea. Véase Listas de rutas voluminosas.

Ejemplos:

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

Abandona los cambios locales de uno o varios archivos, restaura la versión del servidor y libera los bloqueos correspondientes.

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

Ejemplos:

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

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

Listas de rutas voluminosas: `--paths-file`

checkout, checkin y revert aceptan --paths-file <fichier>: un archivo de texto que contiene una ruta por línea. Las rutas así leídas se añaden a las pasadas como argumento, no las reemplazan.

Para qué sirve. En un proyecto Unreal, una operación abarca habitualmente varios miles de archivos. Pasarlos todos como argumentos choca con un límite del sistema: en Windows, una línea de comandos no puede superar los 32 767 caracteres, lo que representa unas 500 rutas de asset. Más allá, el comando falla incluso antes de arrancar, con un mensaje de error del sistema que no dice nada del problema real. --paths-file elimina este límite: el archivo puede contener tantas como haga falta.

Reservar todos los archivos modificados de una carpeta, sean cuantos sean:

$ 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

Luego enviar exactamente el mismo lote:

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

En Windows, con 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

Es también el mecanismo que emplea el plugin de Rider para transmitir un conjunto de modificaciones voluminoso.

`uversion sync`

Descarga los últimos cambios desde el servidor y los aplica al workspace local.

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

Flag	Descripción
`-f, --force`	Sync completo: vuelve a descargar todos los archivos, no solo el delta desde el último sync. Útil en caso de workspace corrupto.

Ejemplos:

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

Descarga una versión concreta de un archivo sin tocar el workspace local. Útil para comparar, archivar, o recuperar un estado pasado sin hacer un revert.

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

--revision espera un número entero, no una huella de commit

Es el número de revisión del archivo: un contador que vale 1 en su primera versión, 2 en la segunda, y así sucesivamente. Pasar una huella de commit como 6e2b8a0 hace fallar el comando ya en el análisis de los argumentos.

El número se lee en uversion log --path <fichier>, donde cada línea de archivo lo muestra entre paréntesis. Omitir --revision descarga la última versión.

Ejemplos:

$ 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

Historial

`uversion log`

Historial de commits del repositorio actual, opcionalmente filtrado por archivo.

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

Flag	Descripción
`-n, --limit`	Número de entradas a mostrar (por defecto: 20)
`-p, --path`	Filtra por ruta de archivo

Ejemplos:

$ 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

Una línea marcada como deleted es una revisión de eliminación: lleva un número como las demás, pero no tiene contenido que descargar.

Bloqueos

Un bloqueo nunca caduca

Se mantiene hasta que se libera explícitamente: mediante uversion checkin, mediante uversion revert, mediante uversion lock release, o mediante un desbloqueo forzado de administrador. No existe ninguna caducidad automática, ni al cabo de una hora, ni al cabo de un mes. Un archivo reservado y olvidado lo sigue estando hasta que alguien interviene.

Por consiguiente, uversion lock heartbeat no prolonga nada. Este comando solo dice «estos bloqueos aún me sirven», para que los administradores distingan un bloqueo activo de uno abandonado.

`uversion lock list`

Muestra todos los bloqueos del repositorio actual.

uversion lock list [--json]

Ejemplos:

$ 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

Si no hay nada que mostrar, el comando escribe No active locks.

`uversion lock release`

Libera uno o varios bloqueos sin tocar el contenido local del archivo. A usar para «devolver» un asset que no se ha modificado: reservado por error, o trabajo abandonado sin envío.

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

Ejemplos:

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

Este comando solo libera sus propios bloqueos. Para retirar el de otra persona, hay que pasar por la administración, o por uversion checkout --force si es admin o lead.

`uversion lock heartbeat`

Señala que los bloqueos que tiene la cuenta actual siguen en uso. Esto no los prolonga: nada caduca. Es una señal de supervisión, para que un administrador que inspecciona la lista de bloqueos vea cuáles siguen activos. Inútil en el trabajo diario; útil para un tratamiento automatizado que mantiene un archivo reservado durante horas.

$ uversion lock heartbeat
3 lock(s) extended

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

Ejemplo en integración continua:

$ while build_in_progress; do
    uversion lock heartbeat
    sleep 300
  done

Info

`uversion info`

Muestra la cuenta utilizada y el estado del workspace actual. Es el comando que hay que lanzar primero cuando algo se comporta de forma inesperada: muestra bajo qué identidad actúa realmente la CLI, que es la del propietario del workspace y no forzosamente la de su última conexión (véase ¿Qué cuenta actúa?).

$ 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

Fuera de un workspace, o sin sesión válida:

$ uversion info
User: not logged in

Workspace: not in a uVersion workspace

El comando no cuenta los archivos ni muestra un resumen de las modificaciones: ese es el papel de uversion status.

JSON output

Todos los comandos salvo content aceptan --json, que reemplaza la visualización legible por una salida estructurada. Es lo que hace la CLI automatizable.

Varios comandos devuelven un array en la raíz

log, lock list y repos producen directamente un array JSON, sin objeto envolvente. No hay, por tanto, ni clave commits, ni clave locks, ni clave repositories: es .[] lo que hay que escribir en jq, no .commits[]. Una expresión que apunta a una clave inexistente no produce nada en absoluto, sin mensaje de error.

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

Los valores posibles de status:

Valor	Significado
`modified`	El archivo es modificable en disco, sin bloqueo puesto
`locked`	Reservado por usted
`locked_other`	Reservado por otra persona, nombrada en `locked_by`
`new`	Presente en local, desconocido para el servidor
`deleted`	Presente en el servidor, ausente en local
`tracked`	Rastreado e intacto. Solo aparece si ha filtrado por ruta

Observe que summary.modified suma modified y locked, ya que ambos designan un archivo en el que está trabajando.

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

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

El vencimiento en 2126 no es una errata: la columna no puede quedar vacía en la base de datos, así que el servidor escribe un valor empujado cien años hacia adelante. Los bloqueos no caducan. No muestre este campo a un usuario ni construya nada sobre él.

Gestión de errores

En caso de fallo, la CLI escribe Error: <message> en la salida de error y termina con el código 1. Los errores nunca se emiten en JSON en la salida estándar: con --json, solo el resultado de un éxito es estructurado. En un script, pruebe el código de salida, no el contenido de la salida.

Patrones habituales

Incorporación de un nuevo miembro del equipo

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

Flujo de trabajo diario (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 de auditoría: ¿quién ha reservado qué?

lock list --json devuelve un array en la raíz. Se itera, pues, con .[], y los campos son username, file_path y acquired_at:

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

Los archivos reservados por una persona dada:

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

Extraer las huellas de commit

También aquí el array está en la raíz, y el campo se llama commit_hash:

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

Los commits de una persona, con su mensaje:

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

Recuperar un asset en una revisión pasada, sin tocar el workspace

uversion content espera un número de revisión, no una huella de commit. Localícelo en el historial del archivo, donde se muestra entre paréntesis:

$ 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

O de una vez, para la última revisión de un archivo:

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 nocturno en integración continua

La contraseña pasa por UVERSION_PASSWORD, nunca por -p: la línea de comandos de un proceso es legible por las demás cuentas de la máquina.

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 de entorno y códigos de salida

Variables de entorno

Variable	Descripción
`UVERSION_PASSWORD`	Contraseña utilizada por `uversion login` cuando la opción `-p` está ausente. Es la manera recomendada de automatizar una conexión: a diferencia de un argumento de línea de comandos, una variable de entorno no queda expuesta a las demás cuentas de la máquina. Si está vacía o ausente, la CLI pide la contraseña de forma interactiva.
`RUST_LOG`	Verbosidad de los registros, escritos en la salida de error. Por ejemplo `RUST_LOG=debug`. Nivel por defecto: `warn`.

No se lee ninguna variable UV_*. El servidor y la cuenta provienen de .uversion/config.toml cuando está en un workspace, y si no de la configuración compartida (en Windows %APPDATA%/uversion/uVersion/config/config.toml). El token de sesión proviene del gestor de contraseñas del sistema. Véase ¿Qué cuenta actúa?.

Códigos de salida

Código	Significado
`0`	Éxito. Es también el código que devuelven `--help` y `--version`, que no son errores.
`1`	Cualquier error de aplicación: autenticación, permiso, red, servidor, escritura en disco, fuera de workspace, conflicto, validación. La CLI no distingue las causas por el código de salida; el detalle está en la salida de error.
`2`	Error de análisis de los argumentos: opción desconocida, valor faltante, subcomando inválido.

Ejemplo en script de shell:

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

Instalación

Chuleta: todos los comandos

Autenticación

uversion login

uversion logout

¿Qué cuenta actúa? La del workspace, no la última conectada

Repositorios

uversion repos

uversion clone

Archivos

uversion status

uversion checkout

uversion checkin

uversion revert

Listas de rutas voluminosas: --paths-file

uversion sync

uversion content

Historial

uversion log

Bloqueos

uversion lock list

uversion lock release

uversion lock heartbeat

Info

uversion info

JSON output

Ejemplo: uversion status --json

Ejemplo: uversion log --json -n 1

Ejemplo: uversion lock list --json

Gestión de errores

Patrones habituales

Incorporación de un nuevo miembro del equipo

Flujo de trabajo diario (artist / programmer)

Script de auditoría: ¿quién ha reservado qué?

Extraer las huellas de commit

Recuperar un asset en una revisión pasada, sin tocar el workspace

Build nocturno en integración continua

Variables de entorno y códigos de salida

Variables de entorno

Códigos de salida

`uversion login`

`uversion logout`

`uversion repos`

`uversion clone`

`uversion status`

`uversion checkout`

`uversion checkin`

`uversion revert`

Listas de rutas voluminosas: `--paths-file`

`uversion sync`

`uversion content`

`uversion log`

`uversion lock list`

`uversion lock release`

`uversion lock heartbeat`

`uversion info`

Ejemplo: `uversion status --json`

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

Ejemplo: `uversion lock list --json`