Repository navigation
Commands
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. |
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.
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
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. |
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-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.
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
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.
Switch to a feature branch:
vx checkout feature-x
vx clear
Clears the console window. vx cls does the same. Mostly useful in the interactive session (vx with no command).
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.
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
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. |
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
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.
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. |
Add two artists:
vx group add artists alice bob
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. |
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.
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. |
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. |
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. |
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.
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
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. |
See who is working in the maps folder:
vx locks Content/Maps
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.
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
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. |
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 |
| 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.
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
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. |
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. |
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.
Throw away changes to one asset:
vx revert Content/Hero.uasset
Throw away every change in the current folder:
vx revert .
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).
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.
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.
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
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.
Get the latest:
vx sync
Go back to how the branch looked at revision 120:
vx sync -r 120
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. |
Release a map left locked by a machine that was reinstalled:
vx unlock Content/Maps/City.umap
vx user <command>
Manages users. User commands are for server admins. Users are never deleted, because history refers to them; disable them instead.
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. | |
| 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. |
Add an artist:
vx user add alice --display-name "Alice Smith"
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. |
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. |
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. |
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. |