Workflow: wf purge --all-older-than --all-filter-status

daprdocs/content/en/developing-applications/building-blocks/workflow/howto-manage-workflow.md

@@ -135,6 +135,9 @@ dapr workflow purge order-12345
 # Purge all completed workflows older than 30 days
 dapr workflow purge --all-older-than 720h
 
+# Purge only FAILED workflows older than 30 days
+dapr workflow purge --all-older-than 720h --all-filter-status FAILED
+
 # Purge all terminal workflows (use with caution!)
 dapr workflow purge --app-id orderprocessing --all
 

daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-history-retention-policy.md

@@ -21,6 +21,24 @@ The duration is defined as a [Go duration string](https://pkg.go.dev/time#ParseD
 It can be useful to configure a short retention duration for `Completed` workflows, while retaining `Failed` and `Terminated` workflows for longer periods to allow for investigation.
 {{% /alert %}}
 
+{{% alert title="Important" color="warning" %}}
+When adding or changing a retention policy, the policy only applies to workflows that **newly reach** a configured terminal state after the policy is in effect. It does **not** retroactively clean up workflows that are already in a terminal state.
+
+To retroactively purge existing terminal workflows, use the Dapr CLI:
+
+```bash
+# Purge all terminal workflows older than a specific duration
+dapr workflow purge --app-id <app-id> --all-older-than <duration>
+
+# Purge only workflows with a specific status older than a duration
+dapr workflow purge --app-id <app-id> --all-older-than <duration> --all-filter-status COMPLETED
+dapr workflow purge --app-id <app-id> --all-older-than <duration> --all-filter-status FAILED
+dapr workflow purge --app-id <app-id> --all-older-than <duration> --all-filter-status TERMINATED
+```
+
+Note: Purge operations require a running workflow client in your application. See [How to: Manage workflows]({{% ref howto-manage-workflow.md %}}) for more details on the purge command and its requirements, including usage of the `--force` flag.
+{{% /alert %}}
+
 The following example configuration sets each of the terminal states.
 The `anyTerminal` property set here would take no effect as all terminal states are explicitly configured, however it is included for reference.
 

daprdocs/content/en/reference/cli/dapr-workflow.md

@@ -113,6 +113,7 @@ dapr workflow purge [instance-id] [flags]
 | `--app-id`, `-a` | string | (Required) The app ID owner of the workflow instances |
 | `--all` | bool | Purge all terminal workflow instances (use with caution) |
 | `--all-older-than` | string | Purge instances older than duration or timestamp (e.g., "24h", "2023-01-02T15:04:05Z") |
+| `--all-filter-status` | string | Filter purge to only instances with the given runtime status. Must be used with `--all-older-than`. One of RUNNING, COMPLETED, CONTINUED_AS_NEW, FAILED, CANCELED, TERMINATED, PENDING, SUSPENDED. Non-terminal statuses (e.g., RUNNING, PENDING, SUSPENDED) require the `--force` flag |
 | `--kubernetes`, `-k` | bool | Target a Kubernetes Dapr installation |
 | `--namespace`, `-n` | string | Kubernetes namespace (default "default") |
 
@@ -133,6 +134,11 @@ dapr workflow purge --app-id myapp --all-older-than 720h
 dapr workflow purge --app-id myapp --all-older-than 2023-12-01T00:00:00Z
 ```
 
+### Purge only FAILED instances older than 7 days
+```bash
+dapr workflow purge --app-id myapp --all-older-than 168h --all-filter-status FAILED
+```
+
 ### Purge all terminal instances (dangerous!)
 ```bash
 dapr workflow purge --app-id myapp --all