Tjmadonna/clt documentation

docs/clt/index.md

@@ -28,7 +28,7 @@ Commands: One of the following commands is required:
    whoami                   Displays the information of the user who is
                             currently logged in.  If no user is logged
                             a message will be displayed prompting the user
-			                to log in.
+			                to login.
 
   -h or --help              Show this help message.
 
@@ -61,21 +61,27 @@ can be found [here](generate-manifest.html)
 
 #### Login
 
-A one-time login is required for any download session.  For any non-public data, you must login with your HuBMAP authorized account, for publicly available data you can log in with any account accepted on the login form (Google and OrCID accepted) as well.  To login issue the following command on the command line:
+A one-time login is required for any download session. For any non-public data, you must log in with your HuBMAP authorized account, for publicly available data you can log in with any account accepted on the login form (Google and OrCID accepted) as well. To log in, issue the following command on the command line:
 
-```
+```bash
 hubmap-clt login
 ```
 
-Similarly, log out with the command:
+By default, login will automatically open a browser window to complete authentication. If you are in a headless environment (e.g. a remote server without a browser), use the `--no-browser` flag. This will display a URL in the terminal that you can copy and open in a browser on another device to complete the login:
 
+```bash
+hubmap-clt login --no-browser
 ```
+
+Similarly, log out with the command:
+
+```bash
 hubmap-clt logout
 ```
 
 To check the identity of the currently logged in user, enter the command:
 
-```
+```bash
 hubmap-clt whoami
 ```
 
@@ -102,6 +108,12 @@ hubmap-clt transfer manifest.txt --destination data/hubmap/rna-seq
 
 Similarly, if you give the path/name to a directory that doesn't exist, it will be created. Be mindful of typos.
 
+An optional `--from-protected-space` flag can be specified to download protected data belonging to a published protected `Dataset`. By default, the HuBMAP CLT will download public data only. The user must have access to the protected data in order for the transfer to be successful.
+
+```bash
+hubmap-clt transfer manifest.txt --from-protected-space
+```
+
 <a name="gcp"></a>
 
 #### Note about Globus Connect Personal

docs/clt/install-hubmap-clt.md

@@ -14,7 +14,7 @@ In order to download any content from Globus, users must install **_Globus Conne
 creates a globus "Endpoint" locally. Downloads take the form of transfers from the desired Collection to the endpoint 
 created on the local machine. Instructions on installing **_Globus Connect Personal_** can be found <a href="https://www.globus.org/globus-connect-personal">Here</a>
 
-During setup, users will have the opportunity to name their Endpoint and login with their Globus Credentials
+During setup, users will have the opportunity to name their Endpoint and log in with their Globus Credentials
 
 #### **_IMPORTANT NOTE ABOUT GLOBUS CONNECT PERSONAL_**
 
@@ -35,37 +35,97 @@ Here we can see precisely where the globus downloads are mounted. If a specific
 
 <img src="../images/globususername.PNG" alt="GCP Home Location" width="500"/>
 
-
 #### Installing the HuBMAP CLT
 
 The HuBMAP CLT is available as a part of a Python package called `atlas-consortia-clt`.
   - Python 3 is required to run the HuBMAP CLT, an installer for it can be downloaded [here](https://www.python.org/downloads/).
   - It is recommended that you create a new Python virtual environment first with `python3 -m venv /path/to/new/virtual/environment`, more information on Python virtual environments is available [here](https://docs.python.org/3/library/venv.html).
-  - To install the Atlast Consortia CLT run the pip command shown below after installing Python and creating and activating a new Python virtual environment.
+  - To install the HuBMAP CLT run the pip command shown below after installing Python and creating and activating a new Python virtual environment.
+
+Note: The HuBMAP CLT requires Python 3.9 or above.
+
+Note: Installation will also install other requirements needed by the the HuBMAP CLT, including the Globus [Command Line Tool](https://docs.globus.org/cli/). The Globus command line tool is a separate tool from **_Globus Connect Personal_**.
+
+The HuBMAP CLT can be installed using multiple methods:
+
+##### pip
 
+Install the HuBMAP CLT globally using pip:
 ```bash
 pip install atlas-consortia-clt
 ```
 
-This will also install other requirements needed by the the HuBMAP CLT including the Globus [Command Line Tool](https://docs.globus.org/cli/)
+##### pip with a virtual environment
 
-The globus command line tool is a separate tool from **_Globus Connect Personal_**. It is likely that users may have to
-log in separately through **_Globus CLI_**. To see if a user is currently logged in, use the command:
+Installing in a virtual environment keeps the HuBMAP CLT and its dependencies isolated from other Python projects.
 
+**macOS/Linux:**
 ```bash
-hubmap-clt whoami
+python3 -m venv clt-env # creates virtual environment named clt-env in the current directory
+source clt-env/bin/activate # activates the virtual environment
+pip install atlas-consortia-clt
+```
+
+**Windows:**
+```bash
+python -m venv clt-env # creates virtual environment named clt-env in the current directory
+clt-env\Scripts\activate # activates the virtual environment
+pip install atlas-consortia-clt
+```
+
+To use the HuBMAP CLT in the future, activate the virtual environment first:
+
+**macOS/Linux:**
+```bash
+source clt-env/bin/activate
 ```
 
-If a user is logged in, their username will be displayed. If not logged in, users will be prompted to login with the
-following command: 
+**Windows:**
+```bash
+clt-env\Scripts\activate
+```
+
+To deactivate the virtual environment, run the following command on any platform:
+```bash
+deactivate
+```
+
+##### pipx
+
+[pipx](https://pipx.pypa.io) installs the HuBMAP CLT in its own isolated environment and automatically exposes the `hubmap-clt` commands on your `PATH`, without affecting other Python packages.
+
+Install pipx if you don't have it. Check the [pipx documentation](https://pipx.pypa.io/stable/#install-pipx) for detailed installation instructions.
+
+Then install the HuBMAP CLT. The HuBMAP CLT relies on the `globus-cli` package and must also be installed via pipx.
+```bash
+pipx install atlas-consortia-clt globus-cli
+```
+
+To upgrade:
+```bash
+pipx upgrade atlas-consortia-clt globus-cli
+```
+
+#### Log in to the HuBMAP CLT
+
+A one-time login is required for any download session. For non-public data, you must log in with your HuBMAP account. For publicly available data, you can log in with any account accepted by the login form (Google and ORCID). Login can be initiated using the following command:
 
 ```bash
 hubmap-clt login
 ```
 
-The Globus login screen will open in the default web browser. Follow login instructions. 
+By default, login will automatically open a browser window to complete authentication. If you are in a headless environment (e.g. a remote server without a browser), use the `--no-browser` flag. This will display a URL in the terminal that you can copy and open in a browser on another device to complete the login:
+
+```bash
+hubmap-clt login --no-browser
+```
+
+You can check if you are currently logged in with the following command:
+
+```bash
+hubmap-clt whoami
+```
 
 #### Using the HuBMAP CLT
 
-At this point, user should be set up and ready to use the HuBMAP Command Line Transfer tool. Detailed instructions of 
-its usage can be found [here](index.html).
+At this point, you should be set up and ready to use the HuBMAP Command Line Transfer tool. Detailed instructions of its usage can be found [here](index.html).