Merge pull request #4909 from JoshVanL/dapr-scheduler

Adds documentation for `$ dapr scheduler`

Author: marcduiker

daprdocs/content/en/concepts/dapr-services/scheduler.md

@@ -115,25 +115,93 @@ services:
       - ./dapr_scheduler/2:/var/run/dapr/scheduler
 ```
 
-## Back Up and Restore Scheduler Data
+## Managing jobs with the Dapr CLI
 
-In production environments, it's recommended to perform periodic backups of this data at an interval that aligns with your recovery point objectives.
+Dapr provides a CLI for inspecting and managing all scheduled jobs, regardless of type.
+The CLI is the recommended way to view, back up, and delete jobs.
 
-### Port Forward for Backup Operations
+There are several different types of jobs which Scheduler manages:
 
-To perform backup and restore operations, you'll need to access the embedded etcd instance. This requires port forwarding to expose the etcd ports (port 2379).
+- `app/{app-id}/{job-name}`: Jobs created via the [Jobs API]({{% ref jobs_api %}})
+- `actor/{actor-type}/{actor-id}/{reminder-name}`: Actor reminder jobs created via the [Actor Reminders API]({{% ref "actors-timers-reminders#actor-reminders" %}})
+- `activity/{app-id}/{instance-id}::{generation-name}::{activity-index}`: Used internally for [Workflow Activity reminders]({{% ref "workflow-features-concepts.md#workflow-activities" %}})
+- `workflow/{app-id}/{instance-id}/{random-name}`: Used internally for [Workflows]({{% ref "workflow-overview.md" %}}).
 
-#### Kubernetes Example
+Please see [here for how to manage specifically reminders]({{% ref "actors-timers-reminders#managing-reminders-with-the-cli" %}}) with the CLI.
 
-Here's how to port forward and connect to the etcd instance:
+### List jobs
 
-```shell
-kubectl port-forward svc/dapr-scheduler-server 2379:2379 -n dapr-system
+```bash
+dapr scheduler list
+```
+
+Example output:
+
+```bash
+NAME                                           BEGIN     COUNT  LAST TRIGGER
+actor/myactortype/actorid1/test1               -3.89s    1      2025-10-03T16:58:55Z
+actor/myactortype/actorid2/test2               -3.89s    1      2025-10-03T16:58:55Z
+app/test-scheduler/test1                       -3.89s    1      2025-10-03T16:58:55Z
+app/test-scheduler/test2                       -3.89s    1      2025-10-03T16:58:55Z
+activity/test-scheduler/xyz1::0::1             -888.8ms  0
+activity/test-scheduler/xyz2::0::1             -888.8ms  0
+workflow/test-scheduler/abc1/timer-0-TVIQGkvu  +50.0h    0
+workflow/test-scheduler/abc2/timer-0-OM2xqG9m  +50.0h    0
+```
+
+For more detail, use the wide output format:
+
+```bash
+dapr scheduler list -o wide
+```
+
+```yaml
+NAMESPACE  NAME                                           BEGIN                 EXPIRATION            SCHEDULE         DUE TIME                   TTL     REPEATS  COUNT  LAST TRIGGER
+default    actor/myactortype/actorid1/test1               2025-10-03T16:58:55Z                        @every 2h46m40s  2025-10-03T17:58:55+01:00          100      1      2025-10-03T16:58:55Z
+default    actor/myactortype/actorid2/test2               2025-10-03T16:58:55Z                        @every 2h46m40s  2025-10-03T17:58:55+01:00          100      1      2025-10-03T16:58:55Z
+default    app/test-scheduler/test1                       2025-10-03T16:58:55Z                        @every 100m      2025-10-03T17:58:55+01:00          1234     1      2025-10-03T16:58:55Z
+default    app/test-scheduler/test2                       2025-10-03T16:58:55Z  2025-10-03T19:45:35Z  @every 100m      2025-10-03T17:58:55+01:00  10000s  56788    1      2025-10-03T16:58:55Z
+default    activity/test-scheduler/xyz1::0::1             2025-10-03T16:58:58Z                                         0s                                          0
+default    activity/test-scheduler/xyz2::0::1             2025-10-03T16:58:58Z                                         0s                                          0
+default    workflow/test-scheduler/abc1/timer-0-TVIQGkvu  2025-10-05T18:58:58Z                                         2025-10-05T18:58:58Z                        0
+default    workflow/test-scheduler/abc2/timer-0-OM2xqG9m  2025-10-05T18:58:58Z                                         2025-10-05T18:58:58Z                        0
+```
+
+### Get job details
+
+```bash
+dapr scheduler get app/my-app/job1 -o yaml
 ```
 
-### Performing Backup and Restore
+### Delete jobs
 
-Once you have access to the etcd ports, you can follow the [official etcd backup and restore documentation](https://etcd.io/docs/v3.5/op-guide/recovery/) to perform backup and restore operations. The process involves using standard etcd commands to create snapshots and restore from them.
+Delete one or more specific jobs:
+
+```bash
+dapr scheduler delete app/my-app/job1 actor/MyActor/123/reminder1
+```
+
+Bulk delete jobs with filters:
+
+```bash
+dapr scheduler delete-all all
+dapr scheduler delete-all app/my-app
+dapr scheduler delete-all actor/MyActorType
+```
+
+### Backup and restore jobs
+
+Export all jobs to a file:
+
+```bash
+dapr scheduler export -o backup.bin
+```
+
+Re-import jobs from a backup file:
+
+```bash
+dapr scheduler import -f backup.bin
+```
 
 ## Monitoring Scheduler's etcd Metrics
 
@@ -155,7 +223,7 @@ For more information on running Dapr on Kubernetes, visit the [Kubernetes hostin
 
 A number of Etcd flags are exposed on Scheduler which can be used to tune for your deployment use case.
 
-###  External Etcd database
+### External Etcd database
 
 Scheduler can be configured to use an external Etcd database instead of the embedded one inside the Scheduler service replicas.
 It may be interesting to decouple the storage volume from the Scheduler StatefulSet or container, because of how the cluster or environment is administered or what storage backend is being used.
@@ -230,4 +298,5 @@ dapr_scheduler.etcdMaxSnapshots=10
 
 ## Related links
 
-[Learn more about the Jobs API.]({{% ref jobs_api %}})
+- [Learn more about the Jobs API.]({{% ref jobs_api %}})
+- [Learn more about Actor Reminders.]{{% ref "actors-features-concepts#reminders" %}})

daprdocs/content/en/developing-applications/building-blocks/actors/actors-timers-reminders.md

@@ -187,6 +187,66 @@ To use protobuf serialization for actor reminders on self-hosted, use the follow
 --max-api-level=20
 ```
 
+## Managing reminders with the CLI
+
+Actor reminders are persisted in the Scheduler.
+You can manage them with the dapr scheduler CLI commands.
+
+#### List actor reminders
+
+```bash
+dapr scheduler list --filter actor
+NAME                                  BEGIN     COUNT  LAST TRIGGER
+actor/MyActorType/actorid1/test1      -3.89s    1      2025-10-03T16:58:55Z
+actor/MyActorType/actorid2/test2      -3.89s    1      2025-10-03T16:58:55Z
+```
+
+Get reminder details
+
+```bash
+dapr scheduler get actor/MyActorType/actorid1/test1 -o yaml
+```
+
+#### Delete reminders
+
+Delete a single reminder:
+
+```bash
+dapr scheduler delete actor/MyActorType/actorid1/test1
+```
+
+Delete all reminders for a given actor type:
+
+```bash
+dapr scheduler delete-all actor/MyActorType
+```
+
+Delete all reminders for a specific actor instance:
+
+```bash
+dapr scheduler delete-all actor/MyActorType/actorid1
+```
+
+#### Backup and restore reminders
+
+Export all reminders:
+
+```bash
+dapr scheduler export -o reminders-backup.bin
+```
+
+Restore from a backup file:
+
+```bash
+dapr scheduler import -f reminders-backup.bin
+```
+
+#### Summary
+
+- Reminders are stored in the Dapr Scheduler, not in the app.
+- Create reminders via the Actors API
+- Manage existing reminders (list, get, delete, backup/restore) using the `dapr scheduler` CLI.
+
 ## Next steps
 
 {{< button text="Configure actor runtime behavior >>" page="actors-runtime-config.md" >}}

daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-features-concepts.md

@@ -119,3 +119,60 @@ or the not-before time from which the schedule should take effect
 The `DueTime` and `Ttl` fields will reflect an RC3339 timestamp value reflective of the time zone provided when the job was
 originally scheduled. If no time zone was provided, these values indicate the time zone used by the server running
 Dapr.
+
+### Managing jobs
+
+While jobs are created via API calls, you can manage (list, inspect, delete, back up, and restore) jobs is by using the dapr scheduler CLI commands.
+
+#### List jobs
+
+```bash
+dapr scheduler list --filter app
+NAME                           BEGIN     COUNT  LAST TRIGGER
+app/my-app/my-job              -3.89s    1      2025-10-03T16:58:55Z
+app/my-app/another-job         -3.89s    1      2025-10-03T16:58:55Z
+```
+
+```bash
+dapr scheduler list -o wide
+NAMESPACE  NAME                     BEGIN                 EXPIRATION   SCHEDULE     DUE TIME                   TTL   REPEATS  COUNT  LAST TRIGGER
+default    app/my-app/my-job        2025-10-03T16:58:55Z               @every 5s   2025-10-03T17:58:55+01:00        100      1      2025-10-03T16:58:55Z
+```
+
+```bash
+dapr scheduler get app/my-app/my-job -o yaml
+```
+
+#### Delete jobs
+
+Delete a specific job:
+
+```bash
+dapr scheduler delete app/my-app/my-job
+```
+
+Delete all jobs for an app:
+
+```bash
+dapr scheduler delete-all app/my-app
+```
+
+#### Backup and restore jobs
+
+Export all jobs:
+
+```bash
+dapr scheduler export -o jobs-backup.bin
+```
+
+Import them later:
+
+```bash
+dapr scheduler import -f jobs-backup.bin
+```
+
+#### Summary
+
+- Use the Jobs API to create or update jobs from applications.
+- Use the dapr scheduler CLI to view, inspect, back up, or delete jobs.
+- Jobs are stored in the Dapr Scheduler, ensuring reliability across restarts and deployments.

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

@@ -10,6 +10,67 @@ Now that you've [authored the workflow and its activities in your application]({
 
 {{< tabpane text=true >}}
 
+<!--CLI-->
+{{% tab "CLI" %}}
+Workflow reminders are stored in the Scheduler and can be managed using the dapr scheduler CLI.
+
+#### List workflow reminders
+
+```bash
+dapr scheduler list --filter workflow
+NAME                                           BEGIN     COUNT  LAST TRIGGER
+workflow/my-app/instance1/timer-0-ABC123       +50.0h    0
+workflow/my-app/instance2/timer-0-XYZ789       +50.0h    0
+```
+
+Get reminder details
+
+```bash
+dapr scheduler get workflow/my-app/instance1/timer-0-ABC123 -o yaml
+```
+
+#### Delete workflow reminders
+
+Delete a single reminder:
+
+```bash
+dapr scheduler delete workflow/my-app/instance1/timer-0-ABC123
+```
+
+Delete all reminders for a given workflow app"
+
+```bash
+dapr scheduler delete-all workflow/my-app
+```
+
+Delete all reminders for a specific workflow instance:
+
+```bash
+dapr scheduler delete-all workflow/my-app/instance1
+```
+
+#### Backup and restore reminders
+
+Export all reminders:
+
+```bash
+dapr scheduler export -o workflow-reminders-backup.bin
+```
+
+Restore from a backup file:
+
+```bash
+dapr scheduler import -f workflow-reminders-backup.bin
+```
+
+#### Summary
+
+- Workflow reminders are persisted in the Dapr Scheduler.
+- Create workflow reminders via the Workflow API.
+- Manage reminders (list, get, delete, backup/restore) with the dapr scheduler CLI.
+
+{{% /tab %}}
+
 <!--Python-->
 {{% tab "Python" %}}
 
@@ -356,7 +417,7 @@ To resume a workflow with an ID `12345678`, run:
 curl -X POST "http://localhost:3500/v1.0/workflows/dapr/12345678/resume"
 ```
 
-### Purge a workflow 
+### Purge a workflow
 
 The purge API can be used to permanently delete workflow metadata from the underlying state store, including any stored inputs, outputs, and workflow history records. This is often useful for implementing data retention policies and for freeing resources.
 

daprdocs/content/en/getting-started/quickstarts/jobs-quickstart.md

@@ -81,6 +81,15 @@ dapr run -f .
 == APP - job-scheduler == Deleted job:  BB-8
 ```
 
+You should eventually see the jobs being scheduled in scheduler:
+
+```bash
+$ dapr scheduler list
+NAME   TARGET  BEGIN    COUNT  LAST TRIGGER
+C-3PO  job     +13.40s  0
+R2-D2  job     +3.40s   0
+```
+
 After 5 seconds, the terminal output should present the `R2-D2` job being processed:
 
 ```text
@@ -95,6 +104,13 @@ After 10 seconds, the terminal output should present the `C3-PO` job being proce
 == APP - job-service == Executing maintenance job: Memory Wipe
 ```
 
+The jobs will no longer be listed in the scheduler:
+
+```bash
+$ dapr scheduler list
+NAME  TARGET  BEGIN  COUNT  LAST TRIGGER
+```
+
 Once the process has completed, you can stop and clean up application processes with a single command.
 
 ```bash