Golem CLI Components

Golem components are WASM components deployed to Golem for execution.

To create, list and update component you can use golem-cli component command.

Component creation

To create a new component, use component add command in the following way:

golem-cli component add --component-name my-component counters.wasm

New component created with URN urn:component:d8bc9194-a4a2-4a57-8545-43408fc38799, version 0, and size of 89735 bytes.
Component name: my-component.
Exports:
        rpc:counters/api.{[constructor]counter}(name: string) -> handle<0>
        rpc:counters/api.{[method]counter.inc-by}(self: &handle<0>, value: u64)
        rpc:counters/api.{[method]counter.get-value}(self: &handle<0>) -> u64
        rpc:counters/api.{[method]counter.get-args}(self: &handle<0>) -> list<string>
        rpc:counters/api.{[method]counter.get-env}(self: &handle<0>) -> list<tuple<string, string>>
        rpc:counters/api.{inc-global-by}(value: u64)
        rpc:counters/api.{get-global-value}() -> u64
        rpc:counters/api.{get-all-dropped}() -> list<tuple<string, u64>>
        rpc:counters/api.{bug-wasm-rpc-i32}(in: variant { leaf }) -> variant { leaf }
        rpc:counters/api.{[drop]counter}(self: handle<0>)

The returned output contains the following information:

• Component URN - URN for the new component. You can use this URN whenever you want to specify the component instead of component name.
• Component version - incremental component version - used for updating the workers.
• Component size - size of the wasm file - it is important for the storage limit in the hosted Golem Cloud.
• Exports - exported function you can call. You can copy function name (the part before parameters) to call the function. All Golem API expect function names in exactly this format. See the function name reference page for more details.

Ephemeral components

Components created are durable by default. To create an ephemeral component instead, use the --ephemeral flag:

golem-cli component add --ephemeral --component-name my-component counters.wasm

Component search

Using URN

If you know component URN you can always get the component metadata using component get --component command or the top level get command:

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

Using component name and the latest version

If you want to get the latest version of the component using its name you can either use a URL or --component-name option.

For component name my-component and the latest version URL would be component:///my-component - you can use URL the same way as URN:

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

Alternatively you could use --component-name argument this way:

golem-cli component get --component-name my-component

Using component name and specific version

If you want to get the specific version of the component using its name you can either use a URL or a combination of the --component-name and --version options.

For component name my-component and version 0 URL would be component:///my-component/0 - you can use URL the same way as URN:

golem-cli get component:///my-component/0
golem-cli component get --component component:///my-component/0

Alternatively you could use --component-name argument this way:

golem-cli component get --component-name my-component --version 0

Getting component list

To get all component versions for specific component name you can use component list command with --component-name this way:

golem-cli component list --component-name my-component

To get all component available you can use component list command this way:

golem-cli component list

Updating component

To update component you can use component update command. This command creates a new version for existing component. To identify component you can use URN, URL and component name:

golem-cli component update --component urn:component:d8bc9194-a4a2-4a57-8545-43408fc38799 counters-v1.wasm
golem-cli component update --component component:///my-component counters-v1.wasm
golem-cli component update --component-name my-component counters-v1.wasm

If you want to trigger an update all worker to the new latest version right after creating this version you can use --try-update-workers option.

It is possible to change the component's type (from durable to ephemeral, or from ephemeral to durable) when updating the component. To do this, use the --ephemeral or --durable flags:

golem-cli component update --durable --component-name my-component counters-v2.wasm

Updating workers

If you want to update all workers you can use component try-update-workers command.

This command gets all workers for the component that are not using the latest version and triggers an update for them one by one:

golem-cli component try-update-workers --component urn:component:d8bc9194-a4a2-4a57-8545-43408fc38799

The update request is enqueued and processed by the workers asynchronously, golem-cli cannot await for the update to finish.

Redeploying workers

During the development of a Golem Component, it is often necessary to quickly rebuild the code, update the component and just restart all the test workers from scratch to test the changes.

This is different from updating the workers as they will loose their state, but it can speed up the feedback loop during development.

This workflow is supported by the component redeploy command:

golem-cli component redeploy --component urn:component:d8bc9194-a4a2-4a57-8545-43408fc38799

This command deletes all workers that are not using the latest version of component and re-creates them with the same name, parameters and environment variables.