Skip to content

Commands

Kyle Ebbinga edited this page Nov 19, 2026 · 1 revision

Access

vx access [--project] [--server] [--verbose]

Shows who can access the project: every user and group with a grant and their level (read, write or manage). Only they and server admins can see the project. Run it inside a workspace to see that workspace's project, or name one with --project. See Users and permissions.

Parameter Short hand Type Required Description
project -p string No The project. Defaults to the current workspace's project.
server -s string No The server address to use. Defaults to the workspace's server, then the one set with vx config server, then http://127.0.0.1:5000.
verbose -v bool No Displays verbose output.

Access grant

vx access grant <name> <level> [--project] [--server] [--verbose]

Gives a user or group read, write or manage access to the project. Users and groups share one namespace, so you don't say which one name is. Granting again changes the level. A user's effective level is the highest of their own grant and their groups' grants.

Parameter Short hand Type Required Description
level string Yes read (sync and view history), write (submit and lock) or manage (manage access and branches).
name string Yes A user or group.
project -p string No The project. Defaults to the current workspace's project.
server -s string No The server address to use.
verbose -v bool No Displays verbose output.

Note: Requires manage access to the project. Server admin isn't a project level: use vx user admin for that.

Examples

Let everyone in the artists group submit and lock:

vx access grant artists write

Let one contractor read a different project without being in its workspace:

vx access grant contractor-jo read -p game

Let the leads manage access and branches:

vx access grant leads manage

Access revoke

vx access revoke <name> [--project] [--server] [--verbose]

Removes a user's or group's grant. Members of a group keep any access they have through their own grant or other groups.

Parameter Short hand Type Required Description
name string Yes A user or group.
project -p string No The project. Defaults to the current workspace's project.
server -s string No The server address to use.
verbose -v bool No Displays verbose output.

Branch

vx branch [name] [--blank] [--delete] [--force] [--merge-to] [--project] [--server] [--verbose]

Shows, lists, creates or deletes branches. With no name it shows the workspace's current branch and where it merges to. vx branch list lists the project's branches. vx branch <name> creates a branch as a copy of the current branch as last submitted: the server copies the file list, so nothing is uploaded. Outside a workspace, a new branch copies main. See Branching and merging.

Parameter Short hand Type Required Description
blank bool No Creates the branch with no files, instead of a copy of the current branch.
delete -d bool No Deletes the branch instead of creating it.
force -f bool No Deletes without asking for confirmation.
merge-to string No Merges every revision on the branch into this branch automatically (e.g. release-1.0 into release-2.0). Sets it on a new branch or changes it on an existing one; none stops it.
name string No The branch to create, change or delete, or list. Omit it to show (or with --merge-to, change) the current branch.
project -p string No The project. Defaults to the current workspace's project.
server -s string No The server address to use.
verbose -v bool No Displays verbose output.

Note: Creating a branch doesn't switch to it. Run vx checkout <name> afterwards.

Note: Unsubmitted changes stay behind in the workspace and don't go onto the new branch. vx branch warns when there are any.

Warning: vx branch -d deletes the branch on the server for everyone, together with its revisions, and asks for confirmation first unless --force is given. Merge anything you want to keep first. A branch that other branches were created from or merge into can't be deleted.

Merge chains

--merge-to gives a branch a merge target. Every revision submitted (or merged) onto the branch is then merged on into its target by the server, hop by hop, so release-1.0 → release-2.0 → main carries a fix from the oldest release to main with one submit. A hop stops at the first conflict, lock or empty merge; the revision that started the chain stands either way, and the next revision on the branch retries the missed hop. vx submit prints every hop. Targets must share history with the branch, and loops are refused.

Examples

Show the current branch:

vx branch

List every branch of the project:

vx branch list

Create a branch from the current one, then switch to it:

vx branch feature-x
vx checkout feature-x

Create an empty branch:

vx branch experiment --blank

Make every fix on release-1.0 flow on to release-2.0:

vx branch release-1.0 --merge-to release-2.0

Stop the current branch's merge chain:

vx branch --merge-to none

Delete a branch without the confirmation prompt:

vx branch -d feature-x -f

Checkout

vx checkout <branch> [--parallel] [--server] [--verbose]

Switches the workspace to another branch of its project. Only files whose content differs between the two branches are downloaded, files the new branch doesn't have are removed, and the workspace follows the new branch from then on.

Parameter Short hand Type Required Description
branch string Yes The branch to switch the workspace to.
parallel int No The number of parallel operations to perform. Defaults to the number of processors.
server -s string No The server address to use.
verbose -v bool No Displays verbose output.

Note: Refused while there are local changes, so nothing is lost or carried between branches. Submit or revert them first.

Note: The workspace switches to the new branch before the files are downloaded. If the command is interrupted, vx sync finishes the job.

Examples

Switch to a feature branch:

vx checkout feature-x

Clear

vx clear

Clears the console window. vx cls does the same. Mostly useful in the interactive session (vx with no command).

Clone

vx clone <project> [path] [--branch] [--parallel] [--server] [--verbose]

Makes a folder (by default the current one) a workspace of a project that already exists on the server, and downloads the branch's latest files into it.

Parameter Short hand Type Required Description
branch -b string No The branch to follow. Defaults to main.
parallel int No The number of parallel operations to perform. Defaults to the number of processors.
path string No Folder to clone into. Defaults to the current folder.
project string Yes The name of the project on the server.
server -s string No The server address to use.
verbose -v bool No Displays verbose output.

Note: Files already in the folder are never overwritten. A file identical to the server's is adopted as is; one that differs is reported as a conflict.

Note: Running it again in a folder already cloned from the same branch finishes an interrupted download, the same as vx sync.

Examples

Get the game project into the current folder:

vx clone game

Get the feature-x branch into another folder:

vx clone game D:/Work/Game -b feature-x

Config

vx config [key] [value] [--unset] [--server] [--verbose]

Shows or changes settings for every vx command on this machine. With no key it lists every setting and where the server address in use comes from. Today the only key is server, the default server used when neither --server nor the workspace names one. Settings are saved in ~/.vertex/config.json.

Parameter Short hand Type Required Description
key string No The setting to show or change. Lists every setting when omitted.
server -s string No The server address to use.
unset bool No Removes the saved value.
value string No The new value. Shows the current value when omitted.
verbose -v bool No Displays verbose output.

Examples

Show every setting:

vx config

Use a team server by default:

vx config server https://vertex.example.com

Go back to the built-in default (http://127.0.0.1:5000):

vx config server --unset

Group

vx group <command>

Manages groups of users. Access granted to a group applies to all its members, so grant a group once and then add and remove people. Group commands are for server admins.

Group add

vx group add <group> <users> [--server] [--verbose]

Adds one or more users to a group.

Parameter Short hand Type Required Description
group string Yes The group's name.
server -s string No The server address to use.
users string Yes One or more usernames.
verbose -v bool No Displays verbose output.

Examples

Add two artists:

vx group add artists alice bob

Group create

vx group create <group> [--server] [--verbose]

Creates a group. Group names share one namespace with usernames.

Parameter Short hand Type Required Description
group string Yes The group's name.
server -s string No The server address to use.
verbose -v bool No Displays verbose output.

Group delete

vx group delete <group> [--force] [--server] [--verbose]

Deletes a group and the access it gave.

Parameter Short hand Type Required Description
force -f bool No Deletes without asking for confirmation.
group string Yes The group's name.
server -s string No The server address to use.
verbose -v bool No Displays verbose output.

Warning: Members lose any access that came only from this group.

Group list

vx group list [group] [--server] [--verbose]

Lists all groups, or one group's members.

Parameter Short hand Type Required Description
group string No A group to list the members of. Omit it to list all groups.
server -s string No The server address to use.
verbose -v bool No Displays verbose output.

Group remove

vx group remove <group> <users> [--server] [--verbose]

Removes one or more users from a group.

Parameter Short hand Type Required Description
group string Yes The group's name.
server -s string No The server address to use.
users string Yes One or more usernames.
verbose -v bool No Displays verbose output.

Info

vx info [--server] [--verbose]

Shows the server's address and where that address came from, its version, its status and latency, and who you're logged in as. Works without logging in, so it's the first thing to run when something can't connect.

Parameter Short hand Type Required Description
server -s string No The server address to use.
verbose -v bool No Displays verbose output.

Init

vx init [--branch] [--path] [--project] [--template] [--server] [--verbose]

Creates a project on the server, named after the folder, with a default branch, then makes the folder its workspace (a .vx/ folder at its root). Nothing is uploaded until the first vx submit. When it recognizes the project type it also writes a starter .vxignore (see Ignore rules).

Parameter Short hand Type Required Description
branch -b string No The project's default branch. Defaults to main.
path string No The folder to make the workspace. Defaults to the current folder.
project -p string No The project's name. Defaults to the folder's name.
server -s string No The server address to use.
template string No Starter .vxignore to write (e.g. unreal), or none. Detected from the folder by default.
verbose -v bool No Displays verbose output.

Note: The server comes first: if it can't be reached or the name is taken, nothing is created locally. To link a folder to a project that already exists, use vx clone.

Examples

Start a project from the current folder and submit it:

vx init
vx submit -m "First"

Start a project with a different name and no ignore template:

vx init -p shooter --template none

Locks

vx locks [paths] [--parallel] [--server] [--verbose]

Lists who has which files locked on the workspace's branch, and on which machine. See File locking.

Parameter Short hand Type Required Description
parallel int No The number of parallel operations to perform. Defaults to the number of processors.
paths string No Files or folders to show locks for. Defaults to the whole workspace.
server -s string No The server address to use.
verbose -v bool No Displays verbose output.

Examples

See who is working in the maps folder:

vx locks Content/Maps

Login

vx login [server] [--username] [--password-stdin] [--verbose]

Logs in to a server and saves the login in ~/.vertex/credentials for later commands, one login per server. Every command except vx info and vx login needs a login.

Parameter Short hand Type Required Description
password-stdin bool No Reads the password from standard input, for scripts and CI.
server string No The server to log in to. Defaults to the workspace's server, then vx config server.
username -u string No The username. Prompted for when omitted.
verbose -v bool No Displays verbose output.

Note: On Windows the saved token is encrypted with DPAPI; elsewhere the file is readable only by you (mode 600). VX_CONFIG_DIR moves the folder.

Examples

Log in to the default server:

vx login

Log in to a team server as alice:

vx login https://vertex.example.com -u alice

Log in from a CI job:

echo "$VX_PASSWORD" | vx login -u ci-bot --password-stdin

Logout

vx logout [server] [--verbose]

Revokes the saved login on the server and forgets it.

Parameter Short hand Type Required Description
server string No The server to log out of. Defaults to the workspace's server, or http://127.0.0.1:5000.
verbose -v bool No Displays verbose output.

Merge

vx merge <source> [--into] [--message] [--take-source] [--keep-target] [--parallel] [--server] [--verbose]

Merges another branch's changes into the workspace's branch (or into --into) as one revision. It runs entirely on the server, so nothing is downloaded. Every file changed on the source since the last merge between the two branches is taken. It works between any branches that share history: a parent and child in either direction, or siblings. Run vx sync afterwards to get the result. See Branching and merging.

Parameter Short hand Type Required Description
into string No The branch to merge into. Defaults to the workspace's branch.
keep-target bool No For files changed on both branches, keep the target branch's version.
message -m string No Describes the merge revision. Defaults to "Merge into ".
parallel int No The number of parallel operations to perform. Defaults to the number of processors.
server -s string No The server address to use.
source string Yes The branch whose changes to take in.
take-source bool No For files changed on both branches, use the source branch's version.
verbose -v bool No Displays verbose output.

Note: Files changed on both branches refuse the whole merge and are listed, unless --take-source or --keep-target picks a side. Vertex merges whole files, never their content.

Note: Files locked on the target branch block a merge that would change them.

Note: If the target branch has a merge target of its own, the merge carries on down the chain, and every hop is printed.

Examples

Bring a feature branch into the current branch:

vx merge feature-x

Merge it into main from anywhere in the workspace, letting the feature branch win on conflicts:

vx merge feature-x --into main --take-source

Passwd

vx passwd [--server] [--verbose]

Changes your password. It asks for the current password and the new one. Your other devices are logged out; this one stays logged in.

Parameter Short hand Type Required Description
server -s string No The server address to use.
verbose -v bool No Displays verbose output.

Project create

vx project create <name> [--server] [--verbose]

Creates an empty project on the server without making a workspace. Most people want vx init instead, which does both.

Parameter Short hand Type Required Description
name string Yes The project's name.
server -s string No The server address to use.
verbose -v bool No Displays verbose output.

Revert

vx revert <paths> [--parallel] [--server] [--verbose]

Discards local changes. Modified and deleted files get the content they had at the last submit or sync back from the server, moved files go back to where they were, and their locks are released. New files are left alone, because the server has no copy to restore.

Parameter Short hand Type Required Description
parallel int No The number of parallel operations to perform. Defaults to the number of processors.
paths string Yes Files or folders to revert. Use . for every change in the current folder.
server -s string No The server address to use.
verbose -v bool No Displays verbose output.

Warning: Local changes to the reverted files are gone for good. Vertex keeps no local history.

Examples

Throw away changes to one asset:

vx revert Content/Hero.uasset

Throw away every change in the current folder:

vx revert .

Status

vx status [--limit] [--force] [--path] [--parallel] [--server] [--verbose]

Shows files added, modified, deleted and moved since the last submit or sync, and updates locks: changed files are locked, files no longer changed are released, and files others hold become read-only. It trusts each file's size and timestamp and only re-hashes files whose stats changed, so it stays fast on large trees. It still works offline; it just says it couldn't update locks.

Parameter Short hand Type Required Description
force -f bool No Re-hashes every file instead of trusting size and timestamp.
limit int No The maximum number of changes to display. Defaults to 25.
parallel int No The number of parallel operations to perform. Defaults to the number of processors.
path string No A folder inside the workspace to run in. Defaults to the current folder.
server -s string No The server address to use.
verbose -v bool No Displays verbose output.

Note: A file locked by someone else is shown with ! and the command that resolves it, for example ! Modified Maps/City.umap (locked by alice on DESKTOP-7; wait for them to submit it, or run 'vx revert Maps/City.umap' to drop your change).

Submit

vx submit [paths] [--message] [--merge-to] [--parallel] [--server] [--verbose]

Submits the workspace's changes as one revision (#N): every added, modified, deleted and moved file in the current folder (or the named paths), the way vx status lists them. Locks on the submitted files are released.

Parameter Short hand Type Required Description
merge-to string No After submitting, also merge the branch into this one. Files changed on both stop the merge, not the submit.
message -m string Yes What changed, shown in the project's history.
parallel int No The number of parallel operations to perform. Defaults to the number of processors.
paths string No Files or folders to submit. Defaults to every change in the current folder.
server -s string No The server address to use.
verbose -v bool No Displays verbose output.

Note: Refused when a file changed on the server since your last sync (run vx sync, then submit again) or when someone else holds a lock on it.

Note: A submit can hold at most 250,000 files. Submit a folder at a time for more.

What gets uploaded

Each changed file is split into chunks, and only chunks the server doesn't already store are sent. Unchanged parts of a large asset, files that exist elsewhere in the project, and a re-submit after an interrupted upload cost almost nothing. See Storage.

Examples

Submit everything:

vx submit -m "Add jump animation"

Submit one folder:

vx submit -m "New level" Content/Maps

Submit a fix and merge it into main in one step:

vx submit -m "Fix jump" --merge-to main

Sync

vx sync [--revision] [--parallel] [--server] [--verbose]

Gets the files changed on the branch since the last sync, or with --revision the files as of that revision (older or newer). Files that differ are downloaded, reusing any chunks the local copy already has, and files that don't exist at the target are removed.

Parameter Short hand Type Required Description
parallel int No The number of parallel operations to perform. Defaults to the number of processors.
revision -r string No The revision to sync to, e.g. 120 or #120. Defaults to the branch's latest.
server -s string No The server address to use.
verbose -v bool No Displays verbose output.

Note: Local changes are never overwritten. Files changed both locally and on the server are reported as conflicts, with the command that resolves each one.

Examples

Get the latest:

vx sync

Go back to how the branch looked at revision 120:

vx sync -r 120

Unlock

vx unlock <paths> [--parallel] [--server] [--verbose]

Releases locks held somewhere else: your own from a workspace that no longer exists, or anyone's for people with manage access. This workspace's own locks are released by submitting or reverting the files.

Parameter Short hand Type Required Description
parallel int No The number of parallel operations to perform. Defaults to the number of processors.
paths string Yes Files or folders whose locks to release.
server -s string No The server address to use.
verbose -v bool No Displays verbose output.

Examples

Release a map left locked by a machine that was reinstalled:

vx unlock Content/Maps/City.umap

User

vx user <command>

Manages users. User commands are for server admins. Users are never deleted, because history refers to them; disable them instead.

User add

vx user add <name> [--admin] [--display-name] [--email] [--password-stdin] [--server] [--verbose]

Adds a user with an initial password, which is prompted for. They log in with vx login -u <name> and can change it with vx passwd.

Parameter Short hand Type Required Description
admin bool No Makes the user a server admin.
display-name string No The name shown to other people. Defaults to the username.
email string No The user's email address.
name string Yes The user's username.
password-stdin bool No Reads the initial password from standard input instead of prompting.
server -s string No The server address to use.
verbose -v bool No Displays verbose output.

Examples

Add an artist:

vx user add alice --display-name "Alice Smith"

User admin

vx user admin <name> [--remove] [--server] [--verbose]

Makes a user a server admin, or removes it with --remove. Server admins manage users and groups and have admin access to every project.

Parameter Short hand Type Required Description
name string Yes The user's username.
remove bool No Removes server admin instead of granting it.
server -s string No The server address to use.
verbose -v bool No Displays verbose output.

User disable

vx user disable <name> [--server] [--verbose]

Stops a user from logging in and ends their logins. Their revisions and history stay.

Parameter Short hand Type Required Description
name string Yes The user's username.
server -s string No The server address to use.
verbose -v bool No Displays verbose output.

User enable

vx user enable <name> [--server] [--verbose]

Lets a disabled user log in again.

Parameter Short hand Type Required Description
name string Yes The user's username.
server -s string No The server address to use.
verbose -v bool No Displays verbose output.

User list

vx user list [--server] [--verbose]

Lists all users.

Parameter Short hand Type Required Description
server -s string No The server address to use.
verbose -v bool No Displays verbose output.

Clone this wiki locally