Welcome to the new Golem Cloud Docs! 👋
Documentation
Invoke
CLI

Invoke using Golem CLI

The golem-cli tool exposes two invocation subcommands:

  • golem-cli worker invoke triggers a function invocation on a worker without waiting for its completion
  • golem-cli worker invoke-and-await invokes a function on a worker and awaits its result

Specifying what to invoke

Both commands require specifying which worker to invoke, and the name of the function.

There are multiple options for selecting the worker:

  • --worker urn:worker:<component-id>/<worker-name>
  • --worker worker:///<component_name>/<worker-name>
  • --component urn:component:<component-id> --worker-name <worker-name>
  • --component component:///<component-name> --worker-name <worker-name>

The function to be invoked is selected by the --function parameter. Read the invocation function name syntax page for more information about the possible function names.

Encoding parameters

The CLI provides three ways to define the invocation parameters:

  • Passing a JSON array of typed JSON values to --parameters. This is the same format as used on the HTTP invocation API.
  • Passing a JSON array of JSON values only, without type information, to --parameters. The format for encoding WebAssembly values in JSON is described on the JSON WAVE Mapping page. In this case golem-cli assumes that the invocation targets the latest version of the selected component, queries it's metadata and uses the selected function's type information for interpreting the provided JSON values.
  • Using the WebAssembly Value Encoding (opens in a new tab) with one or more --arg parameter (one for each invocation parameter).

Getting results

When using invoke-and-await, the CLI awaits the result of the invocation and prints the result value to the standard output. By default it uses the text format, in which case it prints the result value using the WebAssembly Value Encoding (opens in a new tab).

This can be changed with --format json or --format yaml to print the invocation result in JSON or YAML, using the mapping described on the JSON WAVE Mapping page.

Logs

Both invocation commands accept an optional --connect flag for conneting to the invoked worker's event stream and showing its logs. This works the same as running a separate golem-cli worker connect command during the invocation. The logs consists of everything the worker writes to its standard output and standard error, as well as through the WASI Logging API.

The --connect option's output (and also the connect subcommand) can be customized with the following parameters:

  • --format text|json|yaml for different encodings of the log lines
  • --colors=yes|no to enable/disable colors for the text format
  • --show-timestamps=yes|no to enable/disable showing timestamps for each log line
  • --show-level=yes|no to enable/disable showing the log level (or stdout/stderr) for each log line
HTTPMaking Custom APIs