cloudposse
diff --git a/‎cmd/terraform/workdir/mock_workdir_manager_test.go‎
Lines changed: 14 additions & 0 deletions b/‎cmd/terraform/workdir/mock_workdir_manager_test.go‎
Lines changed: 14 additions & 0 deletions
diff --git a/‎cmd/terraform/workdir/workdir_clean.go‎
Lines changed: 64 additions & 21 deletions b/‎cmd/terraform/workdir/workdir_clean.go‎
Lines changed: 64 additions & 21 deletions
diff --git a/‎cmd/terraform/workdir/workdir_clean_cmd_test.go‎
Lines changed: 132 additions & 0 deletions b/‎cmd/terraform/workdir/workdir_clean_cmd_test.go‎
Lines changed: 132 additions & 0 deletions
@@ -21,12 +21,19 @@ var cleanCmd = &cobra.Command{
 	Long: `Remove component working directories.
 
 Use --all to clean all workdirs, or specify a component and stack to clean a specific workdir.
+Use --expired with --ttl to clean only workdirs that haven't been accessed within the TTL.
 Workdirs are ephemeral and can be regenerated by running 'atmos terraform init'.`,
 	Example: `  # Clean a specific workdir
   atmos terraform workdir clean vpc --stack dev
 
   # Clean all workdirs
-  atmos terraform workdir clean --all`,
+  atmos terraform workdir clean --all
+
+  # Clean expired workdirs (not accessed in 7 days)
+  atmos terraform workdir clean --expired --ttl=7d
+
+  # Dry run - show what would be cleaned
+  atmos terraform workdir clean --expired --ttl=24h --dry-run`,
 	Args: cobra.MaximumNArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		defer perf.Track(atmosConfigPtr, "workdir.clean.RunE")()
@@ -37,28 +44,48 @@ Workdirs are ephemeral and can be regenerated by running 'atmos terraform init'.
 			return err
 		}
 		all := v.GetBool("all")
+		expired := v.GetBool("expired")
+		ttl := v.GetString("ttl")
+		dryRun := v.GetBool("dry-run")
 		stack := v.GetString("stack")
 
 		// Validate arguments.
-		if all && len(args) > 0 {
-			return errUtils.Build(errUtils.ErrWorkdirClean).
-				WithExplanation("Cannot specify both --all and a component").
-				WithHint("Use --all alone to clean all workdirs, or specify a component and stack").
-				Err()
-		}
-
-		if !all && len(args) == 0 {
-			return errUtils.Build(errUtils.ErrWorkdirClean).
-				WithExplanation("Either --all or a component is required").
-				WithHint("Use --all to clean all workdirs, or specify a component with --stack").
-				Err()
-		}
-
-		if !all && stack == "" {
-			return errUtils.Build(errUtils.ErrWorkdirClean).
-				WithExplanation("Stack is required when cleaning a specific workdir").
-				WithHint("Use --stack to specify the stack").
-				Err()
+		if expired {
+			// --expired mode: requires --ttl, ignores --all and component.
+			if ttl == "" {
+				return errUtils.Build(errUtils.ErrWorkdirClean).
+					WithExplanation("TTL is required when using --expired").
+					WithHint("Specify a TTL like --ttl=7d or --ttl=24h").
+					Err()
+			}
+			if all || len(args) > 0 {
+				return errUtils.Build(errUtils.ErrWorkdirClean).
+					WithExplanation("Cannot use --all or component with --expired").
+					WithHint("Use --expired --ttl=<duration> alone to clean expired workdirs").
+					Err()
+			}
+		} else {
+			// Non-expired mode: standard validation.
+			if all && len(args) > 0 {
+				return errUtils.Build(errUtils.ErrWorkdirClean).
+					WithExplanation("Cannot specify both --all and a component").
+					WithHint("Use --all alone to clean all workdirs, or specify a component and stack").
+					Err()
+			}
+
+			if !all && len(args) == 0 {
+				return errUtils.Build(errUtils.ErrWorkdirClean).
+					WithExplanation("Either --all, --expired, or a component is required").
+					WithHint("Use --all to clean all workdirs, --expired --ttl to clean stale workdirs, or specify a component with --stack").
+					Err()
+			}
+
+			if !all && len(args) > 0 && stack == "" {
+				return errUtils.Build(errUtils.ErrWorkdirClean).
+					WithExplanation("Stack is required when cleaning a specific workdir").
+					WithHint("Use --stack to specify the stack").
+					Err()
+			}
 		}
 
 		// Initialize config with global flags (--base-path, --config, etc.).
@@ -71,7 +98,10 @@ Workdirs are ephemeral and can be regenerated by running 'atmos terraform init'.
 				Err()
 		}
 
-		// Clean workdirs.
+		// Clean workdirs based on mode.
+		if expired {
+			return cleanExpiredWorkdirs(&atmosConfig, ttl, dryRun)
+		}
 		if all {
 			return cleanAllWorkdirs(&atmosConfig)
 		}
@@ -103,14 +133,27 @@ func cleanSpecificWorkdir(atmosConfig *schema.AtmosConfiguration, component, sta
 	return nil
 }
 
+func cleanExpiredWorkdirs(atmosConfig *schema.AtmosConfiguration, ttl string, dryRun bool) error {
+	defer perf.Track(atmosConfig, "workdir.cleanExpiredWorkdirs")()
+
+	// Use the workdir manager's CleanExpiredWorkdirs.
+	return workdirManager.CleanExpiredWorkdirs(atmosConfig, ttl, dryRun)
+}
+
 func init() {
 	cleanCmd.DisableFlagParsing = false
 
 	// Create parser with functional options.
 	cleanParser = flags.NewStandardParser(
 		flags.WithStackFlag(),
 		flags.WithBoolFlag("all", "a", false, "Clean all workdirs"),
+		flags.WithBoolFlag("expired", "e", false, "Clean only expired workdirs (requires --ttl)"),
+		flags.WithStringFlag("ttl", "t", "", "TTL for expired cleanup (e.g., 7d, 24h, weekly)"),
+		flags.WithBoolFlag("dry-run", "n", false, "Show what would be cleaned without deleting"),
 		flags.WithEnvVars("all", "ATMOS_WORKDIR_CLEAN_ALL"),
+		flags.WithEnvVars("expired", "ATMOS_WORKDIR_CLEAN_EXPIRED"),
+		flags.WithEnvVars("ttl", "ATMOS_WORKDIR_TTL"),
+		flags.WithEnvVars("dry-run", "ATMOS_WORKDIR_DRY_RUN"),
 	)
 
 	// Register flags with the command.
 
@@ -404,3 +404,135 @@ func TestCleanSpecificWorkdir_VariousInputs(t *testing.T) {
 		})
 	}
 }
+
+func TestCleanExpiredWorkdirs_Success(t *testing.T) {
+	ctrl := gomock.NewController(t)
+	defer ctrl.Finish()
+
+	mock := NewMockWorkdirManager(ctrl)
+	mock.EXPECT().CleanExpiredWorkdirs(gomock.Any(), "7d", false).Return(nil)
+
+	// Save and restore.
+	original := workdirManager
+	defer func() { workdirManager = original }()
+	SetWorkdirManager(mock)
+
+	atmosConfig := &schema.AtmosConfiguration{}
+	err := cleanExpiredWorkdirs(atmosConfig, "7d", false)
+	assert.NoError(t, err)
+}
+
+func TestCleanExpiredWorkdirs_DryRun(t *testing.T) {
+	ctrl := gomock.NewController(t)
+	defer ctrl.Finish()
+
+	mock := NewMockWorkdirManager(ctrl)
+	mock.EXPECT().CleanExpiredWorkdirs(gomock.Any(), "30d", true).Return(nil)
+
+	// Save and restore.
+	original := workdirManager
+	defer func() { workdirManager = original }()
+	SetWorkdirManager(mock)
+
+	atmosConfig := &schema.AtmosConfiguration{}
+	err := cleanExpiredWorkdirs(atmosConfig, "30d", true)
+	assert.NoError(t, err)
+}
+
+func TestCleanExpiredWorkdirs_Error(t *testing.T) {
+	ctrl := gomock.NewController(t)
+	defer ctrl.Finish()
+
+	mock := NewMockWorkdirManager(ctrl)
+	expectedErr := errUtils.Build(errUtils.ErrWorkdirClean).
+		WithExplanation("invalid TTL").
+		Err()
+	mock.EXPECT().CleanExpiredWorkdirs(gomock.Any(), "invalid", false).Return(expectedErr)
+
+	// Save and restore.
+	original := workdirManager
+	defer func() { workdirManager = original }()
+	SetWorkdirManager(mock)
+
+	atmosConfig := &schema.AtmosConfiguration{}
+	err := cleanExpiredWorkdirs(atmosConfig, "invalid", false)
+	assert.Error(t, err)
+	assert.ErrorIs(t, err, errUtils.ErrWorkdirClean)
+}
+
+// RunE validation tests - test the command entry point validation logic.
+
+// resetViperForTest resets viper flags for test isolation.
+// Note: cmd.NewTestKit cannot be used here due to circular import between
+// cmd/terraform/workdir and cmd packages.
+func resetViperForTest(t *testing.T) {
+	t.Helper()
+	v := viper.GetViper()
+	v.Set("all", false)
+	v.Set("expired", false)
+	v.Set("ttl", "")
+	v.Set("dry-run", false)
+	v.Set("stack", "")
+}
+
+func TestCleanCmd_RunE_ExpiredWithoutTTL(t *testing.T) {
+	resetViperForTest(t)
+	v := viper.GetViper()
+	v.Set("expired", true)
+	v.Set("ttl", "") // No TTL provided.
+
+	err := cleanCmd.RunE(cleanCmd, []string{})
+	assert.Error(t, err)
+	assert.ErrorIs(t, err, errUtils.ErrWorkdirClean)
+}
+
+func TestCleanCmd_RunE_ExpiredWithAll(t *testing.T) {
+	resetViperForTest(t)
+	v := viper.GetViper()
+	v.Set("expired", true)
+	v.Set("ttl", "7d")
+	v.Set("all", true) // Cannot use --all with --expired.
+
+	err := cleanCmd.RunE(cleanCmd, []string{})
+	assert.Error(t, err)
+	assert.ErrorIs(t, err, errUtils.ErrWorkdirClean)
+}
+
+func TestCleanCmd_RunE_ExpiredWithComponent(t *testing.T) {
+	resetViperForTest(t)
+	v := viper.GetViper()
+	v.Set("expired", true)
+	v.Set("ttl", "7d")
+
+	err := cleanCmd.RunE(cleanCmd, []string{"vpc"}) // Component arg with --expired.
+	assert.Error(t, err)
+	assert.ErrorIs(t, err, errUtils.ErrWorkdirClean)
+}
+
+func TestCleanCmd_RunE_ActualCall_AllWithComponent(t *testing.T) {
+	resetViperForTest(t)
+	v := viper.GetViper()
+	v.Set("all", true)
+
+	err := cleanCmd.RunE(cleanCmd, []string{"vpc"}) // --all with component arg.
+	assert.Error(t, err)
+	assert.ErrorIs(t, err, errUtils.ErrWorkdirClean)
+}
+
+func TestCleanCmd_RunE_ActualCall_NoFlagsNoArgs(t *testing.T) {
+	resetViperForTest(t)
+
+	err := cleanCmd.RunE(cleanCmd, []string{}) // No flags, no args.
+	assert.Error(t, err)
+	assert.ErrorIs(t, err, errUtils.ErrWorkdirClean)
+}
+
+func TestCleanCmd_RunE_ActualCall_ComponentWithoutStack(t *testing.T) {
+	resetViperForTest(t)
+	v := viper.GetViper()
+	v.Set("stack", "") // No stack provided.
+
+	err := cleanCmd.RunE(cleanCmd, []string{"vpc"}) // Component without --stack.
+	assert.Error(t, err)
+	assert.ErrorIs(t, err, errUtils.ErrWorkdirClean)
+}