feat: add support for env files at ws and exec level (#292)

Author: jahvon

cmd/internal/exec.go

@@ -4,6 +4,7 @@ import (
 	"errors"
 	"fmt"
 	"os"
+	"path/filepath"
 	"strings"
 	"time"
 
@@ -26,9 +27,11 @@ import (
 	"github.com/flowexec/flow/internal/runner/request"
 	"github.com/flowexec/flow/internal/runner/serial"
 	"github.com/flowexec/flow/internal/services/store"
+	"github.com/flowexec/flow/internal/utils/env"
 	"github.com/flowexec/flow/internal/vault"
 	vaultV2 "github.com/flowexec/flow/internal/vault/v2"
 	"github.com/flowexec/flow/types/executable"
+	"github.com/flowexec/flow/types/workspace"
 )
 
 func RegisterExecCmd(ctx *context.Context, rootCmd *cobra.Command) {
@@ -125,7 +128,7 @@ func execFunc(ctx *context.Context, cmd *cobra.Command, verb executable.Verb, ar
 
 	if !e.IsExecutableFromWorkspace(ctx.CurrentWorkspace.AssignedName()) {
 		logger.Log().FatalErr(fmt.Errorf(
-			"e '%s' cannot be executed from workspace %s",
+			"executable '%s' cannot be executed from workspace %s",
 			ref,
 			ctx.Config.CurrentWorkspace,
 		))
@@ -140,8 +143,14 @@ func execFunc(ctx *context.Context, cmd *cobra.Command, verb executable.Verb, ar
 	}
 	_ = s.Close()
 
-	// add --param overrides to the env map
 	envMap := make(map[string]string)
+	// add workspace env variables to the env map
+	if wsCfg, ok := ctx.WorkspacesCache.GetData().Workspaces[e.Workspace()]; !ok {
+		logger.Log().Warnf("workspace %s not found in cache, skipping env file resolution", e.Workspace())
+	} else {
+		applyWorkspaceParameterOverrides(wsCfg, envMap)
+	}
+	// add --param overrides to the env map
 	paramOverrides := flags.ValueFor[[]string](cmd, *flags.ParameterValueFlag, false)
 	applyParameterOverrides(paramOverrides, envMap)
 
@@ -395,6 +404,31 @@ func pendingFormFields(
 	return pending
 }
 
+//nolint:nestif
+func applyWorkspaceParameterOverrides(ws *workspace.Workspace, envMap map[string]string) {
+	if len(ws.EnvFiles) > 0 {
+		loaded, err := env.LoadEnvFromFiles(ws.EnvFiles, ws.Location())
+		if err != nil {
+			logger.Log().Errorf("failed loading env files for workspace %s: %v", ws.AssignedName(), err)
+		}
+		for k, v := range loaded {
+			envMap[k] = v
+		}
+	} else {
+		rootEnvFile := filepath.Join(ws.Location(), ".env")
+		if _, err := os.Stat(rootEnvFile); err == nil {
+			loaded, err := env.LoadEnvFromFiles([]string{rootEnvFile}, ws.Location())
+			if err != nil {
+				logger.Log().Errorf("failed loading root env file %s: %v", rootEnvFile, err)
+			} else {
+				for k, v := range loaded {
+					envMap[k] = v
+				}
+			}
+		}
+	}
+}
+
 func applyParameterOverrides(overrides []string, envMap map[string]string) {
 	for _, override := range overrides {
 		parts := strings.SplitN(override, "=", 2)

desktop/src-tauri/src/types/generated/flowfile.rs

@@ -944,8 +944,13 @@ impl ::std::convert::From<::std::vec::Vec<ExecutableParallelRefConfig>>
 #[doc = "  \"description\": \"A parameter is a value that can be passed to an executable and all of its sub-executables.\\nOnly one of `text`, `secretRef`, `prompt`, or `file` must be set. Specifying more than one will result in an error.\\n\","]
 #[doc = "  \"type\": \"object\","]
 #[doc = "  \"properties\": {"]
+#[doc = "    \"envFile\": {"]
+#[doc = "      \"description\": \"A path to a file containing environment variables to be passed to the executable.\\nThe file should contain one variable per line in the format `KEY=VALUE`.\\n\","]
+#[doc = "      \"default\": \"\","]
+#[doc = "      \"type\": \"string\""]
+#[doc = "    },"]
 #[doc = "    \"envKey\": {"]
-#[doc = "      \"description\": \"The name of the environment variable that will be assigned the value.\","]
+#[doc = "      \"description\": \"The name of the environment variable that will be assigned the value.\\n\\nWhen specified with `envFile`, only the environment variable with this name will be set.\\n\","]
 #[doc = "      \"default\": \"\","]
 #[doc = "      \"type\": \"string\""]
 #[doc = "    },"]
@@ -975,7 +980,10 @@ impl ::std::convert::From<::std::vec::Vec<ExecutableParallelRefConfig>>
 #[doc = r" </details>"]
 #[derive(:: serde :: Deserialize, :: serde :: Serialize, Clone, Debug)]
 pub struct ExecutableParameter {
-    #[doc = "The name of the environment variable that will be assigned the value."]
+    #[doc = "A path to a file containing environment variables to be passed to the executable.\nThe file should contain one variable per line in the format `KEY=VALUE`.\n"]
+    #[serde(rename = "envFile", default)]
+    pub env_file: ::std::string::String,
+    #[doc = "The name of the environment variable that will be assigned the value.\n\nWhen specified with `envFile`, only the environment variable with this name will be set.\n"]
     #[serde(rename = "envKey", default)]
     pub env_key: ::std::string::String,
     #[doc = "A path where the parameter value will be temporarily written to disk.\nThe file will be created before execution and cleaned up afterwards.\n"]
@@ -999,6 +1007,7 @@ impl ::std::convert::From<&ExecutableParameter> for ExecutableParameter {
 impl ::std::default::Default for ExecutableParameter {
     fn default() -> Self {
         Self {
+            env_file: Default::default(),
             env_key: Default::default(),
             output_file: Default::default(),
             prompt: Default::default(),
@@ -3468,6 +3477,7 @@ pub mod builder {
     }
     #[derive(Clone, Debug)]
     pub struct ExecutableParameter {
+        env_file: ::std::result::Result<::std::string::String, ::std::string::String>,
         env_key: ::std::result::Result<::std::string::String, ::std::string::String>,
         output_file: ::std::result::Result<::std::string::String, ::std::string::String>,
         prompt: ::std::result::Result<::std::string::String, ::std::string::String>,
@@ -3477,6 +3487,7 @@ pub mod builder {
     impl ::std::default::Default for ExecutableParameter {
         fn default() -> Self {
             Self {
+                env_file: Ok(Default::default()),
                 env_key: Ok(Default::default()),
                 output_file: Ok(Default::default()),
                 prompt: Ok(Default::default()),
@@ -3486,6 +3497,16 @@ pub mod builder {
         }
     }
     impl ExecutableParameter {
+        pub fn env_file<T>(mut self, value: T) -> Self
+        where
+            T: ::std::convert::TryInto<::std::string::String>,
+            T::Error: ::std::fmt::Display,
+        {
+            self.env_file = value
+                .try_into()
+                .map_err(|e| format!("error converting supplied value for env_file: {}", e));
+            self
+        }
         pub fn env_key<T>(mut self, value: T) -> Self
         where
             T: ::std::convert::TryInto<::std::string::String>,
@@ -3543,6 +3564,7 @@ pub mod builder {
             value: ExecutableParameter,
         ) -> ::std::result::Result<Self, super::error::ConversionError> {
             Ok(Self {
+                env_file: value.env_file?,
                 env_key: value.env_key?,
                 output_file: value.output_file?,
                 prompt: value.prompt?,
@@ -3554,6 +3576,7 @@ pub mod builder {
     impl ::std::convert::From<super::ExecutableParameter> for ExecutableParameter {
         fn from(value: super::ExecutableParameter) -> Self {
             Self {
+                env_file: Ok(value.env_file),
                 env_key: Ok(value.env_key),
                 output_file: Ok(value.output_file),
                 prompt: Ok(value.prompt),

desktop/src-tauri/src/types/generated/workspace.rs

@@ -206,6 +206,14 @@ impl
 #[doc = "      \"default\": \"\","]
 #[doc = "      \"type\": \"string\""]
 #[doc = "    },"]
+#[doc = "    \"envFiles\": {"]
+#[doc = "      \"description\": \"A list of environment variable files to load for the workspace. These files should contain key-value pairs of environment variables.\\nBy default, the `.env` file in the workspace root is loaded if it exists.\\n\","]
+#[doc = "      \"default\": [],"]
+#[doc = "      \"type\": \"array\","]
+#[doc = "      \"items\": {"]
+#[doc = "        \"type\": \"string\""]
+#[doc = "      }"]
+#[doc = "    },"]
 #[doc = "    \"executables\": {"]
 #[doc = "      \"$ref\": \"#/definitions/ExecutableFilter\""]
 #[doc = "    },"]
@@ -231,6 +239,13 @@ pub struct Workspace {
     #[doc = "The display name of the workspace. This is used in the interactive UI."]
     #[serde(rename = "displayName", default)]
     pub display_name: ::std::string::String,
+    #[doc = "A list of environment variable files to load for the workspace. These files should contain key-value pairs of environment variables.\nBy default, the `.env` file in the workspace root is loaded if it exists.\n"]
+    #[serde(
+        rename = "envFiles",
+        default,
+        skip_serializing_if = "::std::vec::Vec::is_empty"
+    )]
+    pub env_files: ::std::vec::Vec<::std::string::String>,
     #[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
     pub executables: ::std::option::Option<ExecutableFilter>,
     #[serde(default = "defaults::workspace_tags")]
@@ -253,6 +268,7 @@ impl ::std::default::Default for Workspace {
             description: Default::default(),
             description_file: Default::default(),
             display_name: Default::default(),
+            env_files: Default::default(),
             executables: Default::default(),
             tags: defaults::workspace_tags(),
             verb_aliases: Default::default(),
@@ -327,6 +343,8 @@ pub mod builder {
         description: ::std::result::Result<::std::string::String, ::std::string::String>,
         description_file: ::std::result::Result<::std::string::String, ::std::string::String>,
         display_name: ::std::result::Result<::std::string::String, ::std::string::String>,
+        env_files:
+            ::std::result::Result<::std::vec::Vec<::std::string::String>, ::std::string::String>,
         executables: ::std::result::Result<
             ::std::option::Option<super::ExecutableFilter>,
             ::std::string::String,
@@ -341,6 +359,7 @@ pub mod builder {
                 description: Ok(Default::default()),
                 description_file: Ok(Default::default()),
                 display_name: Ok(Default::default()),
+                env_files: Ok(Default::default()),
                 executables: Ok(Default::default()),
                 tags: Ok(super::defaults::workspace_tags()),
                 verb_aliases: Ok(Default::default()),
@@ -381,6 +400,16 @@ pub mod builder {
                 .map_err(|e| format!("error converting supplied value for display_name: {}", e));
             self
         }
+        pub fn env_files<T>(mut self, value: T) -> Self
+        where
+            T: ::std::convert::TryInto<::std::vec::Vec<::std::string::String>>,
+            T::Error: ::std::fmt::Display,
+        {
+            self.env_files = value
+                .try_into()
+                .map_err(|e| format!("error converting supplied value for env_files: {}", e));
+            self
+        }
         pub fn executables<T>(mut self, value: T) -> Self
         where
             T: ::std::convert::TryInto<::std::option::Option<super::ExecutableFilter>>,
@@ -421,6 +450,7 @@ pub mod builder {
                 description: value.description?,
                 description_file: value.description_file?,
                 display_name: value.display_name?,
+                env_files: value.env_files?,
                 executables: value.executables?,
                 tags: value.tags?,
                 verb_aliases: value.verb_aliases?,
@@ -433,6 +463,7 @@ pub mod builder {
                 description: Ok(value.description),
                 description_file: Ok(value.description_file),
                 display_name: Ok(value.display_name),
+                env_files: Ok(value.env_files),
                 executables: Ok(value.executables),
                 tags: Ok(value.tags),
                 verb_aliases: Ok(value.verb_aliases),

desktop/src/types/generated/flowfile.ts

@@ -365,8 +365,17 @@ export interface ExecutableArgument {
  *
  */
 export interface ExecutableParameter {
+  /**
+   * A path to a file containing environment variables to be passed to the executable.
+   * The file should contain one variable per line in the format `KEY=VALUE`.
+   *
+   */
+  envFile?: string;
   /**
    * The name of the environment variable that will be assigned the value.
+   *
+   * When specified with `envFile`, only the environment variable with this name will be set.
+   *
    */
   envKey?: string;
   /**

desktop/src/types/generated/workspace.ts

@@ -29,6 +29,12 @@ export interface Workspace {
    * The display name of the workspace. This is used in the interactive UI.
    */
   displayName?: string;
+  /**
+   * A list of environment variable files to load for the workspace. These files should contain key-value pairs of environment variables.
+   * By default, the `.env` file in the workspace root is loaded if it exists.
+   *
+   */
+  envFiles?: string[];
   executables?: ExecutableFilter;
   tags?: CommonTags;
   verbAliases?: VerbAliases;

docs/guide/executables.md

@@ -61,6 +61,12 @@ executables:
 
 Customize executable behavior with environment variables or temporary files using `params` or `args`.
 
+> [!INFO]
+> Executables inherit environment variables from their parent executable, workspace, and system.
+> 
+> By default, values defined in the `.env` file at the workspace root are automatically loaded. This can be overriden
+> in the workspace configuration file with the `envFiles` field.
+
 ### Parameters (`params`) <!-- {docsify-ignore} -->
 
 Set environment data from various sources:
@@ -85,6 +91,11 @@ executables:
         # Static values
         - text: "production"
           envKey: DEPLOY_ENV
+          
+        # Env File (key=value format)
+        - envFile: "development.env"
+        - envFile: "staging.env"
+          envKey: SHARED_KEYS  # Only load specific keys
 
         # Saved to a file
         - secretRef: tls-cert
@@ -95,6 +106,7 @@ executables:
 - `secretRef`: Reference to vault secret
 - `prompt`: Interactive user input
 - `text`: Static value
+- `envFile`: Load environment variables from a file
 
 ### Arguments (`args`) <!-- {docsify-ignore} -->
 

docs/guide/workspaces.md

@@ -79,6 +79,11 @@ verbAliases:
   run: ["start", "exec"]
   build: ["compile", "make"]
   # Set to {} to disable all aliases
+  
+# Environment variables to load for all executables in this workspace
+envFiles:
+  - .env
+  - .env.local
 
 # Control executable discovery
 executables:
@@ -100,6 +105,7 @@ executables:
 
 **Behavior Customization:**
 - `verbAliases`: Customize which verb synonyms are available
+- `envFiles`: List of environment files to load for all executables (the root `.env` is loaded by default)
 
 > **Complete reference**: See the [workspace configuration schema](../types/workspace.md) for all available options.
 

docs/schemas/flowfile_schema.json

@@ -283,8 +283,13 @@
       "description": "A parameter is a value that can be passed to an executable and all of its sub-executables.\nOnly one of `text`, `secretRef`, `prompt`, or `file` must be set. Specifying more than one will result in an error.\n",
       "type": "object",
       "properties": {
+        "envFile": {
+          "description": "A path to a file containing environment variables to be passed to the executable.\nThe file should contain one variable per line in the format `KEY=VALUE`.\n",
+          "type": "string",
+          "default": ""
+        },
         "envKey": {
-          "description": "The name of the environment variable that will be assigned the value.",
+          "description": "The name of the environment variable that will be assigned the value.\n\nWhen specified with `envFile`, only the environment variable with this name will be set.\n",
           "type": "string",
           "default": ""
         },

docs/schemas/workspace_schema.json

@@ -60,6 +60,14 @@
       "type": "string",
       "default": ""
     },
+    "envFiles": {
+      "description": "A list of environment variable files to load for the workspace. These files should contain key-value pairs of environment variables.\nBy default, the `.env` file in the workspace root is loaded if it exists.\n",
+      "type": "array",
+      "default": [],
+      "items": {
+        "type": "string"
+      }
+    },
     "executables": {
       "$ref": "#/definitions/ExecutableFilter"
     },

docs/types/flowfile.md

@@ -237,7 +237,8 @@ Only one of `text`, `secretRef`, `prompt`, or `file` must be set. Specifying mor
 
 | Field | Description | Type | Default | Required |
 | ----- | ----------- | ---- | ------- | :--------: |
-| `envKey` | The name of the environment variable that will be assigned the value. | `string` |  |  |
+| `envFile` | A path to a file containing environment variables to be passed to the executable. The file should contain one variable per line in the format `KEY=VALUE`.  | `string` |  |  |
+| `envKey` | The name of the environment variable that will be assigned the value.  When specified with `envFile`, only the environment variable with this name will be set.  | `string` |  |  |
 | `outputFile` | A path where the parameter value will be temporarily written to disk. The file will be created before execution and cleaned up afterwards.  | `string` |  |  |
 | `prompt` | A prompt to be displayed to the user when collecting an input value. | `string` |  |  |
 | `secretRef` | A reference to a secret to be passed to the executable. | `string` |  |  |