Wiki

CLI uversion

Referência completa do CLI do uVersion: todos os comandos, flags, exemplos, JSON output, exit codes.

O binário uversion cobre todas as operações de VCS disponíveis no cliente desktop, além de uma saída --json legível por máquina para automação (CI/CD, scripts de onboarding, integração com ferramentas de terceiros). Todo o conteúdo desta página é destinado a desenvolvedores e admins de estúdio.

Instalação

No Windows, o binário uversion.exe vem no instalador do cliente desktop e é adicionado automaticamente ao PATH do usuário (%LOCALAPPDATA%\uVersion). A entrada do PATH é desduplicada a cada atualização e removida na desinstalação. Abra um novo terminal e digite:

uversion --help

No macOS, é automático: no primeiro início, o cliente desktop cria um link para o binário embutido em ~/.local/bin/uversion e garante que essa pasta esteja no PATH (via ~/.zprofile). Inicie o aplicativo uma vez, abra um novo terminal e o comando uversion estará disponível. Para fazê-lo manualmente em outro local do PATH:

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

No Linux, a CLI ainda não vem incluída nos pacotes .deb / .AppImage. Compile-a a partir do código-fonte se precisar:

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

Para verificar a versão instalada:

$ uversion --version

Cheatsheet: todos os comandos

O conjunto completo de comandos disponíveis, na ordem em que costumam aparecer:

Comando	O que faz
`uversion login <url> -u <user>`	Autenticar em um servidor
`uversion logout`	Limpar as credenciais armazenadas
`uversion repos`	Listar os repositórios acessíveis
`uversion clone <repo> [path]`	Clonar um repositório
`uversion info`	Mostrar o estado do workspace + usuário atual
`uversion status [paths...]`	Ver arquivos modificados / novos / excluídos / bloqueados
`uversion checkout <paths...>`	Bloquear arquivos para edição
`uversion checkin <paths...> -m "..."`	Enviar e fazer commit das alterações
`uversion revert <paths...>`	Descartar as alterações locais, liberar os locks
`uversion sync`	Buscar as alterações do servidor (repo inteiro)
`uversion content <path> --revision <rev>`	Baixar uma versão específica de um arquivo
`uversion log`	Histórico de commits
`uversion lock list`	Ver todos os locks ativos do repo
`uversion lock release <paths...>`	Liberar um lock sem tocar no arquivo
`uversion lock heartbeat`	Estender a expiração de todos os locks retidos (jobs de CI longos)
`uversion trust <url>`	Fixar a impressão digital TLS autoassinada de um servidor (TOFU, interativo; `--yes` para usar em scripts)
`uversion mistrust <url>`	Remover a impressão digital fixada de um servidor
`uversion trusted`	Listar os servidores com impressão digital fixada

Todos os comandos (exceto uversion content) aceitam --json para produzir uma saída legível por máquina (veja JSON output). Todos os comandos também aceitam --help para os detalhes das flags.

Autenticação

`uversion login`

Autentica em um servidor uVersion. O JWT retornado é armazenado no keyring do sistema (Windows Credential Manager, macOS Keychain, libsecret no Linux) e compartilhado com o cliente desktop e os plugins do editor.

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

Flag	Description
`-u, --username`	Nome de usuário
`-p, --password`	Senha. Se omitida, um prompt silencioso (sem eco)

Exemplos:

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

Remove o token do keyring do sistema. O próximo comando que exigir autenticação pedirá a senha novamente.

$ uversion logout
✓ Credentials cleared

Repositórios

`uversion repos`

Lista os repositórios aos quais o usuário atual tem acesso.

$ 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 um repositório localmente. Se local_path for omitido, uma pasta com o nome do repo é criada no diretório de trabalho atual.

uversion clone <repo_name_or_id> [local_path]

Exemplos:

$ 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

Arquivos

`uversion status`

Mostra o estado dos arquivos do workspace atual: modificados, novos (não rastreados), excluídos, bloqueados por outros.

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

Exemplos:

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

Adquire um lock exclusivo sobre os arquivos alvo e os torna graváveis em disco.

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

Flag	Description
`--force`	Força o checkout mesmo que o arquivo esteja bloqueado por outro usuário. Requer a capacidade `force_unlock` (admin por padrão). Auditado.
`--add`	Permite o checkout de caminhos ainda não presentes localmente (arquivos novos)

Exemplos:

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

Envia os arquivos modificados e faz commit no servidor em uma única transação atômica. Os locks são liberados automaticamente após o sucesso.

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

Flag	Description
`-m, --message`	Mensagem de commit (obrigatória)
`-a, --all`	Incluir todos os arquivos modificados do workspace, não apenas os passados como argumento

Exemplos:

$ 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 as alterações locais de um ou mais arquivos, restaura a versão do servidor e libera os locks correspondentes.

uversion revert <paths...>

Exemplos:

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

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

`uversion sync`

Baixa as últimas alterações do servidor e as aplica ao workspace local.

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

Flag	Description
`-f, --force`	Sync completo: baixa novamente todos os arquivos, não apenas o delta desde o último sync. Útil em caso de workspace corrompido.

Exemplos:

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

Baixa uma versão específica de um arquivo (por número de revisão) sem tocar no workspace local. Útil para comparar, arquivar ou recuperar um estado histórico sem fazer um revert.

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

Exemplos:

$ 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

Histórico

`uversion log`

Histórico de commits do repositório atual, opcionalmente filtrado por arquivo.

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

Flag	Description
`-n, --limit`	Número de entradas a exibir (padrão: 20)
`-p, --path`	Filtrar por caminho de arquivo

Exemplos:

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

Mostra todos os locks ativos no repositório atual.

uversion lock list [--json]

Exemplos:

$ 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 um ou mais locks sem tocar no conteúdo local do arquivo. Use quando quiser «devolver» um asset sem ter feito alterações (normalmente, você fez checkout por engano ou está abandonando um trabalho começado sem enviar).

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

Exemplos:

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

`uversion lock heartbeat`

Estende a expiração de todos os locks retidos pelo usuário atual. Não é necessário para o fluxo de trabalho normal; usado por jobs de CI que mantêm um lock por muito tempo, para que os admins vejam que o lock ainda está ativo.

uversion lock heartbeat

Exemplo típico em CI:

$ while build_in_progress; do
    uversion lock heartbeat
    sleep 300
  done

Info

`uversion info`

Mostra as informações do workspace atual, do usuário autenticado e do 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 os comandos aceitam a flag --json para produzir uma saída legível por máquina em vez da exibição humana. Indispensável para criar scripts da CLI em pipelines.

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

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

Tratamento de erros

Em caso de falha, a CLI escreve Error: <message> no stderr e sai com o código 1. Os erros não são emitidos como JSON no stdout: no modo --json, apenas a saída de sucesso é estruturada. Em seus scripts, teste o código de saída (diferente de zero = falha).

Padrões comuns

Onboarding de um novo membro da equipe

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

Fluxo de trabalho diário (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 auditoria: quem tem o quê bloqueado?

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

Recuperar um asset em uma revisão passada (sem tocar no 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

Variáveis de ambiente e exit codes

Variáveis de ambiente

Variable	Description
`RUST_LOG`	Controla o nível de detalhe dos logs (escritos no stderr), ex. `RUST_LOG=debug`. Nível padrão: `warn`. É a única variável de ambiente lida pela CLI.

A URL do servidor e o nome de usuário vêm de config.toml (%APPDATA%/uversion/uVersion/config/), o token do keyring do sistema: nenhuma variável UV_* é lida.

Exit codes

Código	Significado
`0`	Sucesso
`1`	Qualquer erro de aplicação (auth, permissão, rede, servidor, IO, fora do workspace, conflito, validação…). A CLI não distingue os erros por código de saída.
`2`	Erro de análise dos argumentos, `--help` ou `--version` (convenção clap)

Exemplo de uso em um script bash:

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

Instalação

Cheatsheet: todos os comandos

Autenticação

uversion login

uversion logout

Repositórios

uversion repos

uversion clone

Arquivos

uversion status

uversion checkout

uversion checkin

uversion revert

uversion sync

uversion content

Histórico

uversion log

Locks

uversion lock list

uversion lock release

uversion lock heartbeat

Info

uversion info

JSON output

Exemplo: uversion status --json

Exemplo: uversion log --json -n 1

Tratamento de erros

Padrões comuns

Onboarding de um novo membro da equipe

Fluxo de trabalho diário (artist / programmer)

Script de auditoria: quem tem o quê bloqueado?

Recuperar um asset em uma revisão passada (sem tocar no workspace)

CI nightly build

Variáveis de ambiente e exit codes

Variáveis de ambiente

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`

Exemplo: `uversion status --json`

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