From 40f505e2571643eff1e02c66d582db2f4f97d772 Mon Sep 17 00:00:00 2001
From: Adam Weidman <65992621+adamfweidman@users.noreply.github.com>
Date: Tue, 3 Feb 2026 14:49:37 -0500
Subject: [PATCH] docs: document GEMINI_CLI_HOME environment variable (#18219)

---
 docs/cli/enterprise.md            | 17 +++++++++++++++++
 docs/get-started/configuration.md |  7 +++++++
 2 files changed, 24 insertions(+)

diff --git a/docs/cli/enterprise.md b/docs/cli/enterprise.md
index c9b83495e5..f22ec81c37 100644
--- a/docs/cli/enterprise.md
+++ b/docs/cli/enterprise.md
@@ -203,6 +203,23 @@ with the actual Gemini CLI process, which inherits the environment variable.
 This makes it significantly more difficult for a user to bypass the enforced
 settings.
 
+## User isolation in shared environments
+
+In shared compute environments (like ML experiment runners or shared build
+servers), you can isolate Gemini CLI state by overriding the user's home
+directory.
+
+By default, Gemini CLI stores configuration and history in `~/.gemini`. You can
+use the `GEMINI_CLI_HOME` environment variable to point to a unique directory
+for a specific user or job. The CLI will create a `.gemini` folder inside the
+specified path.
+
+```bash
+# Isolate state for a specific job
+export GEMINI_CLI_HOME="/tmp/gemini-job-123"
+gemini
+```
+
 ## Restricting tool access
 
 You can significantly enhance security by controlling which tools the Gemini
diff --git a/docs/get-started/configuration.md b/docs/get-started/configuration.md
index 5a79467fe5..bc6c47a1f2 100644
--- a/docs/get-started/configuration.md
+++ b/docs/get-started/configuration.md
@@ -1176,6 +1176,13 @@ the `advanced.excludedEnvVars` setting in your `settings.json` file.
   - Specifies the default Gemini model to use.
   - Overrides the hardcoded default
   - Example: `export GEMINI_MODEL="gemini-3-flash-preview"`
+- **`GEMINI_CLI_HOME`**:
+  - Specifies the root directory for Gemini CLI's user-level configuration and
+    storage.
+  - By default, this is the user's system home directory. The CLI will create a
+    `.gemini` folder inside this directory.
+  - Useful for shared compute environments or keeping CLI state isolated.
+  - Example: `export GEMINI_CLI_HOME="/path/to/user/config"`
 - **`GOOGLE_API_KEY`**:
   - Your Google Cloud API key.
   - Required for using Vertex AI in express mode.