From e2af620f70ab695a85ff77da761fbfe174e49e76 Mon Sep 17 00:00:00 2001
From: Chris Wanstrath <chris@ozmm.org>
Date: Thu, 12 Mar 2026 14:19:25 -0700
Subject: [PATCH] docs: document environment variables in README

---
 README.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/README.md b/README.md
index 1a2b39b..fde8091 100644
--- a/README.md
+++ b/README.md
@@ -89,6 +89,28 @@ Options:
   -h, --help       display help for command
 ```
 
+## Environment Variables
+
+### Set automatically
+
+| Variable | Value |
+|---|---|
+| `HOME` | Path to the temp directory created for the test |
+| `SHOUT_DIR` | Same as `HOME` — the temp directory for the test |
+| `PORT` | Auto-assigned when `--port-from <n>` is used (increments per file). Not set if `PORT` is already defined via `@env` or `@setup`. |
+
+### Inherited
+
+By default, the test shell inherits all environment variables from the parent process. Use `--clean-env` to start with an empty environment instead.
+
+### Modified
+
+`PATH` is prepended with any directories passed via `--path <path>`.
+
+### User-defined
+
+Use `@env KEY=VALUE` directives to set arbitrary variables. See [Directives](#directives).
+
 Print an example `.shout` file:
 
 ```