Add documentation for configuring the CLI on a new machine

docs/miscellaneous/environments.md

@@ -4,13 +4,15 @@ _WARNING: you are on the master branch, please refer to the docs on the branch t
 
 The `cortex` CLI can be used to deploy models locally and/or to any number of clusters. Environments are used to select which cluster to use for a `cortex` command. An environment contains the information required to connect to a cluster (e.g. AWS credentials and Cortex operator URL).
 
-By default, the CLI ships with a single environment named `local`. This is the default environment for all Cortex commands (other than `cortex cluster` commands), which means that APIs will be deployed locally by default.
-
-Some cortex commands (i.e. `cortex cluster` commands) only apply to cluster environments. Unless otherwise specified by the `-e`/`--env` flag, `cortex cluster` commands create/use an environment named `aws`. For example `cortex cluster up` will configure the `aws` environment to connect to your new cluster. You may interact with this cluster by appending `--env aws` to your `cortex` commands.
+## Example: `aws` only
 
-If you accidentally delete or overwrite one of your cluster environments, running `cortex cluster info --env ENV_NAME` will automatically update the specified environment to interact with the cluster.
-
-You can list your environments with `cortex env list`, change the default environment with `cortex env default`, delete an environment with `cortex env delete`, and create/update an environment with `cortex env configure`.
+```bash
+cortex cluster up       # configures the aws env; same as `cortex cluster up --env aws`
+cortex env default aws  # sets aws as the default env
+cortex deploy           # uses aws env; same as `cortex deploy --env aws`
+cortex logs my-api      # uses aws env; same as `cortex logs my-api --env aws`
+cortex delete my-api    # uses aws env; same as `cortex delete my-api --env aws`
+```
 
 ## Example: `local` only
 
@@ -37,16 +39,6 @@ cortex deploy             # uses aws env; same as `cortex deploy --env aws`
 cortex deploy --env local
 ```
 
-## Example: only `aws`
-
-```bash
-cortex cluster up       # configures the aws env; same as `cortex cluster up --env aws`
-cortex env default aws  # sets aws as the default env
-cortex deploy           # uses aws env; same as `cortex deploy --env aws`
-cortex logs my-api      # uses aws env; same as `cortex logs my-api --env aws`
-cortex delete my-api    # uses aws env; same as `cortex delete my-api --env aws`
-```
-
 ## Example: multiple clusters
 
 ```bash
@@ -76,3 +68,31 @@ cortex deploy --env cluster2
 cortex logs my-api --env cluster2
 cortex delete my-api --env cluster2
 ```
+
+## Example: configure `cortex` CLI to connect to an existing cluster
+
+If you are installing the `cortex` CLI on a new computer, you can configure it to access an existing Cortex cluster.
+
+If you have access to the cluster configuration file which you used to create your cluster, running `cortex cluster info` on your new machine will automatically configure your CLI:
+
+```bash
+# configure the aws environment to connect to the cluster specified in cluster.yaml
+cortex cluster info --config cluster.yaml --env aws
+```
+
+If for some reason this doesn't work, or you don't have access to your cluster configuration file, you can configure the CLI manually:
+
+```bash
+# this will prompt for the necessary configuration
+cortex env configure
+```
+
+## Environments overview
+
+By default, the CLI ships with a single environment named `local`. This is the default environment for all Cortex commands (other than `cortex cluster` commands), which means that APIs will be deployed locally by default.
+
+Some cortex commands (i.e. `cortex cluster` commands) only apply to cluster environments. Unless otherwise specified by the `-e`/`--env` flag, `cortex cluster` commands create/use an environment named `aws`. For example `cortex cluster up` will configure the `aws` environment to connect to your new cluster. You may interact with this cluster by appending `--env aws` to your `cortex` commands.
+
+If you accidentally delete or overwrite one of your cluster environments, running `cortex cluster info --env ENV_NAME` will automatically update the specified environment to interact with the cluster.
+
+You can list your environments with `cortex env list`, change the default environment with `cortex env default`, delete an environment with `cortex env delete`, and create/update an environment with `cortex env configure`.