CLI for JFrog Platform Services

This page describes how to use JFrog CLI with JFrog Platform Services. For more information on the CLI in general, see JFrog CLI.

Managing JFrog Workers

Workers is a JFrog Platform service that you can use to extend and control your execution flows. It provides a serverless execution environment where you can create workers to enhance the platform's functionality.

Workers run in the following ways:

• Automatically, triggered by events within the JFrog Platform for specific use cases.
• On-demand, using HTTP-triggered workers.

For more information, see JFrog Workers. To configure workers using the JFrog Platform UI instead, see Configure Workers for Custom Flows.

This page covers the following JFrog CLI worker commands:

• Initialize JFrog Worker
• Test-Run JFrog Worker
• Deploy JFrog Worker
• Add Secrets to JFrog Worker
• Undeploy JFrog Worker
• Execute an HTTP-Triggered Worker
• List Available Events
• List Registered Workers
• Show Worker Execution History
• Edit Worker Schedule

Initialize JFrog Worker

Use this command to initialize a new JFrog worker.

This command generates the following files:

• manifest.json: Contains the Worker specification, including its name, code location, secrets, and other data useful to the Worker.
• package.json: Describes the development dependencies of the Worker. This file is not used when executing your Worker in the runtime.
• worker.ts: The Worker source code, populated with sample code for the event.
• worker.spec.ts: The source code for the Worker's 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 BEFORE_DOWNLOAD Worker

This example initializes a new BEFORE_DOWNLOAD Worker named my-worker.

jf worker init BEFORE_DOWNLOAD my-worker

Test-Run JFrog Worker

Use this command to test-run a Worker. You must initialize the Worker before running this command. The command executes the Worker with its local content, so you can use it to test the Worker's execution before pushing local changes to the server.

Test-Run JFrog Worker Example

This example test-runs a Worker that has been initialized in the current directory, using a payload from a file named payload.json in the same directory.

jf worker dry-run @payload.json

--format json output (default)

{
  "key": "my-worker",
  "workerKey": "my-worker",
  "triggeredByEvent": "BEFORE_DOWNLOAD",
  "statusCode": 200,
  "status": "STATUS_SUCCESS",
  "warnings": [],
  "errors": [],
  "debug": []
}

--format table output

jf worker dry-run @payload.json --format table

key          workerKey   triggeredByEvent   statusCode  status          warnings  errors  debug
my-worker    my-worker   BEFORE_DOWNLOAD    200         STATUS_SUCCESS

Deploy JFrog Worker

Use this command to update the worker definition (code, description, filter, secret, and so on) on your Artifactory instance.

Deploy JFrog Worker Example

Deploy a worker to the server with id my-server.

jf worker deploy --server-id my-server

--format json output

jf worker deploy --server-id my-server --format json

{
  "status_code": 200,
  "content": "{\"key\":\"my-worker\",\"version\":\"1\"}"
}

Add Secrets to JFrog Worker

Use this command to edit a worker manifest to add or edit a secret used for deployment or execution.

Secrets are stored 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.

Add Secrets to JFrog Worker Example

Add the secret name my-secret to a worker initialized in the current directory.

jf worker add-secret my-secret

Undeploy JFrog Worker

Use this command to remove a registered worker from your Artifactory instance.

Undeploy JFrog Worker Example

Undeploy a worker named my-worker from an Artifactory instance identified by my-server.

jf worker undeploy --server-id my-server my-worker

--format json output

jf worker undeploy --server-id my-server my-worker --format json

{
  "status_code": 200,
  "message": "OK"
}

Execute an HTTP-Triggered Worker

Execute an HTTP-triggered worker.

Execute an HTTP-Triggered Worker Example

Execute an HTTP-triggered worker initialized in the current directory, with a payload located in a file named payload.json from the same directory.

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"}'

--format json output (default)

{
  "key": "my-worker",
  "workerKey": "my-worker",
  "triggeredByEvent": "BEFORE_DOWNLOAD",
  "statusCode": 200,
  "status": "STATUS_SUCCESS",
  "warnings": [],
  "errors": [],
  "debug": []
}

--format table output

jf worker execute @payload.json --format table

key          workerKey   triggeredByEvent   statusCode  status          warnings  errors  debug
my-worker    my-worker   BEFORE_DOWNLOAD    200         STATUS_SUCCESS

List Available Events

This command lists all the available events on the platform. Without --format, the output is a plain comma-separated list of action names, kept for backward compatibility. Use --format table or --format json for structured output.

List Available Events Example

List events supported by a server identified by my-server.

jf worker list-event --server-id my-server

Output without --format (default)

BEFORE_DOWNLOAD, AFTER_CREATE, GENERIC_EVENT

--format table output

jf worker list-event --server-id my-server --format table

NAME                  APPLICATION   DESCRIPTION
BEFORE_DOWNLOAD       artifactory   Triggered before a download request is fulfilled
AFTER_CREATE          artifactory   Triggered after an artifact is created
GENERIC_EVENT         artifactory   Triggered on demand via `jf worker execute`

--format json output

jf worker list-event --server-id my-server --format json

[
  {
    "action": {
      "application": "artifactory",
      "name": "BEFORE_DOWNLOAD"
    },
    "description": "Triggered before a download request is fulfilled",
    "typesDefinitions": "..."
  }
]

List Registered Workers

List workers saved on your Artifactory instance. The default output is a table (CSV) with columns name, action, description, enabled, sorted by worker name. Use --format json for full JSON output.

List Registered Workers Example

List all workers registered in a platform named my-platform.

jf worker list --server-id my-platform

--format table output (default)

my-worker,BEFORE_DOWNLOAD,Intercepts download requests,true
another-worker,AFTER_CREATE,Post-creation hook,false

--format json output

jf worker list --server-id my-platform --format json

{
  "workers": [
    {
      "key": "my-worker",
      "description": "Intercepts download requests",
      "debug": false,
      "enabled": true,
      "sourceCode": "...",
      "action": "BEFORE_DOWNLOAD",
      "secrets": [],
      "projectKey": ""
    },
    {
      "key": "another-worker",
      "description": "Post-creation hook",
      "debug": false,
      "enabled": false,
      "sourceCode": "...",
      "action": "AFTER_CREATE",
      "secrets": [],
      "projectKey": ""
    }
  ]
}

Show Worker Execution History

Display the execution history of a specific worker.

Show Worker Execution History Example

Retrieves the execution history of a worker named my-worker, including test runs.

jf worker execution-history --with-test-runs my-worker

--format json output (default)

[
  {
    "workerKey": "my-worker",
    "workerType": "BEFORE_DOWNLOAD",
    "workerProjectKey": "",
    "executionStatus": "STATUS_SUCCESS",
    "startTimeMillis": 1730460000000,
    "endTimeMillis": 1730460001234,
    "triggeredBy": "[email protected]",
    "testRun": false,
    "executedVersion": "3",
    "traceId": "abc123def456"
  }
]

--format table output

jf worker execution-history --with-test-runs my-worker --format table

Worker Key   Worker Type       Project Key  Status          Started At            Ended At              Triggered By          Test Run  Executed Version  Trace ID
my-worker    BEFORE_DOWNLOAD                STATUS_SUCCESS  2024-11-01T12:00:00Z  2024-11-01T12:00:01Z  [email protected]      false     3                 abc123def456

Edit Worker Schedule

Edit the manifest of a SCHEDULED_EVENT worker to update the schedule criteria.

Deploy the worker afterward with jf worker deploy for the change to be applied to the server.

Edit Worker Schedule Example

Edit a worker manifest so that it is executed every minute.

jf worker edit-schedule --cron "* * * * *"

Frequently Asked Questions

This section provides answers to frequently asked questions.

Related Topics

• Worker Event Types
• Configure Workers for Custom Flows
• Workers Code Samples
• Understand Worker Event Workflows