feat: support loading a dotenv '.env' file for your app by zimeg · Pull Request #436 · slackapi/slack-cli

zimeg · 2026-03-24T22:38:47Z

Changelog

Environment variables saved to a .env file are now loaded into the process before hook scripts run. This brings meaningful improvement to the slack run command foremost as additional dependencies are no longer required for loading environment variables into the runtime context.

Other commands, such as the slack deploy command and the slack manifest command, also benefit from this since the underlying hooks can be more expressive in customizations and configured to custom environments.

Summary

This PR loads environment variables from the .env file for hook commands. These variables are loaded before each hook command executes to ensure correctness 🌲 ✨

We also fix orderings of environment variable precedence within hooks to be:

Provided variables to hooks - Ex: The SLACK_CLI_XOXP token provided with the run command.
Saved ".env" file - Ex: The developer's project keeps a .env. file.
Existing shell environment - Ex: Prior EXPORT or set variables otherwise. This is most important!

Preview

demo.mov

Reviewers

A few test cases might be interesting to saved variables:

$ slack create asdf -t slack-samples/bolt-js-assistant-template
$ cd asdf
$ vim .env
OPENAI_API_KEY=sk-proj-example-123  # Replace please!
$ npm uninstall dotenv
$ diff app.js
- import 'dotenv/config';           # Delete this line
$ slack run                         # File is read
$ OPENAI_API_KEY=oopsies slack run  # Shell overrides

Notes

We might follow up with similar .env patterns and I'm hoping these changes guide decent direction to placement of loading environment variables for hooks!

Earlier exploration attempted to read environment variables during the CLI setup but that required configuration changes that seemed incorrect to make. I understand now the internal/config/dotenv package is for internal configurations instead of developer application variables.
The existing clients.Config.ManifestEnv attribute is used for manifest and trigger commands but not run or the deploy commands for Bolt apps. I'm unsure that we should continue to support this as we bring enhancement to a project ".env" file itself? Regardless, it wasn't the right rabbit hole...

Requirements

I've read and understood the Contributing Guidelines and have done my best effort to follow them.
I've read and agree to the Code of Conduct.

codecov · 2026-03-24T22:43:05Z

Codecov Report

❌ Patch coverage is 86.66667% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 70.44%. Comparing base (0c37128) to head (6cadb2d).

Files with missing lines	Patch %	Lines
internal/pkg/platform/run.go	0.00%	3 Missing ⚠️
internal/slackdotenv/slackdotenv.go	85.71%	2 Missing ⚠️
internal/pkg/platform/localserver.go	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #436      +/-   ##
==========================================
+ Coverage   70.32%   70.44%   +0.11%     
==========================================
  Files         220      221       +1     
  Lines       18506    18533      +27     
==========================================
+ Hits        13015    13055      +40     
+ Misses       4313     4306       -7     
+ Partials     1178     1172       -6

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

zimeg

👾 A few thoughts for wonderful reviewers-

zimeg · 2026-03-24T22:40:54Z

internal/pkg/platform/localserver.go

🗣️ note: The run command uses a separate hook process to handle automatic restarts with file watching so we duplicate some logic here!

zimeg · 2026-03-24T22:42:26Z

cmd/platform/deploy.go

 	// so we instantiate the default here.
 	shell := hooks.HookExecutorDefaultProtocol{
 		IO: clients.IO,
+		Fs: clients.Fs,


🔭 note: Standalone protocol setups must define fs to access .env but we don't error otherwise. AFAICT this is required for just the deploy and run commands.

mwbrooks

🙌🏻 Woohoo, this is so awesome to see landing!

🥾 I think we have a few more steps to tighten things up. I've left a few suggestions in-line around consolidating code and testing edge-cases that users will hit. Below are a few more suggestions.

suggestion(non-blocking): We have some existing dotenv logic in internal/config/dotenv.go. This seems like a reasonable place to put our new parsing logic, so that everything is in one place. Or, rename it to something that feels better to us. This could be a follow-up PR but we should make sure that we don't fragment our dotenv logic.

suggestion: I think we should update the PR title and CHANGELOG description to focus a little more on the use-facing feature. For example: "feat: support loading a dotenv '.env' file for your app"

internal/hooks/hook_executor_default_test.go

internal/hooks/hook_executor_v2_test.go

mwbrooks · 2026-03-25T05:32:05Z

internal/hooks/hooks.go

+	// Order of precedence from lowest to highest:
+	// 1. Provided "opts.Env" variables
+	// 2. Saved ".env" file
+	// 3. Existing shell environment
+	//
+	// > Each entry is of the form "key=value".
+	// > ...
+	// > If Env contains duplicate environment keys, only the last value in the slice for each duplicate key is used.
+	//
+	// https://pkg.go.dev/os/exec#Cmd.Env


praise: ❤️ 🖊️ Love the detailed comment for future readers!

mwbrooks · 2026-03-25T05:42:59Z

internal/pkg/platform/localserver.go

+	// Order of precedence from lowest to highest:
+	// 1. Provided "opts.Env" variables
+	// 2. Saved ".env" file
+	// 3. Existing shell environment
+	//
+	// > Each entry is of the form "key=value".
+	// > ...
+	// > If Env contains duplicate environment keys, only the last value in the slice for each duplicate key is used.
+	//
+	// https://pkg.go.dev/os/exec#Cmd.Env


suggestion: This logic feels important and since it's used in 2 places, I think we should consider DRY'ing up the code and putting the logic into 1 place. For example, internal/config/dotenv.go (existing) or rename the file to internal/slackdotenv if we want something that doesn't name collide with the dotenv dependency.

Additionally, a single function would make future improvements easier. For example, we may want to introduce a --dotenv-overwrite flag and { "dotenv-overwrite": true config value that allow the .env to overwrite session variables. This seems to be a common use-case because most dotenv libraries support it, including our package with godotenv.Overload().

Note: This would also allow us to unit test the scenarios in internal/config/dotenv_test.go instead of in the localserver_test.go and hooks_test.go.

@mwbrooks Super appreciate that you noticed this! I agree it's meaningful logic that felt fragile in my initial implementation 👁️‍🗨️

We refactored our environment variable management into a few places:

internal/slackdotenv: This reads the ".env" file.

internal/hooks/shell.go#HookExecOpts:ShellEnv(): This orders variables for hook commands with precedence.

This change takes place in two commits f63d0ff and 9160bcc with some adjacent tests.

@mwbrooks Not meaning to send before addressing the Overload options 👾

These refactors make this and similar changes to loading from environment variable files much more safe I feel. I look forward to these changes!

internal/hooks/hooks.go

internal/hooks/hooks_test.go

internal/hooks/hooks.go

zimeg

💡 Some thoughts I had during recent changes were left in these comments!

zimeg · 2026-03-26T21:38:19Z

internal/config/dotenv.go

-// GetDotEnvFileVariables collects only the variables in the .env file
-func (c *Config) GetDotEnvFileVariables() (map[string]string, error) {
-	variables := map[string]string{}
-	file, err := afero.ReadFile(c.fs, ".env")
-	if err != nil && !c.os.IsNotExist(err) {
-		return variables, err
-	}
-	return godotenv.UnmarshalBytes(file)
-}


📦 note: This is moved to our own slackdotenv package to avoid odd dependencies of config and to avoid duplicate logic!

zimeg · 2026-03-26T22:19:07Z

internal/slackdotenv/slackdotenv.go

+// Read parses a .env file from the working directory using the provided
+// filesystem. It returns nil if the filesystem is nil or the file does not
+// exist.
+func Read(fs afero.Fs) (map[string]string, error) {
+	if fs == nil {
+		return nil, nil
+	}
+	file, err := afero.ReadFile(fs, ".env")
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	return godotenv.UnmarshalBytes(file)
+}


🪬 note: I'm not confident on the Read vs Load term but for now this is perhaps clear. We might want to revisit this in changes to the actual ".env" file ongoing?

zimeg

@mwbrooks Super appreciate the review and thoughts to improved code health! 🏥 💌

A handful of changes landed since and I'm rerequesting review with hopes that comments have kind resolution, but please let me know if I can follow up with more changes or of other thoughts.

I did make a change to error handling with warnings but nothing that should change current code adjacent. The change is within the other files being updated 📠

zimeg · 2026-03-27T00:24:47Z

.claude/CLAUDE.md


+### Error Handling
+
+- Wrap errors returned across package boundaries with `slackerror.Wrap(err, slackerror.ErrCode)` so they carry a structured error code


📚 note: This is motivated in ongoing changes with encouragement and optimism for checks from the wonderful wrapcheck lint:

Checks that errors returned from external packages are wrapped.

🔗 https://golangci-lint.run/docs/linters/configuration/#wrapcheck

feat: load environment variables from '.env' file for hook commands

c438267

zimeg added this to the Next Release milestone Mar 24, 2026

zimeg self-assigned this Mar 24, 2026

zimeg added enhancement M-T: A feature request for new functionality semver:minor Use on pull requests to describe the release version increment labels Mar 24, 2026

Merge branch 'main' into zimeg-feat-load-hook-dotenv

fb0cce1

zimeg commented Mar 24, 2026

View reviewed changes

zimeg marked this pull request as ready for review March 24, 2026 22:43

zimeg requested a review from a team as a code owner March 24, 2026 22:43

mwbrooks reviewed Mar 25, 2026

View reviewed changes

zimeg changed the title ~~feat: load environment variables from '.env' file for hook commands~~ feat: support loading a dotenv '.env' file for your app Mar 26, 2026

zimeg added 8 commits March 26, 2026 09:55

Merge branch 'main' into zimeg-feat-load-hook-dotenv

0266d17

test: make clear the purpose of env var hook tests

72828ec

refactor: use a slackdotenv package for reading variables from .env file

f63d0ff

docs: godoc slackdotenv

4b29a23

Merge branch 'main' into zimeg-feat-load-hook-dotenv

2324d5f

refactor: set command shell environment variables from hook options

9160bcc

test: assert expected cases of shell environment are parsed in order

7dfc00d

test: confirm inline comments are ignored

c1382df

zimeg commented Mar 26, 2026

View reviewed changes

zimeg added 2 commits March 26, 2026 17:17

feat: output warning for invalid .env file parsing

525f693

chore: claude errorcodes

6cadb2d

zimeg commented Mar 27, 2026

View reviewed changes

zimeg requested a review from mwbrooks March 27, 2026 00:27


		### Error Handling

		- Wrap errors returned across package boundaries with `slackerror.Wrap(err, slackerror.ErrCode)` so they carry a structured error code

Conversation

zimeg commented Mar 24, 2026

Changelog

Summary

Preview

Reviewers

Notes

Requirements

Uh oh!

codecov bot commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

zimeg left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mwbrooks left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

zimeg left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zimeg left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

codecov bot commented Mar 24, 2026 •

edited

Loading