VRChat.VPM.CLI 0.1.4

CLI

The VRChat Package Manager is available as a Command Line Interface application, for advanced users and automation.

Installation & Updating

You'll need the .NET 6 SDK installed. Then just open a terminal and type:

dotnet tool install --global vrchat.vpm.cli

This will make it available at any command prompt just by typing vpm!

You can always update the tool to the latest version with the command:

dotnet tool update --global vrchat.vpm.cli

You can uninstall it with the command:

dotnet tool uninstall --global vrchat.vpm.cli

To learn more about what's going on, read the .NET Tool Docs.

Projects

VRChat Projects are Unity projects which have the VRChat SDK in them.

new

Creates a new VRChat project from a template

vpm new <projectName> [template] [path]

Arguments

• projectName: The name for the new project. Will have numbers added to it if another project already exists with this name in the target directory.

• template: Optional template to use. If you don't provide one, the barebones "Base" template will be used, which includes only the VRChat Base SDK package. You can use the name of one of the built-in templates, or provide an absolute path to your own template. built-in templates: "Base", "World", "Avatar", "UdonSharp"

• path: Optional absolute path to use when creating the project. If not provided, the current directory will be used.

check project

Checks whether a given name or path points to a compatible VRChat project.

vpm check project [<name>]

Arguments

• name: Optional name of the project to find. If not provided, the current directory will be checked.Otherwise, the following places will be searched:
• Name as absolute path
• Name as relative path from current directory
• Name from list in settings stored as userProjects

If the project is found, its type will be printed to the console.

Returns a 0 if a project is found, and a 1 if it is not.

migrate project

Migrates projects created with the legacy .unitypackage SDKs to the new system if they use the SDK3 Worlds or Avatars unitypackages (SDK2 not supported). They can be Unity 2017, 2018 or 2019 projects. Will also migrate UdonSharp and CyanEmu to the new package-based versions.

vpm migrate project [projectPath]

Arguments

• projectPath: The path to the unity project you want to migrate.

Options

• --in-place: Migrate project in place instead of creating a copy. Not recommended unless you have your own backup of the project

If the project is found and it can be migrated it will be automatically upgraded to the new system.

Returns a 0 if a project is found and it can be migrated, and a 1 if it is not found or can't be migrated.

Packages

Packages are code and assets in a portable format, stored in git repositories and pulled into your project by the Unity Editor.

check package

Reports the info from a package, or tells if you if it is not found/invalid.

vpm check package <name>

Arguments

• name: The package to add. This can be the unique name of any package in the Official or Curated package listings, like com.vrchat.worlds or com.merlinvr.udonsharp, or it can be a relative or absolute path to a local package.

Examples

• vpm check com.vrchat.avatars
  • Prints info about the official Avatars package
• vpm check "C:/MyPackages/MirrorExploder"
  • Prints info about the local package "MirrorExploder".

add package

Adds a VPM package to an existing Project

vpm add <packageName> [-p <project>]

Arguments

• packageName: The package to add. This can be the unique name of any package in the Official or Curated package listings, like com.vrchat.worlds or com.merlinvr.udonsharp, or it can be a relative or absolute path to a local package.

Options

• -p|--project: Specifies the project to which the package will be added. If no argument is provided, the method will look in the current directory. If provided, the value can be an absolute or relative path to a Unity Project, or the name of a project which you have added to your userProjects list.

Examples

• vpm add com.vrchat.avatars
  • Adds the official Avatars package to the project in the current directory.
• vpm add "C:/MyPackages/MirrorExploder" "../MyProjectDir"
  • Adds my local package "MirrorExploder" to the project which is one directory up from the current working directory.

Templates

Templates are barebones VRChat projects which can be used as a starting point for new projects, pulling in your favorite packages, prefabs and tools to get running quickly.

install templates

Installs the latest version of the VRChat templates to Documents/VRChatCreatorCompanion/VRCTemplates, overwriting files that are there. Useful if you're using the CLI without having installed the VCC GUI.

vpm install templates

Note that this will clear out the existing template first - user templates should be put into Documents/VRChatCreatorCompanion/Templates instead.

list templates

Prints out the names and paths of the Official VRChat Templates, and the paths of the installed User Templates.

vpm list templates

check template

Reports the version from a template, or tells if you if it is not found/invalid.

vpm check template <template>

Arguments

• template: The template to check. This can be the displayName of any built-in template or an absolute path to your own project template.

built-in templates: "Base", "World", "Avatar", "UdonSharp"

Repos

Repos are listings of Packages. You always have access to the Official and Curated repos, and you can add your own Community repos.

list repos

Lists all the sources available for loading packages. This includes the Official and Curated package listing, as well as any User repos add to the Settings.

vpm list repos

add repo

Adds a local or remote repo of packages.

vpm add repo <path>

Arguments

• path: The path to add. It can be an absolute path to a local json file, or a url to a remote json file. If it's a local file, it must exist to be added. If it's a remote file, it must connect within 10 seconds of the request to be added.

Returns 0 if the repo was added and 1 if it was not.

new repo

Create a new json file for a package listing.

vpm new repo [path] [--name MyName] [--author email@domain.com]

** Arguments**

• path: The path at which to create the file, can be absolute or relative to current directory. If not provided, it will be created in the default sources directory (~User/Documents/VRChatCreatorCompanion/Sources) and given a GUID name like 4d6ffbe7-fe91-449f-ae7e-c8688e315a83.json.

Options

• -n|--name: The name for the source, like "VRChat Official Packages" or "Momo's Messy Mix"
• -a|--author: An email address at which people can contact you with questions.

remove repos

Removes all the repos from your settings Returns 0 if the file was created and 1 if it was not.

vpm remove repos

Requirements

The VCC and VPM require a few things to be installed in order to run properly. These commands can help you quickly get your machine or a cloud build set up.

check git

Checks for git by running git --version in the background. It will print the version if found.

vpm check git

returns 0 if git is installed and 1 if it is not.

install git

Installs a recent version of git with LFS for Windows

vpm install git

Specifically, it downloads the git installer from

https://github.com/git-for-windows/git/releases/download/v2.34.1.windows.1/Git-2.34.1-64-bit.exe

and runs it with these args:

/SILENT /NORESTART /NOCANCEL /SP- /CLOSEAPPLICATIONS /RESTARTAPPLICATIONS /LOG=\"{_gitInstallLogLocation}\" /COMPONENTS=\"gitlfs,icons,assoc\"

It will write an install log to the user's temporary folder with the filename git-install-log.txt.

returns 0 if git was installed and 1 if it was not.

check hub

On Windows, checks if there is a registry key for the Unity Hub at HKEY_LOCAL_MACHINE\SOFTWARE\Classes\unityhub\DefaultIcon. On Mac, checks if there is a file at /Applications/Unity Hub.app/Contents/MacOS/Unity Hub.

vpm check hub

Returns 0 if it is found and 1 if it is not.

install hub

Installs Unity Hub 3.0 for Windows

vpm install hub

Specifically, it downloads the hub installer from

https://public-cdn.cloud.unity3d.com/hub/prod/UnityHubSetup.exe

and runs it with the argument /S to install silently.

Returns 0 if the Hub was installed and 1 if it was not.

check unity

Checks if there is a valid installation of Unity installed at the path specified in the Settings as pathToUnityExe. If the Unity Hub is installed, runs the hub in a background process to list any Unity Editors using the args:

-- --headless editors -i

Updates the Settings with the paths to the Unity Editors if found.

vpm check unity

Returns 0 if a compatible version of Unity is specified there and 1 if it is not.

install unity

Installs a compatible version of the Unity Editor for Windows with Android Build Support

vpm install unity

Specifically, it runs the Unity Hub with these args:

-- --headless install -v 2019.4.31f1 -c bd5abf232a62 -m android

returns 0 if Unity was installed and 1 if it was not.

list unity

Lists the Unity Editors found on the current system.

vpm list unity

Checks:

• Windows Registry
• Unity Hub (by running it with the args -- --headless editors -i
• Subdirectories of the Unity Hub

Mac and Linux Support

The only fully-supported platform at the moment is Windows 10. However, we are working to make the vpm tool available to Mac and Linux users.

Mac Setup

1. Follow the directions under Installation & Updating above.
2. Install Unity Hub for Mac and then Unity 2019.4.31f1.
3. Install Git LFS and restart your machine.
4. Open a terminal and use the vpm check git command to make sure that git is installed (should be installed by default on a Mac). If not, take a look at Installing on macOS and follow the instructions there.
5. Back in a terminal, run vpm install templates to install the latest VRChat project templates.
6. Run vpm check hub to find and save the location of Unity Hub. For now, we assume it has been installed to its default location of /Applications/Unity Hub.app/Contents/MacOS/Unity Hub. If this is not the case, you'll need to open your settings file and set the pathToUnityHub to the correct absolute path manually. Make sure to target the executable inside of the UnityHub.app as shown in the default path.
7. Run vpm check unity to find and save the location of the Unity Editor. VPM will use the Hub to find and save the path(s), so make sure VPM can find the Hub first.

That's it! You should be able to make new projects from templates, add packages to projects and most other functions. You can file a Canny for any methods that don't work.

Linux Setup

The system is completely untested on Linux distributions at this point, but may work anyway due to the work done for the Mac version. The VPM will not be able to find your Unity Hub or Unity Editor paths however, so you'll need to update your settings.json file to set them manually for now.