Wiki

CLI uversion

Referencia completa del CLI de uVersion: todos los comandos, flags, ejemplos, JSON output, exit codes.

El binario uversion cubre todas las operaciones de VCS disponibles en el cliente de escritorio, además de una salida --json legible por máquina para la automatización (CI/CD, scripts de onboarding, integración con herramientas de terceros). Todo el contenido de esta página está dirigido 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 elimina al desinstalar. Abra una nueva terminal y escriba:

uversion --help

En macOS es automático: en el primer arranque, 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). Inicie la aplicación una vez, abra una nueva terminal y el comando uversion estará disponible. Para hacerlo a mano en otra ubicación del PATH:

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

En Linux, la CLI aún no está incluida en los paquetes .deb / .AppImage. Compílela desde el código fuente si la necesita:

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

Para comprobar la versión instalada:

$ uversion --version

Cheatsheet: todos los comandos

El conjunto completo de comandos disponibles, en el orden en que se suelen encontrar:

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 archivos modificados / nuevos / eliminados / bloqueados
`uversion checkout <paths...>`	Bloquear archivos para edición
`uversion checkin <paths...> -m "..."`	Subir y hacer commit de los cambios
`uversion revert <paths...>`	Descartar los cambios locales, liberar los locks
`uversion sync`	Obtener los cambios del servidor (repo completo)
`uversion content <path> --revision <rev>`	Descargar una versión específica de un archivo
`uversion log`	Historial de commits
`uversion lock list`	Ver todos los locks activos del repo
`uversion lock release <paths...>`	Liberar un lock sin tocar el archivo
`uversion lock heartbeat`	Ampliar la caducidad de todos los locks retenidos (trabajos CI largos)
`uversion trust <url>`	Fijar la huella TLS autofirmada de un servidor (TOFU, interactivo; `--yes` para hacerlo con scripts)
`uversion mistrust <url>`	Eliminar la huella fijada de un servidor
`uversion trusted`	Listar los servidores con huella fijada

Todos los comandos (excepto uversion content) aceptan --json para producir una salida legible por máquina (véase JSON output). Todos los comandos también aceptan --help para los detalles de los flags.

Autenticación

`uversion login`

Se autentica en un servidor uVersion. El JWT devuelto se almacena en el keyring del sistema (Windows Credential Manager, macOS Keychain, libsecret en Linux) y se comparte con el cliente de escritorio y los plugins del editor.

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

Flag	Description
`-u, --username`	Nombre de usuario
`-p, --password`	Contraseña. Si se omite, aparece un prompt silencioso (sin eco)

Ejemplos:

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

Elimina el token del keyring del sistema. El siguiente comando que requiera autenticación volverá a pedir la contraseña.

$ uversion logout
✓ Credentials cleared

Repositorios

`uversion repos`

Lista los repositorios a los que tiene acceso el usuario actual.

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

Clona un repositorio localmente. Si se omite local_path, se crea una carpeta con el nombre del repo en el directorio de trabajo actual.

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 (sin seguimiento), 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`

Adquiere un lock exclusivo sobre los archivos indicados y los hace escribibles en disco.

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

Flag	Description
`--force`	Fuerza el checkout aunque el archivo esté bloqueado por otro usuario. Requiere la capacidad `force_unlock` (admin por defecto). Auditado.
`--add`	Permite el checkout de rutas que aún no existen localmente (archivos nuevos)

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

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

Sube los archivos modificados y hace commit en el servidor en una única transacción atómica. Los locks se liberan automáticamente tras el éxito.

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

Flag	Description
`-m, --message`	Mensaje de commit (obligatorio)
`-a, --all`	Incluir todos los archivos modificados del workspace, no solo los pasados como argumento

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`

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

uversion revert <paths...>

Ejemplos:

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

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

`uversion sync`

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

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

Flag	Description
`-f, --force`	Sync completo: vuelve a descargar todos los archivos, no solo el delta desde el último sync. Útil si el workspace está 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 específica de un archivo (por número de revisión) sin tocar el workspace local. Útil para comparar, archivar o recuperar un estado histórico sin hacer un revert.

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

Ejemplos:

$ 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

Historial

`uversion log`

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

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

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

Ejemplos:

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

Muestra todos los locks activos 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

3 locks active

`uversion lock release`

Libera manualmente uno o varios locks sin tocar el contenido local del archivo. Úselo cuando quiera «devolver» un asset sin haber hecho cambios (normalmente, lo ha hecho checkout por error o abandona el trabajo empezado sin enviarlo).

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

Ejemplos:

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

`uversion lock heartbeat`

Amplía la caducidad de todos los locks retenidos por el usuario actual. No es necesario para el flujo de trabajo normal; lo usan los trabajos de CI que retienen un lock durante mucho tiempo, para que los admins vean que el lock sigue activo.

uversion lock heartbeat

Ejemplo típico en CI:

$ while build_in_progress; do
    uversion lock heartbeat
    sleep 300
  done

Info

`uversion info`

Muestra la información del workspace actual, del usuario autenticado y del estado 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

Todos los comandos aceptan el flag --json para producir una salida legible por máquina en lugar de la visualización humana. Imprescindible para hacer scripts de la CLI en pipelines.

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

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

Gestión de errores

En caso de fallo, la CLI escribe Error: <message> en stderr y sale con el código 1. Los errores no se emiten como JSON en stdout: en modo --json, solo la salida de éxito está estructurada. En sus scripts, compruebe el código de salida (distinto de cero = fallo).

Patrones comunes

Onboarding 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 tiene qué bloqueado?

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

Recuperar un asset en una revisión pasada (sin tocar el 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 de entorno y exit codes

Variables de entorno

Variable	Description
`RUST_LOG`	Controla el nivel de detalle de los logs (escritos en stderr), p. ej. `RUST_LOG=debug`. Nivel por defecto: `warn`. Es la única variable de entorno que lee la CLI.

La URL del servidor y el nombre de usuario provienen de config.toml (%APPDATA%/uversion/uVersion/config/), el token del keyring del sistema: no se lee ninguna variable UV_*.

Exit codes

Código	Significado
`0`	Éxito
`1`	Cualquier error de aplicación (auth, permiso, red, servidor, IO, fuera del workspace, conflicto, validación…). La CLI no distingue los errores por código de salida.
`2`	Error de análisis de argumentos, `--help` o `--version` (convención clap)

Ejemplo de uso en un script bash:

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

Instalación

Cheatsheet: todos los comandos

Autenticación

uversion login

uversion logout

Repositorios

uversion repos

uversion clone

Archivos

uversion status

uversion checkout

uversion checkin

uversion revert

uversion sync

uversion content

Historial

uversion log

Locks

uversion lock list

uversion lock release

uversion lock heartbeat

Info

uversion info

JSON output

Ejemplo: uversion status --json

Ejemplo: uversion log --json -n 1

Gestión de errores

Patrones comunes

Onboarding de un nuevo miembro del equipo

Flujo de trabajo diario (artist / programmer)

Script de auditoría: ¿quién tiene qué bloqueado?

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

CI nightly build

Variables de entorno y exit codes

Variables de entorno

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`

Ejemplo: `uversion status --json`

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