feat: add json format output to run:list

Also add some unit tests to the command.

Closes #5171

docs/development/plugin-triggers.md

@@ -2297,6 +2297,25 @@ DOKKU_SCHEDULER="$1"; APP="$2"; ARGS="${@:3}";
 # TODO
 ```
 
+### `scheduler-run-list`
+
+> Warning: The scheduler plugin trigger apis are under development and may change
+> between minor releases until the 1.0 release.
+
+- Description: Lists all run containers for a given app
+- Invoked by: `dokku run`
+- Arguments: `$DOKKU_SCHEDULER $APP $FORMAT`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+DOKKU_SCHEDULER="$1"; APP="$2"; FORMAT="$3";
+
+# TODO
+```
+
 ### `scheduler-stop`
 
 > Warning: The scheduler plugin trigger apis are under development and may change

docs/processes/one-off-tasks.md

@@ -3,7 +3,7 @@
 ```
 run [-e|--env KEY=VALUE] [--no-tty] <app> <cmd>         # Run a command in a new container using the current app image
 run:detached [-e|-env KEY=VALUE] [--no-tty] <app> <cmd> # Run a command in a new detached container using the current app image
-run:list [<app>]                                        # List all run containers for an app
+run:list [--format json|stdout] [<app>]                 # List all run containers for an app
 ```
 
 Sometimes it is necessary to run a one-off command under an app. Dokku makes it easy to run a fresh container via the `run` command.
@@ -85,3 +85,20 @@ node-js-app.run.28689   "/exec sleep 15"   2 seconds ago
 ```
 
 > The `COMMAND` displayed will be what Docker executes and may not exactly match the command specified by a `dokku run` command.
+
+The output can also be shown in json format:
+
+```shell
+dokku run:list node-js-app --format json
+```
+
+```
+[
+  {
+    "name": "node-js-app.run.28689",
+    "state": "running",
+    "command": "\"/exec 'sleep 15'\"",
+    "created_at": "2022-08-03 05:47:44 +0000 UTC"
+  }
+]
+```