Add authentication how-to

Author: daniel-thom

docs/src/SUMMARY.md

@@ -32,6 +32,7 @@
   - [Cancel a Workflow](./core/how-to/cancel-workflow.md)
   - [View Job Logs](./core/how-to/view-job-logs.md)
   - [Debug a Failed Job](./core/how-to/debug-failed-job.md)
+  - [Set Up Authentication](./core/how-to/set-up-authentication.md)
   - [Check Resource Utilization](./core/how-to/check-resource-utilization.md)
   - [View Resource Plots](./core/how-to/view-resource-plots.md)
   - [Parameterize Jobs with Files](./core/how-to/parameterize-with-files.md)

docs/src/core/how-to/index.md

@@ -6,6 +6,7 @@ Step-by-step guides for common tasks.
 - [Cancel a Workflow](./cancel-workflow.md) - Stopping running workflows
 - [View Job Logs](./view-job-logs.md) - Accessing job output
 - [Debug a Failed Job](./debug-failed-job.md) - Troubleshooting failures
+- [Set Up Authentication](./set-up-authentication.md) - Saving credentials for CLI access
 - [Check Resource Utilization](./check-resource-utilization.md) - Monitoring resource usage
 - [View Resource Plots](./view-resource-plots.md) - Visualizing resource metrics
 - [Parameterize Jobs with Files](./parameterize-with-files.md) - Using file-based parameters

docs/src/core/how-to/set-up-authentication.md

@@ -0,0 +1,77 @@
+# How to Set Up Authentication
+
+Configure your Torc credentials so that CLI commands authenticate automatically.
+
+## Prerequisites
+
+Your server administrator must have enabled authentication on the Torc server. If you receive
+"Authentication required" errors, follow the steps below.
+
+## Step 1: Generate a Password Hash
+
+Run `torc-htpasswd hash` on your machine. It prompts for your password securely (nothing appears on
+screen):
+
+```bash
+torc-htpasswd hash
+```
+
+```
+Password for 'alice':
+Confirm password for 'alice':
+Hashing password (cost=12)...
+alice:$2b$12$xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+Send the line above to your server administrator.
+```
+
+The hash is safe to share — it cannot be used to recover your password.
+
+## Step 2: Send the Hash to Your Administrator
+
+Send the output line (`alice:$2b$12$...`) to your server administrator through any channel (email,
+Slack, etc.). They will add it to the server's htpasswd file.
+
+## Step 3: Save Your Password Persistently
+
+**Create the credentials file** using `read -s` so the password never appears on screen or in shell
+history:
+
+```bash
+mkdir -p ~/.config/torc
+(
+  read -s -p "Enter Torc password: " _pw && echo
+  printf 'export TORC_PASSWORD="%s"\n' "$_pw"
+) > ~/.config/torc/credentials
+chmod 600 ~/.config/torc/credentials
+```
+
+If your username on the server differs from your system `$USER`, also add it:
+
+```bash
+echo 'export TORC_USERNAME="alice"' >> ~/.config/torc/credentials
+```
+
+**Source the file from your shell configuration** so it loads automatically. Add this line to
+`~/.bashrc` or `~/.zshrc`:
+
+```bash
+echo '[ -f ~/.config/torc/credentials ] && source ~/.config/torc/credentials' >> ~/.bashrc
+source ~/.config/torc/credentials
+```
+
+## Step 4: Verify
+
+```bash
+torc workflows list
+```
+
+## Protecting Your Credentials
+
+- The credentials file is already restricted (`chmod 600`) from step 3
+- **Never pass `--password` on the command line** — it appears in shell history and process lists
+- **Do not commit** `~/.config/torc/credentials` or any file containing passwords to version control
+
+## See Also
+
+- [Environment Variables](../reference/environment-variables.md) — All Torc environment variables
+- [CLI Reference](../reference/cli.md) — Global `--username` and `--password` flags

docs/src/getting-started/installation.md

@@ -74,7 +74,8 @@ echo 'export PATH="/scratch/dthom/torc/latest:$PATH"' >> ~/.bashrc
 ```
 
 **Shared server**: A `torc-server` instance runs on a dedicated VM within the Kestrel environment at
-`torc.hpc.nrel.gov`. Contact Daniel Thom if you would like to create an access group to store
+`torc.hpc.nrel.gov`. See [How to Set Up Authentication](../core/how-to/set-up-authentication.md) to
+configure your credentials. Contact Daniel Thom if you would like to create an access group to store
 private workflows for your team.
 
 ```bash