docs: add CLI and operator environment variable reference

[glitch-ux]

Problem

The existing Environment Variables docs page covers workflow-level env: scopes and precedence, which is useful for workflow authors. However, there is no centralized reference for the CLI-side and operator-facing environment variables that configure the gh aw tool itself.

These variables are scattered across source code with inline comments (pkg/constants/engine_constants.go, pkg/workflow/features.go, pkg/workflow/action_mode.go, pkg/logger/logger.go, pkg/console/accessibility.go, pkg/cli/update_check.go, etc.) but are not surfaced in any user-facing documentation.

A contributor or operator who wants to know "how do I enable debug logging?" or "how do I override the action mode?" must grep the source code.

Variables Missing from Docs

CLI behavior & debugging

Variable	Purpose	Default	Source
DEBUG	npm-style pattern debug logging (e.g., DEBUG=*, DEBUG=cli:*,workflow:*)	disabled	pkg/logger/logger.go:59
DEBUG_COLORS	Set to "0" to disable color in debug output	"1" (colors on)	pkg/logger/logger.go:30
GH_AW_MCP_SERVER	If set, disables update checks (detects MCP server subprocess)	unset	pkg/cli/update_check.go:97
GH_AW_ACTION_MODE	Override action mode: dev, release, script, or action	auto-detected	pkg/workflow/action_mode.go:75
GH_AW_FEATURES	Comma-separated experimental feature flags	empty (all off)	pkg/workflow/features.go:56
GH_AW_MAX_CONCURRENT_DOWNLOADS	Max parallel log/artifact downloads	unspecified	pkg/cli/logs_orchestrator.go via envutil.GetIntFromEnv()
ACCESSIBLE	Non-empty enables accessibility mode (no animations/spinners)	empty	pkg/console/accessibility.go:16
NO_COLOR	Disable colored output (https://no-color.org/)	empty	pkg/console/accessibility.go:18

Model overrides

Variable	Purpose	Source
GH_AW_MODEL_AGENT_COPILOT	Default Copilot model for agent runs	engine_constants.go:159
GH_AW_MODEL_AGENT_CLAUDE	Default Claude model for agent runs	engine_constants.go:161
GH_AW_MODEL_AGENT_CODEX	Default Codex model for agent runs	engine_constants.go:163
GH_AW_MODEL_AGENT_GEMINI	Default Gemini model for agent runs	engine_constants.go:167
GH_AW_MODEL_DETECTION_COPILOT	Default Copilot model for threat detection	engine_constants.go:169
GH_AW_MODEL_DETECTION_CLAUDE	Default Claude model for threat detection	engine_constants.go:171
GH_AW_MODEL_DETECTION_CODEX	Default Codex model for threat detection	engine_constants.go:173
GH_AW_MODEL_DETECTION_GEMINI	Default Gemini model for threat detection	engine_constants.go:175

Guard policy fallbacks

Variable	Purpose	Format	Source
GH_AW_GITHUB_BLOCKED_USERS	Fallback for tools.github.blocked-users	comma/newline-separated usernames	engine_constants.go:216
GH_AW_GITHUB_APPROVAL_LABELS	Fallback for tools.github.approval-labels	comma/newline-separated label names	engine_constants.go:222
GH_AW_GITHUB_TRUSTED_USERS	Fallback for tools.github.trusted-users	comma/newline-separated usernames	engine_constants.go:228

Engine secrets (already documented in setup wizard, but not on this page)

Variable	Engine	Source
COPILOT_GITHUB_TOKEN	GitHub Copilot	engine_constants.go:52
ANTHROPIC_API_KEY	Claude	engine_constants.go:60
OPENAI_API_KEY / CODEX_API_KEY	Codex	engine_constants.go:69-70
GEMINI_API_KEY	Gemini	engine_constants.go:78
GH_AW_GITHUB_TOKEN	System (cross-repo ops, user identity)	engine_constants.go:95
GH_AW_AGENT_TOKEN	System (agent/bot assignment)	engine_constants.go:101
GH_AW_GITHUB_MCP_SERVER_TOKEN	System (isolated MCP permissions)	engine_constants.go:107

Implementation Plan

1. Extend docs/src/content/docs/reference/environment-variables.md with three new sections after the existing "System-Injected Runtime Variables" section:

   • "CLI Configuration Variables" — DEBUG, DEBUG_COLORS, ACCESSIBLE, NO_COLOR, GH_AW_ACTION_MODE, GH_AW_FEATURES, GH_AW_MAX_CONCURRENT_DOWNLOADS, GH_AW_MCP_SERVER
   • "Model Override Variables" — all GH_AW_MODEL_* vars, with a note that these override model selection from workflow frontmatter
   • "Guard Policy Fallback Variables" — GH_AW_GITHUB_BLOCKED_USERS, GH_AW_GITHUB_APPROVAL_LABELS, GH_AW_GITHUB_TRUSTED_USERS, with a note that these are fallbacks when the corresponding frontmatter field is omitted

2. Add a cross-reference from the "Engine Secrets" section of the setup docs to the new environment variables page.

3. Add a "Related Documentation" entry in the existing page pointing to:

   • Engine Configuration reference
   • Guard Policies / Tools reference for policy fallback context

4. Format each variable entry with: name, type/format, default, description, and which scope it applies to (CLI-only, Actions-only, or both).

Why This Matters

• Users cannot discover DEBUG=* for troubleshooting without reading source
• Model overrides via env vars are the only way to change models outside frontmatter (useful for org-wide defaults via Actions variables) but are undocumented
• Guard policy fallback variables are a key security feature for org admins but require reading engine_constants.go to learn about

[pelikhan]

/scout validate these env vars in the source

[github-actions]

🔭 Recon complete! Scout has charted the territory. Map ready! 🗺️

[github-actions]

🔍 Scout Research Report

Triggered by @pelikhan

Executive Summary

All env vars listed in the issue were validated against the source. All variables exist and are accurate, with 3 corrections and 3 omissions worth noting before the docs page is written.

Validation Results — CLI behavior & debugging

Variable	Issue claim	Validated	Notes
DEBUG	logger.go:59	✅ line 59	Also triggered by ACTIONS_RUNNER_DEBUG=true — not mentioned in issue
DEBUG_COLORS	logger.go:30	✅ line 30	Correct
GH_AW_MCP_SERVER	update_check.go:97	✅ line 97	Correct
GH_AW_ACTION_MODE	action_mode.go:75	✅ line 75	Correct
GH_AW_FEATURES	features.go:56	✅ line 56	Correct
GH_AW_MAX_CONCURRENT_DOWNLOADS	default "unspecified"	⚠️ default is 10, range 1–100	See pkg/cli/logs_models.go:34 and orchestrator call
ACCESSIBLE	accessibility.go:16	✅ line 16	Correct
NO_COLOR	accessibility.go:18	✅ line 18	Correct

Validation Results — Model overrides & Guard policy fallbacks

All model env vars (GH_AW_MODEL_AGENT_*, GH_AW_MODEL_DETECTION_*) and guard policy fallbacks (GH_AW_GITHUB_BLOCKED_USERS, GH_AW_GITHUB_APPROVAL_LABELS, GH_AW_GITHUB_TRUSTED_USERS) confirmed in pkg/constants/engine_constants.go at the exact line numbers cited. ✅

All engine secrets (COPILOT_GITHUB_TOKEN, ANTHROPIC_API_KEY, OPENAI_API_KEY/CODEX_API_KEY, GEMINI_API_KEY, GH_AW_GITHUB_TOKEN, GH_AW_AGENT_TOKEN, GH_AW_GITHUB_MCP_SERVER_TOKEN) confirmed. ✅

Corrections needed

1. GH_AW_MAX_CONCURRENT_DOWNLOADS default — issue says "unspecified" but the code sets a default of 10 with a validated range of 1–100 (pkg/cli/logs_models.go:34, pkg/cli/logs_orchestrator.go:41).

2. TERM=dumb triggers accessibility mode — IsAccessibleMode() (pkg/console/accessibility.go:17) also returns true when TERM=dumb. Should be added alongside ACCESSIBLE and NO_COLOR.

3. GH_AW_MODEL_AGENT_CUSTOM missing — engine_constants.go:164–165 defines EnvVarModelAgentCustom = "GH_AW_MODEL_AGENT_CUSTOM" but it's absent from the issue's model override table.

Additional variable found (not in issue)

ACTIONS_RUNNER_DEBUG — pkg/logger/logger.go:62 — when ACTIONS_RUNNER_DEBUG=true, it is equivalent to DEBUG=* (enables all loggers). This is the standard GitHub Actions runner debug flag and worth documenting alongside DEBUG.

References:

• pkg/cli/logs_models.go:34
• pkg/console/accessibility.go
• pkg/constants/engine_constants.go
• §23967638407

🔭 Intelligence gathered by Scout · ● 143K · ◷