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.

Machine-readable output for CI

commit 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.