docs: update docs on pat usage for cli add-pat cmd

Author: RMCrean

docs/user-guides/account-management.md

@@ -67,6 +67,9 @@ To create a PAT:
     - **Task history** — Allow you to use the token to view your entire task history, not filtered by project.
 4. Click **Create**. Copy the token immediately — it is shown **only once** and cannot be recovered afterwards.
 
+After creating your PAT, the website will show you two options on how to store and use the PAT. For more advice on how to use a PAT in scripts and HPC jobs, see [Using DivBase Programmatically](./using-divbase-programmatically.md#use-personal-access-tokens-to-authenticate-programmatically).
+
 You can have up to **5 active tokens** at a time. To revoke a token, click **Revoke** next to it on the Personal Access Tokens page.
 
-For how to use a PAT in scripts and HPC jobs, see [Using DivBase Programmatically](./using-divbase-programmatically.md#use-personal-access-tokens-to-authenticate-programmatically).
+!!! tip "Scope your token to what the job needs and when you need it for"
+    When creating the PAT, restrict it to the specific project(s) you need it for. Consider also setting an appropriate expiry date for the token. You can always revoke the token immediately if needed from the DivBase website.

docs/user-guides/using-divbase-programmatically.md

@@ -4,49 +4,59 @@ Below is a set of tips for users who want to use DivBase in scripts/pipelines/pr
 
 If you have any tips or suggestions to add to this page or any desired features, please let us know!
 
-## Use Personal Access Tokens to Authenticate programmatically
+## Use Personal Access Tokens to authenticate programmatically
 
-For scripts, pipelines, and HPC jobs the recommended approach is to use a **Personal Access Token (PAT)**. A PAT is a static bearer token that you create once via the website and pass to `divbase-cli` via an environment variable. When using a PAT, there is no login step and no password storage required.
+For scripts, pipelines, and HPC jobs the recommended approach is to use a **Personal Access Token (PAT)**. A PAT is a static bearer token that you create once via the website. When using a PAT, there is no login step and no password storage required.
 
-See [Account Management — Personal Access Tokens](./account-management.md#personal-access-tokens) for how to create/and remove PATs.
+See [Account Management — Personal Access Tokens](./account-management.md#personal-access-tokens) for how to create and revoke PATs.
 
-Once you have a token, set the `DIVBASE_API_PAT` environment variable to it. `divbase-cli` will automatically use it in every request.
+You can store/use a PAT in two ways
 
-!!! question "What if I have both an active login session and a Personal Access Token set?"
-    `divbase-cli` prioritises an active login session over a PAT. If you have both, the CLI will use the active session and ignore the PAT. To use the PAT, you would need to run `divbase-cli auth logout` first.
+### Option 1 — Let `divbase-cli` handle storing the PAT (recommended)
+
+After creating a PAT on the website, store it on your device by copy pasting the pre-filled commands shown on the website, it will look something like this:
 
 ```bash
-export DIVBASE_API_PAT="divbase_pat_your_token_here"
-divbase-cli files ls
+# with an expiry date:
+divbase-cli auth add-pat "my-pat-name" --expires UNIX_TIMESTAMP
+# or without an expiry date:
+divbase-cli auth add-pat "my-pat-name"
+```
+
+You will be prompted to paste the token value. It is then stored securely in your OS keyring (or in a restricted file if no keyring is available) and used automatically on every subsequent `divbase-cli` command.
+
+```bash
+divbase-cli auth pat-info   # show name and expiry of the stored PAT
+divbase-cli auth rm-pat     # remove the stored PAT from this device
 ```
 
-When `DIVBASE_API_PAT` is set, `divbase-cli` does not need you to be logged in.
+!!! info "This strategy works on HPC clusters"
+    On the login node with divbase-cli [installed as we recommend](./installation.md), store the PAT as described above. The token will be available to all your jobs running on the cluster, without needing to worry about setting any environment variables in your job scripts.
 
-### Example: Slurm job script
+### Option 2 — Environment variable
 
-The cleanest way to use a PAT in a SLURM job is to store the token in a restricted file and load it at job start:
+Set `DIVBASE_API_PAT` in your shell or job script:
 
 ```bash
-echo "divbase_pat_your_token_here" > ~/.divbase_pat
-chmod 600 ~/.divbase_pat  # only readable/writeable by the owner
+export DIVBASE_API_PAT="divbase_pat_your_token_here"
+divbase-cli files ls
 ```
 
-Then in your SLURM script:
+You may prefer this if you want explicit per-job control of which token is used.
 
-```bash
-#!/bin/bash
-#SBATCH --job-name=my_divbase_job
-#SBATCH --time=24:00:00
-# ....
+1. Store it securely on your device using `divbase-cli auth add-pat` (recommended and works on HPC clusters!)
+2. Set it as an environment variable `DIVBASE_API_PAT` (can give you more control over which token is used when)
 
-export DIVBASE_API_PAT=$(cat ~/.divbase_pat)
+!!! question "What if I have both an active login session and a personal access token set?"
+    `divbase-cli` follows this priority order:
 
-# Download the files you need
-divbase-cli files download my_data.vcf.gz
-```
+    1. **Active login session** (from `divbase-cli auth login`) — highest priority
+    2. **`DIVBASE_API_PAT` environment variable**
+    3. **CLI-stored PAT** (from `divbase-cli auth add-pat`)
+
+    To use a PAT when you are also logged in, run `divbase-cli auth logout` first.
 
-!!! tip "Scope your token to what the job needs and when you need it for"
-    When creating the PAT, restrict it to the specific project(s) you need it for. Consider also setting an appropriate expiry date for the token. You can always revoke the token immediately if needed from the DivBase website.
+    Your logged in account will have the same or more permissions that your PATs, this is why we follow this order.
 
 ## Parse divbase-cli files ls/info output programmatically