From 8cb87b88976d05e8bb7c6346752f8712f7c7025e Mon Sep 17 00:00:00 2001
From: ehl-jf <hervee@jfrog.com>
Date: Sat, 5 Apr 2025 14:55:50 +0200
Subject: [PATCH] Update platform-services' worker documentation

---
 .../cli-for-jfrog-platform-services/README.md | 18 +++++++-
 .../platform-workers-add-secret.md            | 18 ++++----
 .../platform-workers-deploy.md                | 16 ++++----
 .../platform-workers-dry-run.md               | 27 ++++++------
 .../platform-workers-edit-schedule.md         | 24 +++++++++++
 .../platform-workers-execute.md               | 29 ++++++++++---
 .../platform-workers-execution-history.md     | 26 ++++++++++++
 .../platform-workers-init.md                  | 41 ++++++++++++-------
 .../platform-workers-list-event.md            | 19 +++++----
 .../platform-workers-list.md                  | 15 +++----
 .../platform-workers-undeploy.md              | 21 +++++-----
 11 files changed, 178 insertions(+), 76 deletions(-)
 create mode 100644 jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-edit-schedule.md
 create mode 100644 jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-execution-history.md

diff --git a/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/README.md b/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/README.md
index 2e3ff242..5aa0aa6c 100644
--- a/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/README.md
+++ b/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/README.md
@@ -4,8 +4,22 @@ This page describes how to use JFrog CLI with JFrog Platform Services.
 
 Read more about JFrog CLI [here](https://jfrog-external.fluidtopics.net/r/help/JFrog-CLI/JFrog-CLI).
 
-**Managing Workers**
+**Managing JFrog Workers**
 
-JFrog CLI allows you to fully manage your platform workers.
+Workers is a JFrog Platform service that allows you to extend and control your execution flows. It provides a serverless execution environment. You can create workers to enhance the platform's functionality. Workers are triggered automatically by events within the JFrog Platform, giving you the flexibility to address specific use cases. For on-demand tasks, configure Http-triggered workers.
 
+You can read more about JFrog Workers [here](https://jfrog.com/help/r/jfrog-platform-administration-documentation/workers).
 
+
+With the JFrog CLI for JFrog Worker it is possible to:
+
+- [Initialize a JFrog worker](./platform-workers-init.md)
+- [Test-Run a JFrog worker](./platform-workers-dry-run.md)
+- [Deploy a JFrog worker](./platform-workers-deploy.md)
+- [Add secrets to a JFrog worker](./platform-workers-add-secret.md)
+- [Undeploy a JFrog worker](./platform-workers-undeploy.md)
+- [Trigger an HTTP-Triggered worker](./platform-workers-execute.md)
+- [Retrieve the list of available events](./platform-workers-list-event.md)
+- [Retrieve the list of existing JFrog workers](./platform-workers-list.md)
+- [Retrieve a JFrog worker's execution history](./platform-workers-execution-history.md)
+- [Edit an SCHEDULE_EVENT worker schedule](./platform-workers-edit-schedule.md)
\ No newline at end of file
diff --git a/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-add-secret.md b/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-add-secret.md
index d135ebd7..1de281c0 100644
--- a/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-add-secret.md
+++ b/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-add-secret.md
@@ -1,13 +1,17 @@
-# Add worker secret
+# Add a secret to a worker manifest
 
 ## Overview
 
-This command is used to edit a worker manifest to add secret that can be used for deployment or/and execution.
+This command is used to edit a worker manifest in order to add or edit secret that can be used for deployment or/and execution.
 
-|                        |                                                         |
+Secrets are store encrypted with a master password that will be requested by the command.
+
+Once secrets are added to the manifest the master password will be required by the `deploy` and `test-run` commands.
+
+|                        |                       |
 |------------------------|---------------------------------------------------------|
-| Command name           | worker add-secret                                       |
-| Abbreviation           | worker as                                               |
+| Command name           | worker add-secret     |
+| Abbreviation           | worker as             |
 | **Command options:**   |                                                         |
 | `--edit`               | \[Default: false] Whether to update an existing secret. |
 | **Command arguments:** |                                                         |
@@ -18,5 +22,5 @@ This command is used to edit a worker manifest to add secret that can be used fo
 Add a secret name `my-secret` to a worker initialized in the current directory.
 
 ```
-jfrog worker add-secret my-secret
-```
\ No newline at end of file
+jf worker add-secret my-secret
+```
diff --git a/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-deploy.md b/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-deploy.md
index 6e278542..0487e98e 100644
--- a/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-deploy.md
+++ b/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-deploy.md
@@ -4,19 +4,19 @@
 
 This command is used to update the worker definition (code, description , filter, secret ...) on your Artifactory instance.
 
-|                        |                                                                                                                                                                                     |
+|                        |                       |
 |------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Command name           | worker deploy                                                                                                                                                                       |
-| Abbreviation           | worker d                                                                                                                                                                            |
-| **Command options:**   |                                                                                                                                                                                     |
-| `--server-id`          | \[Optional] Server ID configured using the config command.                                                                                                                          |
-| `--timeout-ms`         | \[Default: 5000] The request timeout in milliseconds.                                                                                                                               |
-| `--no-secrets`         | \[Default: false] Do not use registered secrets.                                                                                                                                 |
+| Command name           | worker deploy          |
+| Abbreviation           | worker d               |
+| **Command options:**   |                        |
+| `--server-id`          | \[Optional] Server ID configured using the config command. |
+| `--timeout-ms`         | \[Default: 5000] The request timeout in milliseconds. |
+| `--no-secrets`         | \[Default: false] Do not use registered secrets. |
 
 ## Example
 
 Deploy a worker to server with id `my-server`.
 
 ```
-jfrog worker server deploy --server-id my-server
+jf worker server deploy --server-id my-server
 ```
\ No newline at end of file
diff --git a/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-dry-run.md b/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-dry-run.md
index d90c50a4..17eea16c 100644
--- a/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-dry-run.md
+++ b/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-dry-run.md
@@ -1,24 +1,25 @@
-# Test a worker
+# Test Run a worker
 
 ## Overview
 
-Dry run a worker. The worker needs to be initialized before running this command.
+Test-run a worker. The worker needs to be initialized before running this command.
+The command will execute the worker with its local content, so it can be used to test the worker execution before pushing the local changes to the server.
 
-|                        |                                                                                                                                                         |
+|                        |                       |
 |------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Command name           | worker dry-run                                                                                                                                          |
-| Abbreviation           | worker dr                                                                                                                                               |
-| **Command options:**   |                                                                                                                                                         |
-| `--server-id`          | \[Optional] Server ID configured using the config command.                                                                                              |
-| `--timeout-ms`         | \[Default: 5000] The request timeout in milliseconds.                                                                                                   |
-| `--no-secrets`         | \[Default: false] Do not use registered secrets.                                                                                                        |
-| **Command arguments:** |                                                                                                                                                         |
+| Command name           | worker test-run       |
+| Abbreviation           | worker dry-run, worker dr, worker tr             |
+| **Command options:**   |                       |
+| `--server-id`          | \[Optional] Server ID configured using the config command.|
+| `--timeout-ms`         | \[Default: 5000] The request timeout in milliseconds. |
+| `--no-secrets`         | \[Default: false] Do not use registered secrets. |
+| **Command arguments:** |                       |
 | json-payload           | The json payload expected by the worker. Use `-` to read the payload from standard input. Use `@<file-path>` to read from a file located at <file-path>. |
 
 ## Example
 
-Dry run a worker initialized in the current directory, with a payload located in a file named `payload.json` from the same directory.
+Test-run a worker initialized in the current directory, with a payload located in a file named `payload.json` from the same directory.
 
 ```
-jfrog worker dry-run @payload.json
-```
\ No newline at end of file
+jf worker dry-run @payload.json
+```
diff --git a/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-edit-schedule.md b/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-edit-schedule.md
new file mode 100644
index 00000000..1609fc92
--- /dev/null
+++ b/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-edit-schedule.md
@@ -0,0 +1,24 @@
+
+# Edit a worker schedule
+
+## Overview
+
+Edit the manifest of a SCHEDULED_EVENT worker to udpate the schedule criteria.
+
+The worker should be deploy afterward with `jf worker deploy` for the change to be applied to the server.
+
+|                        |                     |
+|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Command name           | worker edit-schedule    |
+| Abbreviation           | worker es               |
+| **Command options:**   |                                                                                                                                                                                    |
+| `--cron`         | \[Mandatory] A standard cron expression with minutes resolution. Seconds resolution is not supported by Worker service. |
+| `--timezone`            | \[Default: UTC] The timezone to use for scheduling. |
+
+## Example
+
+Edit a worker manifest so that it is executed every minute.
+
+```
+jf worker edit-schedule --cron "* * * * *"
+```
diff --git a/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-execute.md b/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-execute.md
index ee89eca9..0754326b 100644
--- a/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-execute.md
+++ b/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-execute.md
@@ -4,14 +4,15 @@
 
 Execute an HTTP-triggered worker.
 
-|                        |                                                                                                                                                          |
+|                        |                        |
 |------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Command name           | worker execute                                                                                                                                           |
-| Abbreviation           | worker exec, worker e                                                                                                                                    |
+| Command name           | worker execute         |
+| Abbreviation           | worker exec, worker e  |
 | **Command options:**   |                                                                                                                                                          |
-| `--server-id`          | \[Optional] Server ID configured using the config command.                                                                                               |
-| `--timeout-ms`         | \[Default: 5000] The request timeout in milliseconds.                                                                                                    |
-| **Command arguments:** |                                                                                                                                                          |
+| `--server-id`          | \[Optional] Server ID configured using the config command. |
+| `--timeout-ms`         | \[Default: 5000] The request timeout in milliseconds. |
+| `--project-key`            | \[Optional] The key of the project that the worker belongs to.|
+| **Command arguments:** |                        |
 | worker-key             | The worker key. If not provided it will be read from the `manifest.json` in the current directory. |
 | json-payload           | The json payload expected by the worker. Use `-` to read the payload from standard input. Use `@<file-path>` to read from a file located at <file-path>. |
 
@@ -23,3 +24,19 @@ Execute an HTTP-triggered worker initialized in the current directory, with a pa
 jf worker execute @payload.json
 ```
 
+Execute an HTTP-triggered worker with a payload from the standard input.
+
+```
+jf worker execute - <<EOF
+{
+  “a”: “key”,
+  “an-integer”: 14
+}
+EOF
+```
+
+Execute an HTTP-triggered worker by providing the payload as an argument.
+
+```
+jf worker execute ‘{“my”:”payload”}’
+```
diff --git a/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-execution-history.md b/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-execution-history.md
new file mode 100644
index 00000000..5ee3e907
--- /dev/null
+++ b/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-execution-history.md
@@ -0,0 +1,26 @@
+
+# Show a worker execution history
+
+## Overview
+
+Display in a json format the execution history of a specific worker.
+
+|                        |                     |
+|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Command name           | worker execution-history    |
+| Abbreviation           | worker exec-hist, worker eh                   |
+| **Command options:**   |                                                                                                                                                                                    |
+| `--server-id`          | \[Optional] Server ID configured using the config command. |
+| `--timeout-ms`         | \[Default: 5000] The request timeout in milliseconds. |
+| `--project-key`            | \[Optional] List events available to a specific project.|
+| `--with-test-runs`         | \[Default: false]  Whether to include test-runs entries.|
+| **Command arguments:** |                    |
+| worker-key             | \[Optional]  The worker key. If not provided it will be read from the `manifest.json` in the current directory. |
+
+## Example
+
+Retrieves the execution history of a worker named `my-worker` including test runs.
+
+```
+jf worker execution-history --with-test-runs my-worker
+```
diff --git a/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-init.md b/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-init.md
index 7bbe1734..40ae15eb 100644
--- a/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-init.md
+++ b/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-init.md
@@ -2,23 +2,36 @@
 
 ## Overview
 
-This command is used to initialize a new platform worker.
-
-|                        |                                                                                                                                                                                     |
-|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Command name           | worker init                                                                                                                                                                         |
-| Abbreviation           | worker i                                                                                                                                                                            |
-| **Command options:**   |                                                                                                                                                                                     |
-| `--force`              | \[Default: false] Whether to overwrite existing files.                                                                                                                              |
-| `--no-test`            | \[Default: false] Whether to skip tests generation.                                                                                                                                 |
-| **Command arguments:** |                                                                                                                                                                                     |
-| action                 | The action that will trigger the worker (BEFORE_DOWNLOAD, AFTER_DOWNLOAD, BEFORE_UPLOAD, AFTER_CREATE, AFTER_BUILD_INFO_SAVE, AFTER_MOVE, GENERIC_EVENT, BEFORE_CREATE_TOKEN, ...). |
-| worker-name            | The name of the worker                                                                                                                                                              |
+This command is used to initialize a new JFrog worker.
+
+|                        |                         |
+|---------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Command name           | worker init |
+| Abbreviation           | worker i |
+| **Command options:**   ||
+| `--server-id`          | \[Optional] Server ID configured using the config command.|
+| `--timeout-ms`         | \[Default: 5000] The request timeout in milliseconds.|
+| `--force`              | \[Default: false] Whether to overwrite existing files. |
+| `--no-test`            | \[Default: false] Whether to skip test generation.|
+| `--application`            | \[Optional] The application that provides the event. If omitted the service will try to guess it and raise an error if no application is found.|
+| `--project-key`            | \[Optional] The key of the project that the worker should belong to.|
+| **Command arguments:** ||
+| action                 | The name of the action to init (eg: BEFORE_DOWNLOAD). To have the list of all available actions use `jf worker list-event`. |
+| worker-name            | The name of the worker.|
+
+This command will generate the following files:
+
+- `manifest.json` – The worker specification which includes its name, the code location, the secrets and all the data that is useful to the worker.
+- `package.json` – The file describing the development dependencies of the worker, this will not be used when executing your worker in our runtime.
+- `worker.ts` – The worker code source, here it will be our sample code for the event.
+- `worker.spec.ts` - The source code of the worker unit tests.
+- `tsconfig.json` - The Typescript configuration file.
+- `types.ts` - A file containing the event's specific types that can be used in the worker code.
 
 ## Example
 
 Initialize a new BEFORE_DOWNLOAD worker named `my-worker`.
 
 ```
-jfrog worker init BEFORE_DOWNLOAD my-worker
-```
\ No newline at end of file
+jf worker init BEFORE_DOWNLOAD my-worker
+```
diff --git a/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-list-event.md b/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-list-event.md
index 2f27f5e8..8fd73082 100644
--- a/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-list-event.md
+++ b/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-list-event.md
@@ -1,21 +1,22 @@
-# List events
+# List available events
 
 ## Overview
 
-This command list all the available events on your Artifactory.
+This command list all the available events on the platform.
 
-|                        |                                                                                                                                                                                     |
+|                        |                           |
 |------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Command name           | worker list-event                                                                                                                                                                   |
-| Abbreviation           | worker le                                                                                                                                                                           |
-| **Command options:**   |                                                                                                                                                                                     |
-| `--server-id`          | \[Optional] Server ID configured using the config command.                                                                                                                          |
-| `--timeout-ms`         | \[Default: 5000] The request timeout in milliseconds.                                                                                                                               |
+| Command name           | worker list-event  |
+| Abbreviation           | worker le |
+| **Command options:**   |  |
+| `--server-id`          | \[Optional] Server ID configured using the config command. |
+| `--timeout-ms`         | \[Default: 5000] The request timeout in milliseconds. |
+| `--project-key`            | \[Optional] List events available to a specific project.|
 
 ## Example
 
 List event supported by a server identified by `my-server`.
 
 ```
-jfrog worker list-event --server-id my-server
+jf worker list-event --server-id my-server
 ```
\ No newline at end of file
diff --git a/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-list.md b/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-list.md
index 65edb167..b2454607 100644
--- a/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-list.md
+++ b/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-list.md
@@ -4,14 +4,15 @@
 
 List workers saved on your Artifactory instance. The default output is a CSV format with columns `name`,`action`,`description`,`enabled`.
 
-|                        |                                                                                                                                                                                     |
+|                        |                            |
 |------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Command name           | worker list                                                                                                                                                                         |
-| Abbreviation           | worker ls                                                                                                                                                                           |
+| Command name           | worker list  |
+| Abbreviation           | worker ls    |
 | **Command options:**   |                                                                                                                                                                                     |
-| `--server-id`          | \[Optional] Server ID configured using the config command.                                                                                                                          |
-| `--json`               | \[Default: false] Whether to use JSON instead of CSV as output.                                                                                                                     |
-| `--timeout-ms`         | \[Default: 5000] The request timeout in milliseconds.                                                                                                                               |
+| `--server-id`          | \[Optional] Server ID configured using the config command. |
+| `--json`               | \[Default: false] Whether to use JSON instead of CSV as output.|
+| `--timeout-ms`         | \[Default: 5000] The request timeout in milliseconds. |
+| `--project-key`            | \[Optional] List the events created in a specific project.|
 
 
 # Example
@@ -19,5 +20,5 @@ List workers saved on your Artifactory instance. The default output is a CSV for
 List all workers registered in a platform named `my-platform` with detailed data.
 
 ```
-jfrog worker list --server-id my-platform --json
+jf worker list --server-id my-platform --json
 ```
\ No newline at end of file
diff --git a/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-undeploy.md b/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-undeploy.md
index 57e37f8b..aa0124bb 100644
--- a/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-undeploy.md
+++ b/jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-undeploy.md
@@ -4,20 +4,21 @@
 
 This command is used to remove a registered worker from you Artifactory instance.
 
-|                        |                                                                                                                                                                                    |
+|                        |                     |
 |------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Command name           | worker undeploy                                                                                                                                                                    |
-| Abbreviation           | worker rm                                                                                                                                                                          |
+| Command name           | worker undeploy    |
+| Abbreviation           | worker rm          |
 | **Command options:**   |                                                                                                                                                                                    |
-| `--server-id`          | \[Optional] Server ID configured using the config command.                                                                                                                         |
-| `--timeout-ms`         | \[Default: 5000] The request timeout in milliseconds.                                                                                                                              |
-| **Command arguments:** |                                                                                                                                                                                    |
-| worker-key             | \[Optional]  The worker key. If not provided it will be read from the `manifest.json` in the current directory.                                                                                                                                                            |
+| `--server-id`          | \[Optional] Server ID configured using the config command. |
+| `--timeout-ms`         | \[Default: 5000] The request timeout in milliseconds. |
+| `--project-key`            | \[Optional] The key of the project that the worker belongs to.|
+| **Command arguments:** |                    |
+| worker-key             | \[Optional]  The worker key. If not provided it will be read from the `manifest.json` in the current directory. |
 
 ## Example
 
-Undeploy a worker name `my-worker` from an Artifactory instance identified by `my-server`.
+Undeploy a worker named `my-worker` from an Artifactory instance identified by `my-server`.
 
 ```
-jfrog worker undeploy --server-id my-server my-worker
-```
\ No newline at end of file
+jf worker undeploy --server-id my-server my-worker
+```