add login doc page

README.md

@@ -17,12 +17,6 @@ The tool is designed to work with [the OpenUPM registry](https://openupm.com), b
     - [Search packages](#search-packages)
     - [View package information](#view-package-information)
     - [View package dependencies](#view-package-dependencies)
-    - [Authenticate with a scoped registry](#authenticate-with-a-scoped-registry)
-      - [Using token](#using-token)
-      - [Using basic authentication](#using-basic-authentication)
-      - [Always auth](#always-auth)
-      - [Authenticate for the Windows system user](#authenticate-for-the-windows-system-user)
-      - [Troubleshooting](#troubleshooting)
     - [Command options](#command-options)
   - [Work with proxy](#work-with-proxy)
   - [Contributors](#contributors)
@@ -124,90 +118,6 @@ openupm deps com.my.package
 
 Checkout [the commands doc page](./docs/cmd-deps.md) for more information.
 
-### 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: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 <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.

docs/cmd-login.md

@@ -0,0 +1,66 @@
+# `openupm login`
+
+The `login` command authenticates with a remote registry and stores login credentials in your `.upmconfig.toml` for future requests.
+
+There are two ways to authenticate with a registry 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.
+
+```sh
+openupm login -r https://packages.my-registry.com -u user123 -p ****** -e user123@mail.com
+```
+
+Tokens will be saved in the users local `.npmrc` file.
+
+This command has the aliases `adduser` and `add-user`. On this doc page we will always use the primary command name `login`.
+
+## Options
+
+### Registry
+
+Specify the registry with which you want to authenticate. You can use the `--registry` or `-r` option.
+
+### Basic vs token
+
+By default the `login` command uses token-based authentication. If you want to use basic authentication use the `--basic-auth` option.
+
+### Credentials
+
+In order to authenticate you must specify 3 credentials:
+
+- username (--username/-u)
+- password (--password/-p)
+- email (--email/-e)
+
+If you omit any of these, you will be prompted interactively. This can be useful since when entering the password in the interactive prompt it will be obfuscated.
+
+### Always auth
+
+Some registry servers are configured to always require authentication, even for `GET` requests. If this is the case for the registry you are authenticating for you should specify the `--always-auth` option.
+
+### Windows system-user authentication
+
+By default the authentication information will be saved to the users local `.upmconfig.toml`. If you want to save it in the Windows system users config file instead, run with the `--system-user` option. For more information check out the corresponding [article](./help-system-user.md).
+
+## Troubleshooting
+
+You can verify the authentication in your `.upmconfig.toml` file. Please read the [official documentation](https://docs.unity3d.com/Manual/upm-config.html) if you are unsure where to find the file.
+
+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/`.