Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Command-line client

Run vsync <command> --help for the exact options supported by your installed version.

Common context

Most remote commands need a game and platform:

vsync --game hippo --platform win64 list

You can set VSYNC_GAME and VSYNC_PLATFORM instead.

Vsync also reads context from where you run it: inside a checkout it knows the game, platform, and stream from the checkout's marker. Explicit flags always win.

Browse builds

vsync --game hippo --platform win64 list

The output includes streams and recent builds, including versions, authors, source revisions, broken status, pin status, and notes.

Fetch builds

Fetch the current tip of a stream:

vsync --game hippo --platform win64 fetch nightly

Fetch an exact version:

vsync --game hippo --platform win64 fetch --version 2193.1.2

A version is unique within its stream (per platform), but may repeat across streams - a rebuild of the same changelist can live in both nightly and rc. When several builds share the version you asked for, the fetch stops and lists them so you can pick a build ID.

Fetch an exact build by its ID (its game and platform come from the server, so no flags are needed):

vsync fetch 42

Without --out, Vsync creates the checkout below the build root - streams at <root>/<game>/<platform>/<stream>, exact builds under <root>/<game>/<platform>/builds/. Every fetched directory is a managed checkout: it carries a .vsync-checkout.json marker recording the server, game, platform, stream, and build it holds, and updates replace the directory wholesale.

Inside a stream checkout, update it to the stream's current tip with no arguments at all:

vsync fetch

An exact-build checkout tracks no stream, so a bare fetch inside one is an error.

Verify a checkout

Checkouts are ordinary directories, so files can drift - get edited, corrupted, or deleted. Compare one against the build it was fetched from:

vsync verify D:\builds\test

Checkouts made by the desktop app record their build; for other directories pass the build explicitly with --build <id>. Files that drifted or went missing are listed, and --repair rewrites exactly those files from the local cache, downloading any chunks the cache no longer has:

vsync verify D:\builds\test --repair

Extra local files that are not part of the build (logs, saves, configs) never fail verification and are never deleted. To reset a checkout wholesale, fetch the build again into an empty directory.

Publish a build

vsync --game hippo --platform win64 commit D:\build-output `
  --stream nightly `
  --version 2193.1.2 `
  --rev CL45210 `
  --config development

The final line is the registered build's ID, like #42. Recommitting identical contents uploads no duplicate chunks; with the same metadata it is a retry and answers with the existing build, while different metadata (a new version, another stream) registers a new build sharing the same stored contents.

--stream is the only place a build's stream is set, and the stream must already exist. Without it, the build belongs to no stream and is kept only while it is young or pinned.

Build and publish an Unreal project

vsync --game hippo --platform win64 build-ue D:\hippo\Hippo.uproject `
  --config shipping `
  --stream nightly

build-ue runs the engine's RunUAT BuildCookRun for the project (build, cook, stage, pak, IoStore), commits the packaged folder exactly like commit does, and deletes the packaged folder once the commit succeeded (--keep leaves it in place; a failed commit leaves it too, so vsync commit can pick it up). The folder lives under the project's Saved/Vsync/, so it never shows up as a workspace change.

Whatever your own build script adds to BuildCookRun goes after -- and reaches UAT unchanged:

vsync --game hippo build-ue D:\hippo\Hippo.uproject --stream nightly `
  -- -nocompileeditor -cookincremental -zenstore -CookCultures=en

What it fills in by itself:

  • The engine comes from the project's engine association: a launcher install by version, a registered source build by its GUID, or a source build sitting above the project. --engine <root> overrides it.
  • The target is the project's Game target (--target picks another, e.g. a Client target); the platform is the global --platform, or the machine's own when unset.
  • --rev defaults to the revision the project's workspace is at: the Perforce changelist or the Git commit, with -dirty appended when the workspace has local edits.
  • --version defaults to ProjectVersion from Config/DefaultGame.ini, joined to the revision with a hyphen, e.g. 1.2.0-45210.
  • --config is recorded on the build as its config.

Two ways to pick what gets built:

  • The folder as it is. The default: the build is whatever the workspace holds right now, local edits included, and the revision says so with -dirty.
  • An exact revision. --at 45210 (or a commit) syncs the workspace there first, with p4 sync //...@45210 or git checkout --detach. It refuses a workspace with local edits, because a build stamped with a revision must not carry changes that revision does not have.

--dry-run prints the UAT command line and stops; the same line is printed before a real build so it can be reproduced by hand. UAT's output streams to stderr, and the full log is kept next to the packaged folder as <folder>.log, whether the build succeeds or fails.

Machine-readable output for CI

commit, build-ue and fetch accept --json, replacing the text output with one JSON object on stdout so pipelines parse results instead of scraping text:

vsync --game hippo --platform win64 commit D:\build-output --stream nightly --json

{"content_id":"067c4e9949d5d77952ac78bfb1a823ab","build":42,"files":1214,
 "bytes":18321047552,"chunks":8956,"new_chunks":412,"new_bytes":864026624,
 "dedup_ratio":0.953,"uploaded_chunks":412,"uploaded_bytes":864026624,
 "game":"hippo","platform":"win64","stream":"nightly"}

dedup_ratio is the share of the build's bytes the destination already had. build and uploaded_* appear only when the commit pushed to a server; the game/platform/stream fields echo what the build was published as.

fetch --json reports build, content_id, files, bytes, the out directory, and - when pulling from a server - downloaded_chunks/downloaded_bytes. Progress and errors still go to stderr, so stdout stays pure JSON.

Manage games

vsync game list
vsync game create hippo
vsync game delete hippo --yes

Create the game before its first stream or build. Deleting a game immediately removes all of its streams and build metadata, including pinned builds. Garbage collection reclaims the unreferenced chunks later.

Manage streams

vsync --game hippo stream create nightly --description "Latest automated build"
vsync --game hippo stream list
vsync --game hippo stream describe nightly "Latest automated build"
vsync --game hippo stream delete nightly
vsync --game hippo stream delete nightly --delete-builds --yes

Streams belong to a game, not to a platform. Deleting one leaves its builds in place, now in no stream, where normal retention and garbage collection rules apply. --delete-builds deletes them with the stream instead - pinned builds included - and their storage is reclaimed by the next garbage collection.

Report and pin builds

vsync report 42 --verdict broken --note "Crashes during startup"
vsync report 42 --verdict good --note "Campaign and multiplayer both load"
vsync report 42 --remove
vsync pin 42
vsync pin 42 --remove

Build IDs are shown as #42 around the product; the leading # is optional on the command line (quote it in a shell, where # starts a comment).

Each user has one report per build and can update or withdraw it. Reports and their notes are visible to the team. Pinned builds are protected from server garbage collection.

Check your connection

vsync doctor

Measures latency, jitter, and download and upload throughput against the connected server, over the same transfer path a sync uses.

Without a login, check a server anonymously (the server rate-limits anonymous checks):

vsync doctor --server https://builds.example.com

An anonymous version of the check runs in a browser at https://<server>/diag - useful for people who do not have the CLI installed.

Sign out

vsync logout

This revokes the token on the server and forgets the login. It does not remove cached chunks or checkouts.