Wiki

CLI uversion

Riferimento completo della CLI di uVersion: tutti i comandi, flag, esempi, JSON output, exit code.

Il binario uversion copre tutte le operazioni VCS disponibili nel client desktop, oltre a un output --json leggibile dalle macchine per l'automazione (CI/CD, script di onboarding, integrazione con strumenti di terze parti). Tutti i contenuti di questa pagina sono destinati agli sviluppatori e agli amministratori di studio.

Installazione

Su Windows, il binario uversion.exe è incluso nell'installer del client desktop e viene aggiunto automaticamente al PATH utente (%LOCALAPPDATA%\uVersion). La voce del PATH viene deduplicata a ogni aggiornamento e rimossa alla disinstallazione. Apri un nuovo terminale e digita:

uversion --help

Su macOS è automatico: al primo avvio, il client desktop crea un collegamento al binario incorporato in ~/.local/bin/uversion e si assicura che quella cartella sia nel PATH (tramite ~/.zprofile). Avvia l'app una volta, apri un nuovo terminale e il comando uversion sarà disponibile. Per farlo manualmente in un'altra posizione del PATH:

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

Su Linux, la CLI non è ancora inclusa nei pacchetti .deb / .AppImage. Compilala dai sorgenti se ti serve:

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

Per verificare la versione installata:

$ uversion --version

Cheatsheet: tutti i comandi

L'insieme completo dei comandi disponibili, nell'ordine in cui si incontrano tipicamente:

Comando	Cosa fa
`uversion login <url> -u <user>`	Autenticarsi su un server
`uversion logout`	Cancellare le credenziali memorizzate
`uversion repos`	Elencare i repository accessibili
`uversion clone <repo> [path]`	Clonare un repository
`uversion info`	Mostrare lo stato del workspace + utente corrente
`uversion status [paths...]`	Vedere i file modificati / nuovi / eliminati / bloccati
`uversion checkout <paths...>`	Bloccare i file per la modifica
`uversion checkin <paths...> -m "..."`	Caricare ed eseguire il commit delle modifiche
`uversion revert <paths...>`	Annullare le modifiche locali, rilasciare i lock
`uversion sync`	Recuperare le modifiche dal server (intero repo)
`uversion content <path> --revision <rev>`	Scaricare una versione specifica di un file
`uversion log`	Cronologia dei commit
`uversion lock list`	Vedere tutti i lock attivi del repo
`uversion lock release <paths...>`	Rilasciare un lock senza toccare il file
`uversion lock heartbeat`	Estendere la scadenza di tutti i lock detenuti (job CI lunghi)
`uversion trust <url>`	Fissare l'impronta TLS autofirmata di un server (TOFU, interattivo; `--yes` per gli script)
`uversion mistrust <url>`	Rimuovere l'impronta fissata di un server
`uversion trusted`	Elencare i server con impronta fissata

Tutti i comandi (tranne uversion content) accettano --json per produrre un output leggibile dalle macchine (vedi JSON output). Tutti i comandi accettano anche --help per i dettagli dei flag.

Autenticazione

`uversion login`

Si autentica su un server uVersion. Il JWT restituito viene memorizzato nel keyring di sistema (Windows Credential Manager, macOS Keychain, libsecret su Linux) e condiviso con il client desktop e i plugin dell'editor.

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

Flag	Description
`-u, --username`	Nome utente
`-p, --password`	Password. Se omessa, un prompt silenzioso (senza eco)

Esempi:

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

Rimuove il token dal keyring di sistema. Il prossimo comando che richiede l'autenticazione chiederà di nuovo la password.

$ uversion logout
✓ Credentials cleared

Repository

`uversion repos`

Elenca i repository a cui l'utente corrente ha accesso.

$ 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 repository localmente. Se local_path viene omesso, viene creata una cartella con il nome del repo nella directory di lavoro corrente.

uversion clone <repo_name_or_id> [local_path]

Esempi:

$ 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

File

`uversion status`

Mostra lo stato dei file del workspace corrente: modificati, nuovi (non tracciati), eliminati, bloccati da altri.

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

Esempi:

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

Acquisisce un lock esclusivo sui file target e li rende scrivibili su disco.

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

Flag	Description
`--force`	Forza il checkout anche se il file è bloccato da un altro utente. Richiede la capability `force_unlock` (admin per impostazione predefinita). Registrato nell'audit.
`--add`	Consente il checkout di percorsi non ancora presenti localmente (nuovi file)

Esempi:

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

Carica i file modificati e ne esegue il commit sul server in un'unica transazione atomica. I lock vengono rilasciati automaticamente al successo.

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

Flag	Description
`-m, --message`	Messaggio di commit (obbligatorio)
`-a, --all`	Includere tutti i file modificati nel workspace, non solo quelli passati come argomento

Esempi:

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

Scarta le modifiche locali di uno o più file, ripristina la versione del server, rilascia i lock corrispondenti.

uversion revert <paths...>

Esempi:

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

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

`uversion sync`

Scarica le ultime modifiche dal server e le applica al workspace locale.

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

Flag	Description
`-f, --force`	Sync completo: riscarica tutti i file, non solo il delta dall'ultimo sync. Utile in caso di workspace corrotto.

Esempi:

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

Scarica una versione specifica di un file (per numero di revisione) senza toccare il workspace locale. Utile per confrontare, archiviare o recuperare uno stato storico senza eseguire un revert.

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

Esempi:

$ 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

Cronologia

`uversion log`

Cronologia dei commit del repository corrente, opzionalmente filtrata per file.

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

Flag	Description
`-n, --limit`	Numero di voci da visualizzare (predefinito: 20)
`-p, --path`	Filtra per percorso di file

Esempi:

$ 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

Lock

`uversion lock list`

Mostra tutti i lock attivi nel repository corrente.

uversion lock list [--json]

Esempi:

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

Rilascia manualmente uno o più lock senza toccare il contenuto locale del file. Da usare quando vuoi «restituire» un asset senza aver fatto modifiche (in genere, l'hai fatto checkout per errore o abbandoni un lavoro iniziato senza inviarlo).

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

Esempi:

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

`uversion lock heartbeat`

Estende la scadenza di tutti i lock detenuti dall'utente corrente. Non necessario per il flusso di lavoro normale; usato dai job CI che mantengono un lock a lungo, così che gli admin vedano che il lock è ancora attivo.

uversion lock heartbeat

Esempio tipico in CI:

$ while build_in_progress; do
    uversion lock heartbeat
    sleep 300
  done

Info

`uversion info`

Mostra le informazioni del workspace corrente, dell'utente autenticato e dello stato di 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

Tutti i comandi accettano il flag --json per produrre un output leggibile dalle macchine invece della visualizzazione umana. Indispensabile per scriptare la CLI nelle pipeline.

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

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

Gestione degli errori

In caso di errore, la CLI scrive Error: <message> su stderr ed esce con codice 1. Gli errori non vengono emessi come JSON su stdout: in modalità --json, solo l'output di successo è strutturato. Nei tuoi script, verifica il codice di uscita (diverso da zero = errore).

Pattern comuni

Onboarding di un nuovo membro del team

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

Flusso di lavoro quotidiano (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 di audit: chi ha bloccato cosa?

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

Recuperare un asset a una revisione passata (senza toccare il 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

Variabili d'ambiente & exit code

Variabili d'ambiente

Variable	Description
`RUST_LOG`	Controlla la verbosità dei log (scritti su stderr), es. `RUST_LOG=debug`. Livello predefinito: `warn`. È l'unica variabile d'ambiente letta dalla CLI.

L'URL del server e il nome utente provengono da config.toml (%APPDATA%/uversion/uVersion/config/), il token dal keyring di sistema: nessuna variabile UV_* viene letta.

Exit code

Codice	Significato
`0`	Successo
`1`	Qualsiasi errore applicativo (auth, permessi, rete, server, IO, fuori dal workspace, conflitto, validazione…). La CLI non distingue gli errori per codice di uscita.
`2`	Errore di analisi degli argomenti, `--help` o `--version` (convenzione clap)

Esempio di utilizzo in uno script bash:

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

Installazione

Cheatsheet: tutti i comandi

Autenticazione

uversion login

uversion logout

Repository

uversion repos

uversion clone

File

uversion status

uversion checkout

uversion checkin

uversion revert

uversion sync

uversion content

Cronologia

uversion log

Lock

uversion lock list

uversion lock release

uversion lock heartbeat

Info

uversion info

JSON output

Esempio: uversion status --json

Esempio: uversion log --json -n 1

Gestione degli errori

Pattern comuni

Onboarding di un nuovo membro del team

Flusso di lavoro quotidiano (artist / programmer)

Script di audit: chi ha bloccato cosa?

Recuperare un asset a una revisione passata (senza toccare il workspace)

CI nightly build

Variabili d'ambiente & exit code

Variabili d'ambiente

Exit code

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

Esempio: `uversion status --json`

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