Wiki

CLI uversion

Complete uVersion CLI reference: every command, flag, example, JSON output, exit codes.

The uversion binary covers every VCS operation available in the desktop client, plus a machine-readable --json output for automation (CI/CD, onboarding scripts, third-party tooling integration). Everything on this page is aimed at developers and studio admins.

Installation

On Windows, the uversion.exe binary ships with the desktop client installer and is added automatically to the user PATH (%LOCALAPPDATA%\uVersion). The PATH entry is deduplicated on every update and removed on uninstall. Open a new terminal and type:

uversion --help

On macOS, it is automatic: on first launch, the desktop client creates a link to the embedded binary at ~/.local/bin/uversion and makes sure that folder is on the PATH (via ~/.zprofile). Launch the app once, open a new terminal, and the uversion command is available. To do it by hand to another PATH location:

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

On Linux, the CLI is not yet bundled in the .deb / .AppImage packages. Build it from source if you need it:

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

To check the installed version:

$ uversion --version

Cheatsheet: every command

The full set of available commands, in the order you typically encounter them:

Command	What it does
`uversion login <url> -u <user>`	Authenticate against a server
`uversion logout`	Clear the stored credentials
`uversion repos`	List accessible repositories
`uversion clone <repo> [path]`	Clone a repository
`uversion info`	Show the workspace state + current user
`uversion status [paths...]`	See modified / new / deleted / locked files
`uversion checkout <paths...>`	Lock files for editing
`uversion checkin <paths...> -m "..."`	Upload and commit changes
`uversion revert <paths...>`	Discard local changes, release the locks
`uversion sync`	Fetch changes from the server (whole repo)
`uversion content <path> --revision <rev>`	Download a specific version of a file
`uversion log`	Commit history
`uversion lock list`	See all active locks in the repo
`uversion lock release <paths...>`	Release a lock without touching the file
`uversion lock heartbeat`	Extend the expiry of all held locks (long CI jobs)
`uversion trust <url>`	Pin a server's self-signed TLS fingerprint (TOFU, interactive; `--yes` to script it)
`uversion mistrust <url>`	Remove a server's pinned fingerprint
`uversion trusted`	List servers with a pinned fingerprint

Every command (except uversion content) accepts --json to produce machine-readable output (see JSON output). Every command also accepts --help for the flag details.

Authentication

`uversion login`

Authenticates against a uVersion server. The returned JWT is stored in the system keyring (Windows Credential Manager, macOS Keychain, libsecret on Linux) and shared with the desktop client and the editor plugins.

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

Flag	Description
`-u, --username`	Username
`-p, --password`	Password. If omitted, a silent prompt (no echo)

Examples:

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

Removes the token from the system keyring. The next command that requires authentication will ask for the password again.

$ uversion logout
✓ Credentials cleared

Repositories

`uversion repos`

Lists the repositories the current user has access to.

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

Clones a repository locally. If local_path is omitted, a folder named after the repo is created in the current working directory.

uversion clone <repo_name_or_id> [local_path]

Examples:

$ 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

Files

`uversion status`

Shows the state of the files in the current workspace: modified, new (untracked), deleted, locked by others.

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

Examples:

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

Acquires an exclusive lock on the target files and makes them writable on disk.

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

Flag	Description
`--force`	Force the checkout even if the file is locked by another user. Requires the `force_unlock` capability (admin by default). Audited.
`--add`	Allows checking out paths not yet present locally (new files)

Examples:

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

Uploads the modified files and commits them to the server in a single atomic transaction. The locks are released automatically on success.

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

Flag	Description
`-m, --message`	Commit message (required)
`-a, --all`	Include every modified file in the workspace, not only the ones passed as arguments

Examples:

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

Discards local changes to one or more files, restores the server version, releases the matching locks.

uversion revert <paths...>

Examples:

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

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

`uversion sync`

Downloads the latest changes from the server and applies them to the local workspace.

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

Flag	Description
`-f, --force`	Full sync: re-downloads every file, not only the delta since the last sync. Useful when the workspace is corrupted.

Examples:

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

Downloads a specific version of a file (by revision number) without touching the local workspace. Useful to compare, archive, or retrieve a historical state without doing a revert.

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

Examples:

$ 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

History

`uversion log`

Commit history of the current repository, optionally filtered by file.

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

Flag	Description
`-n, --limit`	Number of entries to display (default: 20)
`-p, --path`	Filter by file path

Examples:

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

Shows all the active locks in the current repository.

uversion lock list [--json]

Examples:

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

Manually releases one or more locks without touching the local content of the file. Use it when you want to "hand back" an asset without having made any changes (typically, you checked it out by mistake, or you are abandoning work started without submitting).

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

Examples:

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

`uversion lock heartbeat`

Extends the expiry of all locks held by the current user. Not needed for the normal workflow; used by CI jobs that hold a lock for a long time, so that admins can see the lock is still active.

uversion lock heartbeat

Typical example in CI:

$ while build_in_progress; do
    uversion lock heartbeat
    sleep 300
  done

Info

`uversion info`

Shows the information of the current workspace, the authenticated user, and the sync state.

$ 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

Every command accepts the --json flag to produce machine-readable output instead of the human display. Essential for scripting the CLI in pipelines.

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

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

Error handling

On failure, the CLI writes Error: <message> to stderr and exits with code 1. Errors are not emitted as JSON on stdout: in --json mode, only the success output is structured. In your scripts, test the exit code (non-zero = failure).

Common patterns

Onboarding a new team member

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

Daily workflow (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"

Audit script: who has what locked?

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

Retrieve an asset at a past revision (without touching the 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

Environment variables & exit codes

Environment variables

Variable	Description
`RUST_LOG`	Controls log verbosity (written to stderr), e.g. `RUST_LOG=debug`. Default level: `warn`. This is the only environment variable read by the CLI.

The server URL and username come from config.toml (%APPDATA%/uversion/uVersion/config/), the token from the system keyring: no UV_* variable is read.

Exit codes

Code	Meaning
`0`	Success
`1`	Any application error (auth, permission, network, server, IO, outside workspace, conflict, validation…). The CLI does not distinguish errors by exit code.
`2`	Argument parsing error, `--help` or `--version` (clap convention)

Example usage in a bash script:

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

Installation

Cheatsheet: every command

Authentication

uversion login

uversion logout

Repositories

uversion repos

uversion clone

Files

uversion status

uversion checkout

uversion checkin

uversion revert

uversion sync

uversion content

History

uversion log

Locks

uversion lock list

uversion lock release

uversion lock heartbeat

Info

uversion info

JSON output

Example: uversion status --json

Example: uversion log --json -n 1

Error handling

Common patterns

Onboarding a new team member

Daily workflow (artist / programmer)

Audit script: who has what locked?

Retrieve an asset at a past revision (without touching the workspace)

CI nightly build

Environment variables & exit codes

Environment variables

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`

Example: `uversion status --json`

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