# openupm-cli *Read this in other languages: [English](https://github.com/openupm/openupm-cli/blob/master/README.md), [简体中文](https://github.com/openupm/openupm-cli/blob/master/README.zh-cn.md).* ![npm](https://camo.githubusercontent.com/09f369a079660a73122e0e0aa4e7e7a317c85ce374358e38cd22f487c7dacd5f/68747470733a2f2f696d672e736869656c64732e696f2f6e706d2f762f6f70656e75706d2d636c69) ![NPM](https://camo.githubusercontent.com/11af18a1e6c4b8865ff2924a6f35467408b35611e09b45cc54c87bd17ef7b0b6/68747470733a2f2f696d672e736869656c64732e696f2f6e706d2f6c2f6f70656e75706d2d636c69) ![npm](https://camo.githubusercontent.com/545ed06fd28357de059168bfcd5b34a195cd319bfe1f0c455ede2e3db24a4d12/68747470733a2f2f696d672e736869656c64732e696f2f6e706d2f646d2f6f70656e75706d2d636c69) 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 NodeJS. The tool is designed to work with [the OpenUPM registry](https://openupm.com), but can also work with any upm registries, including the official Unity registry. - [openupm-cli](https://github.com/openupm/openupm-cli/raw/master/#openupm-cli) - [How it works](https://github.com/openupm/openupm-cli/raw/master/#how-it-works) - [Installation](https://github.com/openupm/openupm-cli/raw/master/#installation) - [Windows platform troubleshooting](https://github.com/openupm/openupm-cli/raw/master/#windows-platform-troubleshooting) - [Cannot find module 'node:net'](https://github.com/openupm/openupm-cli/raw/master/#cannot-find-module-nodenet) - [China region](https://github.com/openupm/openupm-cli/raw/master/#china-region) - [Commands](https://github.com/openupm/openupm-cli/raw/master/#commands) - [Add packages](https://github.com/openupm/openupm-cli/raw/master/#add-packages) - [Remove packages](https://github.com/openupm/openupm-cli/raw/master/#remove-packages) - [Search packages](https://github.com/openupm/openupm-cli/raw/master/#search-packages) - [View package information](https://github.com/openupm/openupm-cli/raw/master/#view-package-information) - [View package dependencies](https://github.com/openupm/openupm-cli/raw/master/#view-package-dependencies) - [Authenticate with a scoped registry](https://github.com/openupm/openupm-cli/raw/master/#authenticate-with-a-scoped-registry) - [Using token](https://github.com/openupm/openupm-cli/raw/master/#using-token) - [Using basic authentication](https://github.com/openupm/openupm-cli/raw/master/#using-basic-authentication) - [Always auth](https://github.com/openupm/openupm-cli/raw/master/#always-auth) - [Windows Subsystem for Linux (WSL)](https://github.com/openupm/openupm-cli/raw/master/#windows-subsystem-for-linux-wsl) - [Authenticate for the Windows system user](https://github.com/openupm/openupm-cli/raw/master/#authenticate-for-the-windows-system-user) - [Troubleshooting](https://github.com/openupm/openupm-cli/raw/master/#troubleshooting) - [Command options](https://github.com/openupm/openupm-cli/raw/master/#command-options) - [Work with Unity official (upstream) registry](https://github.com/openupm/openupm-cli/raw/master/#work-with-unity-official-upstream-registry) - [Work with proxy](https://github.com/openupm/openupm-cli/raw/master/#work-with-proxy) ## 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 14.18 or above](https://nodejs.org/en/download/). - Install via npm: ``` npm install -g openupm-cli ``` - Or install via [yarn](https://yarnpkg.com/): ``` yarn global add openupm-cli ``` ### Windows platform troubleshooting If npm is not available in your CMD/PowerShell/Git-Bash, please configure your [environment variables](https://stackoverflow.com/questions/27864040/fixing-npm-path-in-windows-8-and-10). ``` # 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 [nodejs 14.18 or above](https://nodejs.org/en/download/). ## China region To use the region CN, replace the command `openupm` with `openupm-cn` or add the option `--cn`. Then the CLI will query both the Unity China region registry (`https://packages.unity.cn`) and the OpenUPM China region registry (`https://package.openupm.cn`). ``` # Region us openupm view com.littlebigfun.addressable-importer # Region cn openupm view com.littlebigfun.addressable-importer --cn openupm-cn view com.littlebigfun.addressable-importer ``` ## Commands ### Add packages ``` openupm add [otherPkgs..] openupm add @ openupm add @git@github.com:... openupm add @https://github.com/... openupm add @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](https://docs.unity3d.com/Manual/cus-tests.html) when importing: ``` openupm --test ``` ### Remove packages ``` openupm remove [otherPkgs...] ``` ### Search packages ``` openupm search ``` 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 ``` ### View package dependencies ``` open deps ``` Using option `--deep` to view dependencies recursively ``` open deps --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 an npm server and store the info to the UPM config file. There are two ways to authenticate with an npm server: - using token (recommended): a server-generated string for the grant of access and publishing rights. - using basic authentication: the `username:password` pair (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 -e -r -p 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 -e -r -p --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 -e -r -p --always-auth i.e. openupm login -u user1 -e user1@example.com -r http://127.0.0.1:4873 --always-auth ``` #### Windows Subsystem for Linux (WSL) By default, the command treats the Windows Subsystem for Linux (WSL) as a Linux system. But if you want to authenticate for the Windows (probably where your Unity installed on), add `--wsl` option. > Known issue: run with `--wsl` option may clear the terminal screen during the process. #### 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 ``` Specify another 3rd-party registry (defaults to the openupm registry) ``` openupm --registry i.e. openupm --registry http://127.0.0.1:4873 ``` Show verbose logging ``` openupm --verbose ... ``` ## Work with Unity official (upstream) registry Most commands can fallback 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](https://forum.unity.com/threads/using-unity-when-behind-a-proxy.69896/).