Golem CLI Workers

Using golem-cli worker command you can:

• Start and stop worker
• Interrupt and resume workers
• Invoke worker function
• Get worker stdout, stderr and logs
• Update workers
• Search workers, get metadata, etc.

Start new worker

Even though workers can automatically start on the first invocation, it is possible to explicitly start a worker. This allows specifying command line arguments and environment variables for the worker.

golem-cli worker add --component urn:component:d8bc9194-a4a2-4a57-8545-43408fc38799 --worker-name counter1 --env A=1 --env B=2 arg1 arg2

New worker created for component urn:component:d8bc9194-a4a2-4a57-8545-43408fc38799, with name counter1.
Worker URN: urn:worker:d8bc9194-a4a2-4a57-8545-43408fc38799/counter1

You can see the URN for your new worker in command output. You can use URN whenever you want to specify worker instead of component and worker name.

Get worker metadata

Using URN

If you know worker URN you can get worker metadata using worker get --worker command or top level get command:

golem-cli get urn:worker:d8bc9194-a4a2-4a57-8545-43408fc38799/counter1
golem-cli worker get --worker urn:worker:d8bc9194-a4a2-4a57-8545-43408fc38799/counter1

Please note that for any Golem resource URN is always the fastest option on CLI.

Using URL

For component name my-component and worker name counter1 worker URL would be worker:///my-component/counter1:

golem-cli get worker:///my-component/counter1
golem-cli worker get --worker worker:///my-component/counter1

Using worker name

You can get worker metadata using worker name and component (via --component with URN/URL or --component-name):

golem-cli worker get --component urn:component:d8bc9194-a4a2-4a57-8545-43408fc38799 --worker-name counter1

Search workers

You can search for workers of some components using worker list command with repeated --filter argument.

For instance lets find idle workers with component version older than 2:

golem-cli worker list --component urn:component:d8bc9194-a4a2-4a57-8545-43408fc38799 --filter "status = Idle" --filter "version < 2"

+----------------------------------------------------+----------+--------+-------------------+
| Component                                          | Name     | Status | Component version |
+----------------------------------------------------+----------+--------+-------------------+
| urn:component:d8bc9194-a4a2-4a57-8545-43408fc38799 | counter1 |   Idle |                 1 |
+----------------------------------------------------+----------+--------+-------------------+

Invoke functions

The folowig section shows the basics of invoking workers through the CLI. See the dedicated invocation with CLI page for more details.

Without waiting for result

You can invoke worker function without waiting for function result using worker invoke command:

golem-cli worker invoke --worker urn:worker:d8bc9194-a4a2-4a57-8545-43408fc38799/counter1 \
  --function 'rpc:counters/api.{inc-global-by}' \
  --arg 5

Function parameters can be specified using repeated --arg parameters.

Waiting for result

You can invoke worker function and wait for result using worker invoke-and-await command:

$ golem-cli worker invoke-and-await --worker urn:worker:d8bc9194-a4a2-4a57-8545-43408fc38799/counter1 \
  --function 'rpc:counters/api.{get-global-value}'
Invocation results in WAVE format:
- '5'

Ephemeral workers

Invoking ephemeral components does not require specifying the worker name, as Golem creates a new instance for each invocation. In this case only the compnent must be selected by the URN or URL:

golem-cli worker invoke-and-await --worker 'worker:///ephemeral_component' \
  --function 'demo:worker/api.{test}'

or

$ golem-cli worker invoke-and-await --worker urn:worker:d8bc9194-a4a2-4a57-8545-43408fc38799 \
    --function 'demo:worker/api.{test}'

Using idempotency key

If you want to make sure function was called only once even if you called CLI multiple times (for instance due to retries on network errors) you can use --idempotency-key parameter for both invoke and invoke-and-await commands.

You can use any string as idempotency key, but there is also a convenient method to generate a fresh idempotency key:

golem-cli worker idempotency-key

Getting worker logs

You can connect to your running worker and get logs using worker connect command this way:

golem-cli worker connect --worker urn:worker:d8bc9194-a4a2-4a57-8545-43408fc38799/counter1

You can also use --connect option on invoke and invoke-and-await commands to connect to worker right after invoking the command.

Worker update

To update worker to some specific version of worker component you can use worker update this way:

golem-cli worker update --worker urn:worker:d8bc9194-a4a2-4a57-8545-43408fc38799/counter1 --target-version 2 --mode auto

You can also use worker update-many with the same --filter parameters as in worker list command to update multiple workers:

golem-cli worker update-many --component urn:component:d8bc9194-a4a2-4a57-8545-43408fc38799 --filter 'version < 2' --target-version 2 --mode auto

Interrupt and resume workers

If you want to interrupt and later resume a long-running worker you can use interrupt and resume commands:

golem-cli worker interrupt --worker urn:worker:d8bc9194-a4a2-4a57-8545-43408fc38799/counter1
golem-cli worker resume --worker urn:worker:d8bc9194-a4a2-4a57-8545-43408fc38799/counter1

Testing worker crash recovery

There is a special command to simulate unexpected worker crush and recovery - worker simulated-crash. This command can be used for tests:

golem-cli worker simulated-crash --worker urn:worker:d8bc9194-a4a2-4a57-8545-43408fc38799/counter1

Stopping workers

Idle worker are not actively consuming resources but they take storage as their state is persisted. A worker can be deleted using the worker delete command:

golem-cli worker delete --worker urn:worker:d8bc9194-a4a2-4a57-8545-43408fc38799/counter1

This command deletes worker state.

Please note that even though the worker can be deleted this way it would be started again (with the fresh state) if used:

golem-cli worker delete --worker urn:worker:d8bc9194-a4a2-4a57-8545-43408fc38799/counter1
golem-cli worker invoke-and-await --worker urn:worker:d8bc9194-a4a2-4a57-8545-43408fc38799/counter1 --function 'rpc:counters/api.{get-global-value}'

Invocation results in WAVE format:
- '0'

Oplog query

It is possible to query an existing worker's oplog for debugging purposes. To get the full oplog of a worker, use the worker oplog command the worker must be specified just like in other golem-cli worker commands:

golem-cli worker oplog --worker urn:worker:d8bc9194-a4a2-4a57-8545-43408fc38799/counter1

Any other form of identifying a worker can be used (URL syntax, separate component-id and worker name, etc).

With the optional --from parameter it is possible to only get oplog entries after a certain oplog index:

golem-cli worker oplog --worker urn:worker:d8bc9194-a4a2-4a57-8545-43408fc38799/counter1

Oplog entries are indexed from 1, and the first entry is always a create entry that defines the initial state of the worker.

Searching for oplog entries

The same command can also be used to search for oplog entries, using the --query parameter. This parameter requries a query using lucene query syntax. The following syntax elements are supported:

• search terms looks for search AND terms
• AND, OR and NOT
• grouping using parentheses ()
• "quoted terms"
• regular expression matches using /regex/
• field:value to search for a specific information

The terms and fields are interpreted in the following way:

The cases marked with (*) can use the field:value syntax to look into the typed, structured parameter and result values.

For example to look for oplog entries that contain parameters or return values of exported functions where any of these input/output values is a record having a field product-id with either value 123 or 456, we can use the following query:

golem-cli worker oplog --worker urn:worker:d8bc9194-a4a2-4a57-8545-43408fc38799/counter1 --query 'exported-function AND (product-id:123 OR product-id:456)'