Wiki

CLI uversion

uVersion CLI 전체 레퍼런스: 모든 명령, 플래그, 예시, JSON output, 종료 코드.

uversion 바이너리는 데스크톱 클라이언트에서 사용할 수 있는 모든 VCS 작업을 포괄하며, 자동화(CI/CD, 온보딩 스크립트, 서드파티 도구 연동)를 위한 기계 판독 가능한 --json 출력도 제공합니다. 이 페이지의 모든 내용은 개발자와 스튜디오 관리자를 대상으로 합니다.

설치

Windows에서는 uversion.exe 바이너리가 데스크톱 클라이언트 설치 프로그램에 포함되어 사용자 PATH(%LOCALAPPDATA%\uVersion)에 자동으로 추가됩니다. PATH 항목은 업데이트할 때마다 중복이 제거되고 제거 시 삭제됩니다. 새 터미널을 열고 다음을 입력합니다:

uversion --help

macOS에서는 자동입니다. 최초 실행 시 데스크톱 클라이언트가 내장 바이너리에 대한 링크를 ~/.local/bin/uversion에 생성하고 해당 폴더가 PATH에 있는지(~/.zprofile를 통해) 확인합니다. 앱을 한 번 실행하고 새 터미널을 열면 uversion 명령을 사용할 수 있습니다. PATH의 다른 위치에 수동으로 만들려면:

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

Linux에서는 CLI가 아직 .deb / .AppImage 패키지에 번들로 제공되지 않습니다. 필요하면 소스에서 빌드하세요:

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

설치된 버전을 확인하려면:

$ uversion --version

치트시트: 모든 명령

사용 가능한 모든 명령을 일반적으로 접하게 되는 순서대로 나열합니다:

명령	기능
`uversion login <url> -u <user>`	서버에서 인증
`uversion logout`	저장된 자격 증명 지우기
`uversion repos`	접근 가능한 리포지토리 나열
`uversion clone <repo> [path]`	리포지토리 클론
`uversion info`	워크스페이스 상태 + 현재 사용자 표시
`uversion status [paths...]`	수정 / 신규 / 삭제 / 잠긴 파일 확인
`uversion checkout <paths...>`	편집을 위해 파일 잠금
`uversion checkin <paths...> -m "..."`	변경 사항 업로드 및 커밋
`uversion revert <paths...>`	로컬 변경 사항 취소, 잠금 해제
`uversion sync`	서버에서 변경 사항 가져오기(리포지토리 전체)
`uversion content <path> --revision <rev>`	파일의 특정 버전 다운로드
`uversion log`	커밋 히스토리
`uversion lock list`	리포지토리의 모든 활성 잠금 확인
`uversion lock release <paths...>`	파일을 건드리지 않고 잠금 해제
`uversion lock heartbeat`	보유한 모든 잠금의 만료 연장(긴 CI 작업)
`uversion trust <url>`	서버의 자체 서명 TLS 지문 고정(TOFU, 대화형; 스크립트화하려면 `--yes`)
`uversion mistrust <url>`	서버의 고정된 지문 제거
`uversion trusted`	지문이 고정된 서버 나열

uversion content를 제외한 모든 명령은 기계 판독 가능한 출력을 생성하기 위해 --json을 허용합니다 (JSON output 참조). 모든 명령은 플래그 세부 정보를 위해 --help도 허용합니다.

인증

`uversion login`

uVersion 서버에서 인증합니다. 반환된 JWT는 시스템 keyring (Windows Credential Manager, macOS Keychain, Linux의 libsecret)에 저장되며 데스크톱 클라이언트 및 에디터 플러그인과 공유됩니다.

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

Flag	Description
`-u, --username`	사용자 이름
`-p, --password`	비밀번호. 생략하면 무음 프롬프트(에코 없음)

예시:

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

시스템 keyring에서 토큰을 삭제합니다. 인증이 필요한 다음 명령에서 비밀번호를 다시 요청합니다.

$ uversion logout
✓ Credentials cleared

리포지토리

`uversion repos`

현재 사용자가 접근할 수 있는 리포지토리를 나열합니다.

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

리포지토리를 로컬로 클론합니다. local_path를 생략하면 리포지토리 이름의 폴더가 현재 작업 디렉터리에 생성됩니다.

uversion clone <repo_name_or_id> [local_path]

예시:

$ 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

파일

`uversion status`

현재 워크스페이스의 파일 상태를 표시합니다: 수정됨, 신규(추적되지 않음), 삭제됨, 다른 사용자가 잠금.

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

예시:

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

대상 파일에 대한 배타적 잠금을 획득하고 디스크에서 쓰기 가능하게 만듭니다.

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

Flag	Description
`--force`	파일이 다른 사용자에게 잠겨 있어도 checkout을 강제합니다. `force_unlock` 권한(기본적으로 관리자)이 필요합니다. 감사됨.
`--add`	아직 로컬에 없는 경로(신규 파일)의 checkout을 허용합니다

예시:

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

수정된 파일을 업로드하고 단일 원자적 트랜잭션으로 서버에 커밋합니다. 성공 후 잠금은 자동으로 해제됩니다.

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

Flag	Description
`-m, --message`	커밋 메시지(필수)
`-a, --all`	인수로 전달된 것뿐만 아니라 워크스페이스의 모든 수정된 파일을 포함합니다

예시:

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

하나 이상의 파일의 로컬 변경 사항을 취소하고 서버 버전을 복원하며 해당 잠금을 해제합니다.

uversion revert <paths...>

예시:

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

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

`uversion sync`

서버에서 최신 변경 사항을 다운로드하여 로컬 워크스페이스에 적용합니다.

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

Flag	Description
`-f, --force`	전체 동기화: 마지막 동기화 이후의 델타뿐만 아니라 모든 파일을 다시 다운로드합니다. 워크스페이스가 손상된 경우에 유용합니다.

예시:

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

로컬 워크스페이스를 건드리지 않고 파일의 특정 버전(리비전 번호)을 다운로드합니다. revert하지 않고 비교, 보관 또는 과거 상태를 가져오는 데 유용합니다.

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

예시:

$ 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

히스토리

`uversion log`

현재 리포지토리의 커밋 히스토리로, 선택적으로 파일별로 필터링할 수 있습니다.

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

Flag	Description
`-n, --limit`	표시할 항목 수(기본값: 20)
`-p, --path`	파일 경로로 필터링

예시:

$ 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

잠금

`uversion lock list`

현재 리포지토리의 모든 활성 잠금을 표시합니다.

uversion lock list [--json]

예시:

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

파일의 로컬 콘텐츠를 건드리지 않고 하나 이상의 잠금을 수동으로 해제합니다. 변경하지 않은 에셋을 반납하고 싶을 때 사용합니다(일반적으로 실수로 checkout했거나, 제출하지 않고 시작한 작업을 중단하는 경우).

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

예시:

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

`uversion lock heartbeat`

현재 사용자가 보유한 모든 잠금의 만료를 연장합니다. 일반 워크플로에는 필요하지 않으며, 잠금을 오랫동안 보유하는 CI 작업이 관리자에게 잠금이 여전히 활성 상태임을 보여주기 위해 사용합니다.

uversion lock heartbeat

CI에서의 일반적인 예:

$ while build_in_progress; do
    uversion lock heartbeat
    sleep 300
  done

정보

`uversion info`

현재 워크스페이스, 인증된 사용자 및 동기화 상태의 정보를 표시합니다.

$ 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

모든 명령은 사람이 보는 표시 대신 기계 판독 가능한 출력을 생성하기 위해 --json 플래그를 허용합니다. 파이프라인에서 CLI를 스크립트화하는 데 필수적입니다.

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

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

오류 처리

실패하면 CLI는 Error: <message>를 stderr에 기록하고 코드 1로 종료합니다. 오류는 stdout에 JSON으로 출력되지 않습니다: --json 모드에서는 성공 출력만 구조화됩니다. 스크립트에서는 종료 코드를 테스트하세요(0이 아니면 실패).

자주 쓰는 패턴

새 팀원 온보딩

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

일상 워크플로(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"

감사 스크립트: 누가 무엇을 잠갔는가?

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

과거 리비전의 에셋 가져오기(워크스페이스를 건드리지 않고)

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 나이틀리 빌드

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

변수 & 종료 코드

환경 변수

Variable	Description
`RUST_LOG`	로그 상세도를 제어합니다(stderr에 기록). 예: `RUST_LOG=debug`. 기본 레벨: `warn`. CLI가 읽는 유일한 환경 변수입니다.

서버 URL과 사용자 이름은 config.toml (%APPDATA%/uversion/uVersion/config/)에서, 토큰은 시스템 keyring에서 가져옵니다: UV_* 변수는 읽지 않습니다.

종료 코드

코드	의미
`0`	성공
`1`	모든 애플리케이션 오류(인증, 권한, 네트워크, 서버, IO, 워크스페이스 외부, 충돌, 검증 등). CLI는 종료 코드로 오류를 구분하지 않습니다.
`2`	인수 파싱 오류, `--help` 또는 `--version`(clap 관례)

bash 스크립트에서의 사용 예:

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

설치

치트시트: 모든 명령

인증

uversion login

uversion logout

리포지토리

uversion repos

uversion clone

파일

uversion status

uversion checkout

uversion checkin

uversion revert

uversion sync

uversion content