Wiki

CLI uversion

Referência completa da CLI do uVersion: todos os comandos, flags, exemplos, JSON output, códigos de saída.

O binário uversion cobre as mesmas operações de versionamento que o cliente de desktop, além de uma saída --json aproveitável por um programa, para automação: integração contínua, scripts de integração de novos membros, ferramentas próprias. Esta página é voltada a desenvolvedores e administradores de estúdio.

Instalação

No Windows, o binário uversion.exe é incluído no instalador do cliente de 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 lançamento, o cliente de 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 à mão para outro local do PATH:

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

No Linux, também é automático, exatamente como no macOS. O cliente de desktop é distribuído como AppImage, e essa AppImage contém o binário uversion. No primeiro lançamento, o aplicativo o coloca em ~/.local/bin/uversion e garante que essa pasta esteja no PATH. Inicie o aplicativo uma vez, abra um novo terminal, e o comando estará disponível:

uversion --help

Você não precisa compilar nada. No Linux, o cliente de desktop é distribuído apenas como AppImage, e é ela que traz a CLI. Para colocar o binário em outro lugar do PATH, copie-o de ~/.local/bin:

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

Para verificar a versão instalada:

$ uversion --version

Referência rápida: todos os comandos

O conjunto de comandos disponíveis, na ordem em que costumamos encontrá-los:

Comando	O que faz
`uversion login <url> -u <user>`	Autenticar-se em um servidor
`uversion logout`	Apagar as credenciais armazenadas
`uversion repos`	Listar os repositórios acessíveis
`uversion clone <repo> [path]`	Clonar um repositório
`uversion info`	Exibir o estado do workspace + usuário atual
`uversion status [paths...]`	Ver os arquivos modificados / novos / excluídos / bloqueados
`uversion checkout <paths...>`	Reservar arquivos para edição (aplica um bloqueio)
`uversion checkin <paths...> -m "..."`	Enviar e confirmar as alterações
`uversion revert <paths...>`	Descartar as alterações locais e liberar os bloqueios
`uversion sync`	Buscar as alterações do servidor (repositório inteiro)
`uversion content <path> --revision <n>`	Baixar uma versão específica de um arquivo
`uversion log`	Histórico de commits
`uversion lock list`	Ver todos os bloqueios do repositório
`uversion lock release <paths...>`	Liberar um bloqueio sem tocar no arquivo
`uversion lock heartbeat`	Sinalizar que seus bloqueios ainda estão em uso (para o monitoramento)
`uversion trust <url>`	Memorizar a impressão digital do certificado autoassinado de um servidor (interativo; `--yes` para automatizar)
`uversion mistrust <url>`	Esquecer a impressão digital memorizada de um servidor
`uversion trusted`	Listar os servidores cuja impressão digital está memorizada

Todos os comandos, exceto uversion content, aceitam --json, que substitui a exibição legível por uma saída aproveitável por um programa (ver JSON output). Todos aceitam --help para o detalhe das opções.

checkout, checkin e revert também aceitam --paths-file <fichier>, indispensável assim que se trabalha na escala de um projeto Unreal. Ver Listas de caminhos volumosas.

Autenticação

`uversion login`

Autentica-se em um servidor uVersion. O servidor entrega um token de sessão (um JWT, de JSON Web Token), que a CLI guarda no gerenciador de senhas do sistema: o Gerenciador de Credenciais no Windows, o Chaveiro no macOS, o libsecret no Linux. Esse token é compartilhado com o cliente de desktop, o plugin do Unreal e o plugin do Rider: conectar-se de um lado conecta os outros, e desconectar-se desconecta todos.

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

Opção	Descrição
`-u, --username`	Nome de usuário
`-p, --password`	Desaconselhado. Ver o quadro abaixo. Se a opção for omitida, a CLI lê a variável de ambiente `UVERSION_PASSWORD`, e na falta dela pede a senha de forma interativa, sem eco na tela.

Para automatizar uma conexão, use UVERSION_PASSWORD, nunca -p

Em um sistema multiusuário, a linha de comando de cada processo é legível pelas outras contas da máquina: ps no Linux e no macOS, o Gerenciador de Tarefas ou wmic no Windows. Uma senha passada como argumento aparece ali em texto claro, mesmo que venha de uma variável, pois a shell a substitui pelo seu valor antes de lançar o programa. Ela também vai parar no histórico da shell e, muitas vezes, nos registros da cadeia de integração contínua.

A CLI lê UVERSION_PASSWORD justamente para evitar isso, e exibe um aviso na saída de erro quando -p é usado.

Exemplos:

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

Na primeira conexão a um servidor que apresenta um certificado autoassinado, a CLI exibe a impressão digital do certificado e pede que você a confirme, depois a memoriza. É o princípio da confiança no primeiro contato, o mesmo do SSH: aceita-se uma identidade uma vez, e toda apresentação posterior de uma identidade diferente é sinalizada. Se a impressão digital muda, a CLI recusa a conexão e o avisa: é ou uma renovação legítima do certificado, ou uma interceptação do seu tráfego por um terceiro. A manobra deliberada é então uversion mistrust <url>, seguida de uma nova conexão.

`uversion logout`

Apaga o token do gerenciador de senhas do sistema e invalida no servidor todas as sessões desta conta. Como o token é compartilhado, isso também desconecta o cliente de desktop, o plugin do Unreal e o plugin do Rider, em todas as suas máquinas.

$ uversion logout
Logged out (alice)

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

Qual conta age? A do workspace, não a última conectada

É o ponto que mais surpreende, e é melhor conhecê-lo antes de automatizar qualquer coisa: a identidade usada não é a da última conexão, é a do workspace em que você está.

Um workspace é uma pasta clonada, reconhecível pela sua subpasta .uversion. O arquivo .uversion/config.toml registra ali o servidor e a conta proprietária:

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

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

Assim que você está em um workspace, server_url e owner têm autoridade: status, checkout, checkin, revert, sync, log, content, lock e info se autenticam como owner, contra server_url.

Apenas login, logout, repos e clone usam a configuração compartilhada entre todos os workspaces (no Windows %APPDATA%/uversion/uVersion/config/config.toml), que segue a conta ativa do cliente de desktop.

Por quê. Uma mesma máquina serve com frequência a várias contas, por exemplo um freelancer que trabalha para dois estúdios. Sem essa regra, todos os workspaces agiriam sob a conta ativa do momento: uma pasta clonada por alice, mas usada enquanto bob está ativo, aplicaria seus bloqueios em nome de bob, veria seus próprios arquivos como «bloqueados por outra pessoa» e teria seus envios recusados.

Para mudar a identidade de um workspace, edite o campo owner em .uversion/config.toml e certifique-se de que essa conta tenha se conectado pelo menos uma vez nesta máquina (uversion login), para que o token dela esteja presente. Verifique em seguida com uversion info, que exibe a conta realmente utilizada.

Limitação conhecida: um mesmo nome de usuário em dois servidores

O token é guardado apenas sob o nome de usuário, sem o servidor. Se o mesmo nome existir em dois servidores uVersion diferentes, ambos compartilham uma única e mesma entrada: conectar-se ao segundo substitui o token do primeiro. Use nomes distintos, ou empregue apenas um servidor por vez a partir de uma mesma máquina.

Repositórios

`uversion repos`

Lista os repositórios aos quais a conta tem acesso. Este comando usa a configuração compartilhada, não a de um workspace: portanto, responde pela conta da sua última conexão.

$ 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 um repositório localmente. Se o caminho for omitido, uma pasta com o nome do repositório é criada no diretório atual. O clone também cria a subpasta .uversion, que torna a pasta um workspace e registra o servidor e a conta proprietária.

A transferência aplica a desduplicação: o conteúdo é dividido em blocos, e um bloco já presente é armazenado uma única vez, mesmo que apareça em vários arquivos. É por isso que o espaço ocupado em disco costuma ser bem menor que o volume baixado.

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`

Exibe o estado dos arquivos do workspace atual: modificados, novos (untracked), 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`

Aplica um bloqueio exclusivo nos arquivos indicados e os torna modificáveis em disco. Os arquivos rastreados ficam somente leitura enquanto não estiverem reservados: é isso que evita que duas pessoas modifiquem o mesmo asset binário em paralelo.

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

Opção	Descrição
`--paths-file`	Ler caminhos adicionais de um arquivo, um por linha. Ver Listas de caminhos volumosas.
`--force`	Toma o bloqueio mesmo que ele esteja com outra pessoa. Reservado às contas que possuem a capacidade `force_unlock`, ou seja, os papéis `admin` e `lead`. Ver abaixo.
`--add`	Autoriza a reserva de caminhos ainda ausentes localmente, para arquivos novos.

O que --force realmente faz

A opção toma o bloqueio de outra pessoa. Ela é protegida pela capacidade force_unlock, possuída pelos papéis admin e lead. Uma conta que não a tem recebe uma recusa explícita, com o recurso a seguir: pedir a um administrador, ou usar o botão «Solicitar a liberação» do cliente de desktop, que avisa a pessoa envolvida.

Quando um roubo efetivamente ocorreu, ele é registrado no log de auditoria, com os caminhos envolvidos e o nome das pessoas de quem os bloqueios foram tomados. Nada é escrito se a opção estava presente mas nenhum bloqueio de terceiros mudou de mãos: nos scripts, a flag costuma ser sistemática, e um log cheio de eventos sem objeto é um log que ninguém relê.

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

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

Envia os arquivos modificados e os confirma no servidor em uma única transação: ou tudo passa, ou nada. Os bloqueios são liberados automaticamente em caso de sucesso.

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

Opção	Descrição
`-m, --message`	Mensagem de commit. Obrigatória.
`-a, --all`	Incluir todos os arquivos modificados do workspace, não apenas os passados como argumento.
`--paths-file`	Ler caminhos adicionais de um arquivo, um por linha. Ver Listas de caminhos volumosas.

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`

Abandona as alterações locais de um ou vários arquivos, restaura a versão do servidor e libera os bloqueios correspondentes.

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

Exemplos:

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

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

Listas de caminhos volumosas: `--paths-file`

checkout, checkin e revert aceitam --paths-file <fichier>: um arquivo de texto contendo um caminho por linha. Os caminhos assim lidos se somam aos passados como argumento, não os substituem.

Para que serve. Em um projeto Unreal, uma operação abrange comumente vários milhares de arquivos. Passá-los todos como argumentos esbarra em um limite do sistema: no Windows, uma linha de comando não pode ultrapassar 32.767 caracteres, o que representa cerca de 500 caminhos de asset. Além disso, o comando falha antes mesmo de iniciar, com uma mensagem de erro do sistema que nada diz sobre o problema real. --paths-file elimina esse limite: o arquivo pode conter quantos forem necessários.

Reservar todos os arquivos modificados de uma pasta, qualquer que seja o número:

$ 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

Depois, enviar exatamente o mesmo lote:

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

No Windows, no 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

É também o mecanismo que o plugin do Rider emprega para transmitir um conjunto de modificações volumoso.

`uversion sync`

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

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

Flag	Descrição
`-f, --force`	Sync completo: rebaixa 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 sem tocar no workspace local. Útil para comparar, arquivar, ou recuperar um estado passado sem fazer um revert.

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

--revision espera um número inteiro, não uma impressão digital de commit

É o número de revisão do arquivo: um contador que vale 1 na sua primeira versão, 2 na segunda, e assim por diante. Passar uma impressão digital de commit como 6e2b8a0 faz o comando falhar já na análise dos argumentos.

O número é lido em uversion log --path <fichier>, onde cada linha de arquivo o exibe entre parênteses. Omitir --revision baixa a última versão.

Exemplos:

$ 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

Histórico

`uversion log`

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

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

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

Exemplos:

$ 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

Uma linha marcada como deleted é uma revisão de exclusão: ela leva um número como as demais, mas não tem conteúdo para baixar.

Bloqueios

Um bloqueio nunca expira

Ele se mantém até ser explicitamente liberado: por uversion checkin, por uversion revert, por uversion lock release, ou por um desbloqueio forçado de administrador. Não existe nenhuma expiração automática, nem ao fim de uma hora, nem ao fim de um mês. Um arquivo reservado e esquecido continua assim até que alguém intervenha.

Por conseguinte, uversion lock heartbeat não prolonga nada. Este comando apenas diz «esses bloqueios ainda me servem», para que os administradores distingam um bloqueio ativo de um abandonado.

`uversion lock list`

Exibe todos os bloqueios do 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

Se não houver nada a exibir, o comando escreve No active locks.

`uversion lock release`

Libera um ou vários bloqueios sem tocar no conteúdo local do arquivo. A usar para «devolver» um asset que não se modificou: reservado por engano, ou trabalho abandonado sem envio.

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

Exemplos:

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

Este comando libera apenas seus próprios bloqueios. Para remover o de outra pessoa, é preciso passar pela administração, ou por uversion checkout --force se você for admin ou lead.

`uversion lock heartbeat`

Sinaliza que os bloqueios mantidos pela conta atual ainda estão em uso. Isso não os prolonga: nada expira. É um sinal de supervisão, para que um administrador que inspeciona a lista de bloqueios veja quais ainda estão ativos. Inútil no trabalho diário; útil para um processamento automatizado que mantém um arquivo reservado por horas.

$ uversion lock heartbeat
3 lock(s) extended

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

Exemplo em integração contínua:

$ while build_in_progress; do
    uversion lock heartbeat
    sleep 300
  done

Info

`uversion info`

Exibe a conta utilizada e o estado do workspace atual. É o comando a lançar primeiro quando algo se comporta de forma inesperada: mostra sob qual identidade a CLI realmente age, que é a do proprietário do workspace e não necessariamente a da sua última conexão (ver Qual conta age?).

$ 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

Fora de um workspace, ou sem sessão válida:

$ uversion info
User: not logged in

Workspace: not in a uVersion workspace

O comando não conta os arquivos nem exibe um resumo das modificações: esse é o papel de uversion status.

JSON output

Todos os comandos, exceto content, aceitam --json, que substitui a exibição legível por uma saída estruturada. É o que torna a CLI automatizável.

Vários comandos retornam um array na raiz

log, lock list e repos produzem diretamente um array JSON, sem objeto envolvente. Portanto não há nem chave commits, nem chave locks, nem chave repositories: é .[] que se deve escrever no jq, não .commits[]. Uma expressão que aponta para uma chave inexistente não produz nada, sem mensagem de erro.

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

Os valores possíveis de status:

Valor	Significado
`modified`	O arquivo é modificável em disco, sem bloqueio aplicado
`locked`	Reservado por você
`locked_other`	Reservado por outra pessoa, nomeada em `locked_by`
`new`	Presente localmente, desconhecido do servidor
`deleted`	Presente no servidor, ausente localmente
`tracked`	Rastreado e intacto. Só aparece se você filtrou por caminho

Note que summary.modified soma modified e locked, pois ambos designam um arquivo no qual você está trabalhando.

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

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

O vencimento em 2126 não é um erro de digitação: a coluna não pode ficar vazia no banco de dados, de modo que o servidor escreve um valor empurrado cem anos à frente. Os bloqueios não expiram. Não exiba este campo a um usuário e não construa nada sobre ele.

Tratamento de erros

Em caso de falha, a CLI escreve Error: <message> na saída de erro e termina com o código 1. Os erros nunca são emitidos em JSON na saída padrão: com --json, apenas o resultado de um sucesso é estruturado. Em um script, teste o código de saída, não o conteúdo da saída.

Padrões comuns

Integração 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 reservou o quê?

lock list --json retorna um array na raiz. Itera-se, portanto, com .[], e os campos são username, file_path e acquired_at:

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

Os arquivos reservados por uma pessoa específica:

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

Extrair as impressões digitais de commit

Aqui também o array está na raiz, e o campo se chama commit_hash:

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

Os commits de uma pessoa, com sua mensagem:

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

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

uversion content espera um número de revisão, não uma impressão digital de commit. Localize-o no histórico do arquivo, onde ele é exibido entre parênteses:

$ 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 de uma vez, para a última revisão de um arquivo:

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 noturno em integração contínua

A senha passa por UVERSION_PASSWORD, nunca por -p: a linha de comando de um processo é legível pelas outras contas da 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

Variáveis de ambiente e códigos de saída

Variáveis de ambiente

Variável	Descrição
`UVERSION_PASSWORD`	Senha usada por `uversion login` quando a opção `-p` está ausente. É a maneira recomendada de automatizar uma conexão: ao contrário de um argumento de linha de comando, uma variável de ambiente não fica exposta às outras contas da máquina. Se estiver vazia ou ausente, a CLI pede a senha de forma interativa.
`RUST_LOG`	Verbosidade dos registros, escritos na saída de erro. Por exemplo `RUST_LOG=debug`. Nível padrão: `warn`.

Nenhuma variável UV_* é lida. O servidor e a conta provêm de .uversion/config.toml quando você está em um workspace, e caso contrário da configuração compartilhada (no Windows %APPDATA%/uversion/uVersion/config/config.toml). O token de sessão vem do gerenciador de senhas do sistema. Ver Qual conta age?.

Códigos de saída

Código	Significado
`0`	Sucesso. É também o código retornado por `--help` e por `--version`, que não são erros.
`1`	Qualquer erro de aplicação: autenticação, permissão, rede, servidor, escrita em disco, fora do workspace, conflito, validação. A CLI não distingue as causas pelo código de saída; o detalhe está na saída de erro.
`2`	Erro de análise dos argumentos: opção desconhecida, valor faltante, subcomando inválido.

Exemplo em script shell:

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

Instalação

Referência rápida: todos os comandos

Autenticação

uversion login

uversion logout

Qual conta age? A do workspace, não a última conectada

Repositórios

uversion repos

uversion clone

Arquivos

uversion status

uversion checkout

uversion checkin

uversion revert

Listas de caminhos volumosas: --paths-file

uversion sync

uversion content

Histórico

uversion log

Bloqueios

uversion lock list

uversion lock release

uversion lock heartbeat

Info

uversion info

JSON output

Exemplo: uversion status --json

Exemplo: uversion log --json -n 1

Exemplo: uversion lock list --json

Tratamento de erros

Padrões comuns

Integração de um novo membro da equipe

Fluxo de trabalho diário (artist / programmer)

Script de auditoria: quem reservou o quê?

Extrair as impressões digitais de commit

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

Build noturno em integração contínua

Variáveis de ambiente e códigos de saída

Variáveis de ambiente

Códigos de saída

`uversion login`

`uversion logout`

`uversion repos`

`uversion clone`

`uversion status`

`uversion checkout`

`uversion checkin`

`uversion revert`

Listas de caminhos volumosas: `--paths-file`

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

Exemplo: `uversion lock list --json`