Welcome to the new Golem Cloud Docs! 👋
Invoke
CLI

Invoke using Golem CLI

The golem command line interface exposes one invocation subcommand:

  • golem agent invoke triggers a function invocation on an agent and awaits its result
  • golem agent invoke --enqueue just enqueues an invocation and returns immediately

Specifying what to invoke

The command requires specifying which agent to invoke, and the name of the function.

There are multiple options for selecting the agent:

  • agent-type(agent-parameters)
  • component-name/agent-type(agent-parameters)
  • project-name/component-name/agent-type(agent-parameters)
  • account-name/project-name/component-name/agent-type(agent-parameters)

Note that the agent-type(agent-parameters) part is also referred as the agent ID, or in previous versions, the worker name.

Also note that you can only omit the component name if it can be inferred from the context, for example if the current directory is a component directory or the application root with a single component only.

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

Encoding parameters

The CLI requires you to encode the function parameters using the WebAssembly Value Encoding (opens in a new tab) with one or more parameters following the function name (one for each invocation parameter).

Getting results

When using invoke without the --enqueue flag, 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 Type Mapping page.

Logs

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

The --stream option's output (and also the stream 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

Cancelling pending invocations

As invocations are executed sequentially, it is possible to cancel a pending invocation before it starts executing. This can be done using the command line interface by running the agent cancel-invocation subcommand:

golem agent cancel-invocation <component-name>/<agent-id> --idempotency-key <idempotency-key>
HTTPREPL