flag(runtime): new flag format

cmd/tracee/cmd/root.go

@@ -115,6 +115,19 @@
 		"[file|dir]\t\t\t\tPath to a policy or directory with policies",
 	)
 
+	// Runtime flags
+
+	rootCmd.Flags().StringArrayP(
+		flags.RuntimeFlag,
+		"r",
+		[]string{"workdir=" + flags.WorkdirDefault},
+		fmt.Sprintf("[workdir=%s]\t\tControl runtime configurations", flags.WorkdirDefault),
+	)
+	err := viper.BindPFlag(flags.RuntimeFlag, rootCmd.Flags().Lookup(flags.RuntimeFlag))
+	if err != nil {
+		return errfmt.WrapError(err)
+	}
+
 	// Output flags
 
 	rootCmd.Flags().StringArrayP(
@@ -123,7 +136,7 @@
 		[]string{"table"},
 		"[json|none|webhook...]\t\tControl how and where output is printed",
 	)
-	err := viper.BindPFlag("output", rootCmd.Flags().Lookup("output"))
+	err = viper.BindPFlag("output", rootCmd.Flags().Lookup("output"))
 	if err != nil {
 		return errfmt.WrapError(err)
 	}
@@ -268,16 +281,6 @@
 		return errfmt.WrapError(err)
 	}
 
-	rootCmd.Flags().String(
-		"install-path",
-		"/tmp/tracee",
-		"<dir>\t\t\t\tPath where tracee will install or lookup it's resources",
-	)
-	err = viper.BindPFlag("install-path", rootCmd.Flags().Lookup("install-path"))
-	if err != nil {
-		return errfmt.WrapError(err)
-	}
-
 	rootCmd.Flags().StringArrayP(
 		"log",
 		"l",

deploy/helm/tracee/templates/tracee-config.yaml

@@ -17,8 +17,9 @@ data:
     pprof: {{ .Values.config.pprof }}
     pyroscope: {{ .Values.config.pyroscope }}
     listen-addr: {{ .Values.config.listenAddr }}
-    {{- if .Values.config.installPath }}
-    install-path: {{ .Values.config.installPath }}
+    {{- if .Values.config.workdir }}
+    runtime:
+      - workdir={{ .Values.config.workdir }}
     {{- end }}
     {{- if .Values.config.signaturesDir }}
     signatures-dir: {{ .Values.config.signaturesDir }}

deploy/helm/tracee/values.yaml

@@ -86,7 +86,7 @@ config:
   pprof: false
   pyroscope: false
   listenAddr: :3366
-  installPath: ""
+  workdir: ""
   signaturesDir: ""
   log:
     level: info

docs/docs/flags/runtime.1.md

@@ -0,0 +1,46 @@
+---
+title: TRACEE-RUNTIME
+section: 1
+header: Tracee Runtime Flag Manual
+date: 2025/11
+...
+
+## NAME
+
+tracee **\-\-runtime** - Control runtime configurations
+
+## SYNOPSIS
+
+tracee **\-\-runtime** [workdir=*path*] [**\-\-runtime** ...]
+
+## DESCRIPTION
+
+The **\-\-runtime** flag allows you to control runtime configurations for Tracee.
+
+### Options
+
+- **workdir**=*path*
+  Set the path where Tracee will install or lookup its resources. The default value is `/tmp/tracee`.
+
+  Example:
+  ```console
+  --runtime workdir=/tmp/tracee
+  ```
+
+## EXAMPLES
+
+1. Use the default working directory:
+   ```console
+   --runtime workdir=/tmp/tracee
+   ```
+
+2. Set a custom working directory:
+   ```console
+   --runtime workdir=/var/lib/tracee
+   ```
+
+3. Using the short form:
+   ```console
+   -r workdir=/opt/tracee
+   ```
+

docs/docs/install/config/index.md

@@ -63,16 +63,23 @@ A complete config file with all available options can be found [here](https://gi
     - process
   ```
 
-### Install Path
+### Runtime
 
-- **`--install-path`**: Specifies the directory where Tracee will install or look for its resources. If not specified, the default installation directory is `/tmp/tracee`.
+- **`--runtime` (`-r`)**: Controls runtime configurations for Tracee.
+
+  CLI Examples:
+  ```bash
+  # Set working directory
+  tracee --runtime workdir=/opt/tracee
+  ```
 
   YAML:
   ```yaml
-  install-path: /opt/tracee
+  runtime:
+    - workdir=/opt/tracee
   ```
 
-  __NOTE__: This option is useful when running Tracee in environments where `/tmp` is not suitable or secure.
+  __NOTE__: The workdir is the path where Tracee will install or lookup its resources. The default is `/tmp/tracee`. This option is useful when running Tracee in environments where `/tmp` is not suitable or secure.
 
 ### Log
 

docs/docs/policies/usage/cli.md

@@ -35,7 +35,8 @@ tracee --config ./config.yaml --policy ./policy.yaml && cat /tmp/debug.json
 ### config.yaml (example)
 
 ```yaml
-install-path: /tmp/tracee
+runtime:
+  - workdir=/tmp/tracee
 
 # server configuration
 

docs/man/runtime.1

@@ -0,0 +1,49 @@
+.\" Automatically generated by Pandoc 3.2
+.\"
+.TH "TRACEE\-RUNTIME" "1" "2025/11" "" "Tracee Runtime Flag Manual"
+.SS NAME
+tracee \f[B]\-\-runtime\f[R] \- Control runtime configurations
+.SS SYNOPSIS
+tracee \f[B]\-\-runtime\f[R] [workdir=\f[I]path\f[R]]
+[\f[B]\-\-runtime\f[R] \&...]
+.SS DESCRIPTION
+The \f[B]\-\-runtime\f[R] flag allows you to control runtime
+configurations for Tracee.
+.SS Options
+.IP \[bu] 2
+\f[B]workdir\f[R]=\f[I]path\f[R] Set the path where Tracee will install
+or lookup its resources.
+The default value is \f[CR]/tmp/tracee\f[R].
+.RS 2
+.PP
+Example:
+.IP
+.EX
+\-\-runtime workdir=/tmp/tracee
+.EE
+.RE
+.SS EXAMPLES
+.IP "1." 3
+Use the default working directory:
+.RS 4
+.IP
+.EX
+\-\-runtime workdir=/tmp/tracee
+.EE
+.RE
+.IP "2." 3
+Set a custom working directory:
+.RS 4
+.IP
+.EX
+\-\-runtime workdir=/var/lib/tracee
+.EE
+.RE
+.IP "3." 3
+Using the short form:
+.RS 4
+.IP
+.EX
+\-r workdir=/opt/tracee
+.EE
+.RE

examples/config/global_config.json

@@ -9,7 +9,9 @@
     "capabilities": [],
     "containers": [],
     "healthz": false,
-    "install-path": "/tmp/tracee",
+    "runtime": [
+        "workdir=/tmp/tracee"
+    ],
     "listen-addr": ":3366",
     "log": [
         "info"

examples/config/global_config.yaml

@@ -55,7 +55,8 @@ events:
 
 healthz: false
 
-install-path: /tmp/tracee
+runtime:
+  - workdir=/tmp/tracee
 
 listen-addr: :3366
 

pkg/cmd/cobra/cobra.go

@@ -316,9 +316,16 @@
 	}
 
 	// Decide BTF & BPF files to use (based in the kconfig, release & environment info)
+	runtimeFlags, err := flags.GetFlagsFromViper(flags.RuntimeFlag)
+	if err != nil {
+		return runner, err
+	}
+	runtimeConfig, err := flags.PrepareRuntime(runtimeFlags)
+	if err != nil {
+		return runner, err
+	}
 
-	traceeInstallPath := viper.GetString("install-path")
-	err = initialize.BpfObject(&cfg, kernelConfig, osInfo, traceeInstallPath, version)
+	err = initialize.BpfObject(&cfg, kernelConfig, osInfo, runtimeConfig.Workdir, version)
 	if err != nil {
 		return runner, errfmt.Errorf("failed preparing BPF object: %v", err)
 	}
@@ -340,7 +347,7 @@
 	cfg.HealthzEnabled = runner.HTTP.HealthzEnabled()
 	runner.TraceeConfig = cfg
 	runner.Printer = p
-	runner.InstallPath = traceeInstallPath
+	runner.Workdir = runtimeConfig.Workdir
 
 	noSignaturesMode := viper.GetBool("no-signatures")
 	if noSignaturesMode {

pkg/cmd/flags/config.go

@@ -36,6 +36,8 @@ func GetFlagsFromViper(key string) ([]string, error) {
 		flagger = &OutputConfig{}
 	case "dnscache":
 		flagger = &DnsCacheConfig{}
+	case "runtime":
+		flagger = &RuntimeConfig{}
 	default:
 		return nil, errfmt.Errorf("unrecognized key: %s", key)
 	}

pkg/cmd/flags/config_test.go

@@ -335,6 +335,28 @@ server:
 				"pyroscope",
 			},
 		},
+		{
+			name: "Test runtime configuration (cli flags)",
+			yamlContent: `
+runtime:
+    - workdir=/tmp/tracee
+`,
+			key: "runtime",
+			expectedFlags: []string{
+				"workdir=/tmp/tracee",
+			},
+		},
+		{
+			name: "Test runtime configuration (structured flags)",
+			yamlContent: `
+runtime:
+    workdir: /opt/tracee
+`,
+			key: "runtime",
+			expectedFlags: []string{
+				"workdir=/opt/tracee",
+			},
+		},
 	}
 
 	for _, tt := range tests {
@@ -1022,6 +1044,7 @@ func TestOutputConfigFlags(t *testing.T) {
 		})
 	}
 }
+
 func TestServerConfigFlags(t *testing.T) {
 	t.Parallel()
 

pkg/cmd/flags/runtime.go

@@ -0,0 +1,58 @@
+package flags
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/aquasecurity/tracee/common/errfmt"
+)
+
+const (
+	RuntimeFlag    = "runtime"
+	WorkdirDefault = "/tmp/tracee"
+
+	workdirFlag        = "workdir"
+	runtimeInvalidFlag = "invalid runtime flag: %s, use 'trace man runtime' for more info"
+)
+
+// RuntimeConfig represents the configuration for the runtime.
+type RuntimeConfig struct {
+	Workdir string `mapstructure:"workdir"`
+}
+
+// flags returns the flags for the runtime configuration.
+func (c *RuntimeConfig) flags() []string {
+	return []string{fmt.Sprintf("workdir=%s", c.Workdir)}
+}
+
+// PrepareRuntime prepares the runtime configuration from the command line flags.
+func PrepareRuntime(runtimeSlice []string) (RuntimeConfig, error) {
+	runtimeConfig := RuntimeConfig{
+		Workdir: WorkdirDefault,
+	}
+	for _, flag := range runtimeSlice {
+		parts := strings.SplitN(flag, "=", 2)
+
+		if len(parts) != 2 {
+			return runtimeConfig, errfmt.Errorf(runtimeInvalidFlag, flag)
+		}
+
+		flagName := parts[0]
+		flagValue := parts[1]
+
+		switch flagName {
+		case workdirFlag:
+			workdir := strings.TrimSpace(flagValue)
+			if workdir == "" {
+				return runtimeConfig, errfmt.Errorf("invalid runtime flag: %s value can't be empty, use 'trace man runtime' for more info", flagName)
+			}
+
+			runtimeConfig.Workdir = workdir
+
+		default:
+			return runtimeConfig, errfmt.Errorf(runtimeInvalidFlag, flag)
+		}
+	}
+
+	return runtimeConfig, nil
+}