Invoke using Golem CLI

The golem command line interface exposes agent and native tool invocations:

golem agent invoke triggers a function invocation on an agent and awaits its result
golem agent invoke --trigger (or -t) fire-and-forget mode — triggers the invocation without waiting for the result
golem agent invoke --trigger --schedule-at <DATETIME> schedules the invocation at a specific time (ISO 8601 format; requires --trigger)
golem tool invoke invokes a deployed tool using its declared command-line interface, as described below

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:

AgentType(agent-parameters)
environment/AgentType(agent-parameters)
application/environment/AgentType(agent-parameters)
account/application/environment/AgentType(agent-parameters)

Note that AgentType(agent-parameters) is the agent ID. The agent type name uses the casing of the agent’s source language, matching the name in the source code.

The account, application and environment prefixes can be omitted when they can be inferred from the context, i.e. from the --environment/--local/--cloud flags, the selected profile, or the application manifest found from the current directory.

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 function parameters are specified as positional arguments following the function name (one for each invocation parameter), using the source language’s native syntax. See the Type Mapping page for details on how types are represented.

Getting results

When using invoke without the --trigger 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 source language syntax of the invoked agent (for example Invocation result in TypeScript syntax: followed by the value).

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

By default, agent invoke streams the agent’s standard output, standard error, and log channels live during the invocation. This works the same as running a separate golem agent stream command during the invocation. Use --no-stream (or -n) to disable this behavior.

The streaming output can be customized with the following parameters:

--stream-no-log-level to hide log levels in stream output
--stream-no-timestamp to hide timestamps in stream output
--logs-only to only show entries coming from the agent, suppressing invocation markers and stream status messages

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 <agent-id> <idempotency-key>

Invoking native tools

Tool arguments follow the tool’s declared CLI interface, regardless of its implementation language. Select exactly one owner with --agent (an existing agent) or --component (a fresh ephemeral owner), then supply the tool name. Put the tool’s subcommands, positional arguments, and flags after --. Golem options stay before that separator.

For example, if search declares a query command with a string positional argument and a --limit option:


golem tool invoke --component my-app:tool-owner search -- \
  query "durable streams" --limit 10
golem tool invoke --agent 'Assistant("alice")' search -- \
  query "durable streams" --limit 10

The owner must have a binding for the tool; a top-level implementation declaration alone does not authorize invocation. Component-targeted calls instantiate the deployed component, including core initializers, but do not select an agent type or call an agent constructor.

Tool help and argument values


golem tool invoke --help
golem tool invoke --component my-app:tool-owner search -- --help
golem tool invoke --component my-app:tool-owner search -- query --help

The first command shows Golem’s invocation options; the others show the bound tool’s root or command help without invoking it. Help and parsing use the owner’s effective deployed definition, including middleware, and require view permission on the selected agent or component’s agents in addition to invocation permission. A tool that declares its own help or -h option retains that option instead of generated help.

Strings are ordinary shell arguments; quote spaces using your shell. Numbers, booleans, and enums are parsed against the declared schema. Composite values use JSON in one shell argument. You do not supply a {schema, value} document. Declared aliases, inherited global options, defaults, repeated options, and constraints apply. Tool metadata never reads the caller’s local environment variables; pass those values explicitly if needed. Optional-valued options use --option=VALUE for an explicit value and bare --option for their declared default. A second -- belongs to the tool’s own argument grammar, for example to pass a positional value beginning with -.

Byte streams and invocation controls

Raw stream attachments are separate from structured tool arguments:


golem tool invoke --component my-app:tool-owner \
  --stdin input.bin --stdout file-tools -- transform >output.bin
golem tool invoke --component my-app:tool-owner \
  --stdin - --stdout --output output.bin \
  --stderr --stderr-output warnings.txt file-tools -- transform
golem tool invoke --component my-app:tool-owner \
  --stdout --stderr file-tools -- transform >output.bin 2>warnings.txt

These examples assume file-tools transform declares byte stdin, stdout, and stderr. --stdin - reads process stdin. --stdout writes tool stdout to process stdout unless --output PATH selects a file; --stderr similarly writes tool stderr to process stderr unless --stderr-output PATH selects a file. - is a literal output filename for both output options.

The completion report uses stdout when neither process output fd carries raw tool bytes. If only stdout is raw, the report and routine diagnostics use stderr; if only stderr is raw, they use stdout. When both are raw, the report is suppressed for structured success and tool failure so neither byte channel is corrupted. Whenever an awaited invocation or lookup observes a structured tool result, success exits with status 0 and failure exits with status 1, regardless of the selected raw streams or output files. Triggering, scheduling, and a lookup that is still pending exit successfully because they have not observed a tool failure. Direct CLI failures still use stderr. Direct at least one tool output to a file when you need both raw bytes and the structured report. Non-empty stderr does not make a successful tool result fail.

Streams use the ordinary resumable invocation transport and are checkpointed independently.

--trigger, --schedule-at, and --idempotency-key remain Golem options before --. Triggering and scheduling cannot attach live byte streams. To observe an existing invocation, use --lookup --idempotency-key KEY and supply only its tool command path after --, without input arguments. Lookup does not start a new invocation.