From 23e3b9042bc7fd95181f59c47cc4ec3587664a91 Mon Sep 17 00:00:00 2001
From: "alex.stanfield" <13949480+chaptersix@users.noreply.github.com>
Date: Sat, 11 Jul 2026 13:10:50 -0500
Subject: [PATCH] docs: generate environment variables reference

---
 cmd/gen-docs/main_test.go    | 13 ++++++++
 internal/commandsgen/docs.go | 59 ++++++++++++++++++++++++++++++++++++
 2 files changed, 72 insertions(+)

diff --git a/cmd/gen-docs/main_test.go b/cmd/gen-docs/main_test.go
index cdd68945c..ab2af4cc2 100644
--- a/cmd/gen-docs/main_test.go
+++ b/cmd/gen-docs/main_test.go
@@ -3,6 +3,7 @@ package main
 import (
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 )
 
@@ -36,4 +37,16 @@ func TestGenDocsMultipleInputs(t *testing.T) {
 	if _, err := os.Stat(workflowPath); os.IsNotExist(err) {
 		t.Fatal("workflow.mdx was not generated")
 	}
+
+	envVarsPath := filepath.Join(outputDir, "environment-variables.mdx")
+	envVars, err := os.ReadFile(envVarsPath)
+	if os.IsNotExist(err) {
+		t.Fatal("environment-variables.mdx was not generated")
+	}
+	if err != nil {
+		t.Fatalf("failed reading environment-variables.mdx: %v", err)
+	}
+	if !strings.Contains(string(envVars), "`TEMPORAL_ADDRESS`") {
+		t.Fatal("environment-variables.mdx does not include TEMPORAL_ADDRESS")
+	}
 }
diff --git a/internal/commandsgen/docs.go b/internal/commandsgen/docs.go
index d699c23f6..b5af6b5be 100644
--- a/internal/commandsgen/docs.go
+++ b/internal/commandsgen/docs.go
@@ -46,6 +46,7 @@ func GenerateDocsFiles(commands Commands, subdirNames []string) (map[string][]by
 
 	// Write global flags section once at the end of each file
 	w.writeGlobalFlagsSections()
+	w.writeEnvironmentVariablesPage(commands)
 
 	// Format and return
 	var finalMap = make(map[string][]byte)
@@ -360,6 +361,64 @@ func (w *docWriter) writeGlobalFlagsSections() {
 	}
 }
 
+func (w *docWriter) writeEnvironmentVariablesPage(commands Commands) {
+	envOptions := make(map[string]Option)
+	for _, optionSet := range commands.OptionSets {
+		for _, o := range optionSet.Options {
+			if o.ImpliedEnv != "" && !o.Hidden {
+				envOptions[o.ImpliedEnv] = o
+			}
+		}
+	}
+	for _, command := range commands.CommandList {
+		for _, o := range command.Options {
+			if o.ImpliedEnv != "" && !o.Hidden {
+				envOptions[o.ImpliedEnv] = o
+			}
+		}
+	}
+
+	envNames := make([]string, 0, len(envOptions))
+	for envName := range envOptions {
+		envNames = append(envNames, envName)
+	}
+	sort.Strings(envNames)
+
+	buf := &bytes.Buffer{}
+	buf.WriteString("---\n")
+	buf.WriteString("id: environment-variables\n")
+	buf.WriteString("title: Temporal CLI environment variables\n")
+	buf.WriteString("sidebar_label: Environment variables\n")
+	buf.WriteString("description: Reference for Temporal CLI environment variables.\n")
+	buf.WriteString("toc_max_heading_level: 4\n")
+	buf.WriteString("keywords:\n")
+	buf.WriteString("  - cli\n")
+	buf.WriteString("  - environment variables\n")
+	buf.WriteString("  - temporal cli\n")
+	buf.WriteString("tags:\n")
+	buf.WriteString("  - Temporal CLI\n")
+	buf.WriteString("---\n\n")
+	buf.WriteString(autoGeneratedNotice)
+	buf.WriteString("This page lists the environment variables that can configure the Temporal CLI.\n\n")
+	buf.WriteString("| Variable | Flag | Description | Default |\n")
+	buf.WriteString("|----------|------|-------------|---------|\n")
+
+	for _, envName := range envNames {
+		o := envOptions[envName]
+		description := encodeJSONExample(o.Description)
+		description = strings.ReplaceAll(description, "\n", "<br />")
+		description = strings.ReplaceAll(description, "|", "\\|")
+		defaultVal := ""
+		if o.Default != "" {
+			defaultVal = fmt.Sprintf("`%s`", o.Default)
+		}
+		buf.WriteString(fmt.Sprintf("| `%s` | `--%s` | %s | %s |\n", envName, o.Name, description, defaultVal))
+	}
+	buf.WriteString("\n")
+
+	w.fileMap["environment-variables"] = buf
+}
+
 func (w *docWriter) processOptions(c *Command) {
 	// Pop options from stack if we are moving up a level
 	if len(w.optionsStack) >= len(strings.Split(c.FullName, " ")) {