Awesome
openupm-cli
The command-line tool to maintain the Unity manifest file for 3rd-party upm registries, offering a similar but lighter experience like npm or yarn for Node.js.
The tool is designed to work with the OpenUPM registry, but can also work with any upm registries, including the official Unity registry.
- openupm-cli
How it works
The command-line tool installs the 3rd-party registry as a scoped registry and maintains the Packages/manifest.json file when adding/removing packages. If the manifest file is modified, the Unity Package Manager will detect the changes and try to resolve the package dependencies.
Notice: the command-line tool does not directly install/uninstall package tarballs, at least for now.
Installation
-
Requires nodejs 18 or above.
-
Install via npm:
npm install -g openupm-cli -
Or install via yarn:
yarn global add openupm-cli
Windows platform troubleshooting
If npm is not available in your CMD/PowerShell/Git-Bash, please configure your environment variables.
# for npm
c:\Program Files\nodejs
# for npm global bin
C:\Users\{yourName}\AppData\Roaming\npm
Cannot find module 'node:net'
internal/modules/cjs/loader.js:818
throw err;
^
Error: Cannot find module 'node:net'
Please install Node.js 18 or above.
Commands
Add packages
openupm add <pkg> [otherPkgs..]
openupm add <pkg>@<version>
openupm add <pkg>@git@github.com:...
openupm add <pkg>@https://github.com/...
openupm add <pkg>@file:...
The add command adds the package to the manifest.json and configures the scope registry by adding scopes for the package and its dependencies that available on the registry.
The add command doesn't verify package or resolve dependencies for Git, HTTPS, and file protocol. See https://docs.unity3d.com/Manual/upm-git.html for more examples of the version string.
The add command fails if the package is not qualified:
- the package has a missing dependency
- the package requires a non-existed dependency version
- the package requires a higher editor version
You shall either resolve these issues manually or add the option -f to continue.
You can also add testables when importing:
openupm --test <pkg>
Remove packages
openupm remove <pkg> [otherPkgs...]
Search packages
openupm search <keyword>
If the registry doesn't support the new search endpoint, it will fall back to the old /-/all endpoint. If no package was found, it will search the Unity official registry instead.
Because the upstream Unity registry doesn't support the search endpoint as of December 2019, the search command will only query the current registry.
View package information
openupm view <pkg>
View package dependencies
open deps <pkg>
Using option --deep to view dependencies recursively
open deps <pkg> --deep
Authenticate with a scoped registry
Starting from Unity 2019.3.4f1, you can configure the.upmconfig.toml file to authenticate with a scoped registry. The openupm login command helps you authenticate with a npm server and store the info to the UPM config file.
There are two ways to authenticate with a npm server:
- using token (recommended): a server-generated string for the grant of access and publishing rights.
- using basic authentication: the
username:passwordpair (base64 encoded) is stored to authenticate with the server on each request.
After login, all openupm-cli commands will use .upmconfig.toml configuration to authenticate with your private scoped registry.
Using token
openupm login -u <username> -e <email> -r <registry> -p <password>
i.e.
openupm login -u user1 -e user1@example.com -r http://127.0.0.1:4873
If you don't provide a username, email, or password, it will prompt you to input the value. If your npm server doesn't require an email field, you can provide a dummy one like yourname@example.com. Notice that requesting a new token is not meant to invalidate old ones for most NPM servers.
For the npm server to allow user creation via CLI, providing a new username will create a new user with the information you just provided.
The token is also stored in the .npmrc file for convenience.
Using basic authentication
Adding --basic-auth option to use basic authentication.
openupm login -u <username> -e <email> -r <registry> -p <password> --basic-auth
i.e.
openupm login -u user1 -e user1@example.com -r http://127.0.0.1:4873 --basic-auth
Notice that your username and password is not verified during the login command, but simply stored in the .upmconfig.toml file. Because verify the password against your npm server will generate a token, which is not what you want here. Please type your password carefully.
Unlike using the token, .npmrc lacks syntax to support multiple registries for basic authentication. Hence, the .npmrc is not updated for the basic authentication.
Always auth
Adding --always-auth option if tarball files are hosted on a different domain other than the registry domain.
openupm login -u <username> -e <email> -r <registry> -p <password> --always-auth
i.e.
openupm login -u user1 -e user1@example.com -r http://127.0.0.1:4873 --always-auth
Authenticate for the Windows system user
Make sure you have the right permission, then add --system-user option to authenticate for the Windows system user.
Troubleshooting
You can verify the authentication in .upmconfig.toml file:
- Windows:
%USERPROFILE%/.upmconfig.toml - Windows (System user) :
%ALLUSERSPROFILE%Unity/config/ServiceAccounts/.upmconfig.toml - MacOS and Linux:
~/.upmconfig.toml
For token, it will look like:
[npmAuth."http://127.0.0.1:4873"]
email = "email address"
alwaysAuth = false
token = "token string"
For basic authentication, it will look like:
[npmAuth."http://127.0.0.1:4873"]
email = "email address"
alwaysAuth = true
_auth = "base64 string"
Notice that the registry address should match exactly with your manifest.json. The last slash is always trimmed. i.e. http://127.0.0.1:4873 instead of http://127.0.0.1:4873/.
Learn more about authentication at https://forum.unity.com/threads/npm-registry-authentication.836308/
Command options
The cli assumes the current working directory (CWD) is the root of a Unity project (the parent of the Assets folder). However, you can specify the CWD.
openupm --chdir <unity-project-path>
Specify another 3rd-party registry (defaults to the openupm registry)
openupm --registry <registry-url>
i.e.
openupm --registry http://127.0.0.1:4873
Show verbose logging
openupm --verbose ...
Work with Unity official (upstream) registry
Most commands can fall back to Unity upstream registry if necessary, to make it easier to mix the official registry with a 3rd-party registry. i.e.
$ openupm add com.unity.addressables com.littlebigfun.addressable-importer
added: com.unity.addressables@1.4.0 # from unity registry
added: com.littlebigfun.addressable-importer@0.4.1 # from openupm registry
...
Turn off Unity official (upstream) registry
openupm --no-upstream ...
Work with proxy
OpenUPM-CLI supports HTTP, HTTPS, or SOCKS proxy specified by the http_proxy environment variable.
http_proxy="http://127.0.0.1:8080" openupm ...
You may need to set both http_proxy and https_proxy environment variables at the system-level to enable Unity work with a proxy.