Golem CLI

Golem CLI is a command-line interface for interacting with Golem. Golem CLI allows users to upload their components, launch new workers based on these components and call functions on running workers.

The main functions of the CLI are:

• creating new projects from components
• uploading a new component
• launching new workers based on these components
• invoking functions on workers
• connecting to workers to see their logs

Secondary functions of the tool are:

• authentication
• creating projects and organizing components into projects
• managing permissions for projects and accounts
• managing (transferring) ownership of projects

Registration

A new user can launch the binary and create a new account on Golem Cloud by signing up with their Github account via the oauth2 protocol.

Account registration workflow

1. Users runs any Golem CLI command that requires an account, initiating authentication.

   golem-cloud-cli account get
    >>
    >>  Application requests to perform OAuth2
    >>  authorization.
    >>
    >>  Visit following URL in a browser:
    >>
    >>   ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
    >>   ┃ https://github.com/login/device ┃
    >>   ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
    >>
    >>  And enter following code:
    >>
    >>   ┏━━━━━━━━━━━┓
    >>   ┃ 1234-ABCD ┃
    >>   ┗━━━━━━━━━━━┛
    >>
    >>  Code will expire in 14 minutes at 01:03:51.
    >>
    
   Waiting...

2. The Github OAuth server returns an access_token id to Golem CLI.

3. Golem CLI then registers a new golem_token using the access_token

   1. Golem service queries the external using the access_token to obtain login name, user name and primary email.
   2. If Golem Cloud doesn't have this user, a new account is created on-demand.
   3. Golem Cloud creates a new golem_token linked for the user and returns it.
   4. All tokens are cached in $HOME/.golem directory. It is safe to delete this directory in case of login issues, as it can be re-created through re-authentication.

Getting help

To obtain help for using the CLI, use --help. Similarly, use --help option after a subcommand to get subcommand documentation.

Creating a new component

The compiled code Golem can execute is called a golem component. Before we can upload a component we need to create its guest-language specific source and compile it to a WebAssembly program.

The following CLI commands help with this:

golem-cli list-examples

Golem has a library of examples which you can use as a starting point for your program. (The examples are defined in the open-source https://github.com/golemcloud/golem-examples (opens in a new tab) repository).

The list-examples command can list and filter the available commands for you.

• Use --language X to filter for your chosen guest language, such as Rust, Go, etc.
• Use --tier N to show only examples for a given language tier - see Building Components for a definition of tiers.

golem-cli new

Once you selected the example to use you can use the new command to create a new directory ready to be compiled to a golem component.

You have to specify two parameters:

• --example NAME with the selected example's name, for example rust-actor-minimal
• --component-name NAME with your chosen name for the new component. You can use either PascalCase, snake_case or kebab-case for the name. Try to avoid numbers if possible, as some components may have problems with it.

Optionally you can also specify a package name:

• --package-name NAME which should be in a pack:name format. If not specified the default should will be golem:component.

The command prints out the instructions specific to the generated source that describes how to compile it to a WASM file ready to be uploaded to Golem.

golem-cli component add

Once you have the compiled WASM you have to upload it to the system before you can start creating workers based on it. If it is a new component, use the component add command (if it is a new version of an existing component you can use component update).

Required parameters:

• --component-name NAME is the name of the component in Golem. You can use the same name you used for instantiating the example, but it is not necessary.
• component.wasm the path to the compiled WASM program

Optionally you can also organise your components into separate projects. If not specified, each new component is added to the default project of your account.

If needed, you can select an already created project (read below for information about how to create one) by either its ID or its name:

• --project-name NAME
• --project-id UUID

Once the component is successfully uploaded the CLI will print its metadata. The metadata contains all the detected exported functions with their type signature. See the Component Interface page for more information about types and how they are mapped to JSON structures.

Creating and invoking workers

The uploaded component is just a definition of a runnable code but it does not run by itself. You can create an arbitrary number of workers based on a component, each holding to its own state and allowing you to invoke exported functions on them.

Workers hold some per-worker data which you can specify when you create one, and can be used to store configuration of that worker. These are environment variables and the list of arguments (which would be passed to the main function if it was a regular executable process).

If you try to invoke a function on a worker that does not exist yet, it will be automatically created with the default properties (empty list of environment variables and arguments).

golem-cli worker add

The worker add command creates a new worker based on a component, but does not invoke it yet. This prepares the worker, initializes it and loads in memory.

You need to give a unique name to your worker (unique per component). If the worker corresponds to some business entity in your system, you can use the identifier of that for example.

• --worker-name NAME

You also have to specify which component to create the worker based on. This can be done by name or by the component's ID (an UUID you get when you execute component add).

Either specify:

• --component-id UUID if you know the identifier of the component

Or:

• --component-name if you only know its name.

Note that component names are only unique within a project. If you have multiple projects with components you also have to specify which project you mean, either by its name or its ID:

• --project-name NAME
• OR --project-id UUID

Optionally you can also specify a list of environment variables and a list of command line arguments which are static during the worker's lifetime and accessible through standard library functions of your chosen guest language:

• --env NAME1=VALUE1 defines an environment variable NAME1 with a value VALUE1. You can have multiple --env parameters to define more.
• arg1 arg2 ... all the remaining parameters of the command are passed to the worker as command line arguments.

The newly created worker will always use the latest version of the component that you uploaded via component add or component update.

golem-cli worker invoke-and-await

The worker invoke-and-await command executes an exported function of a worker and waits for its return value.

This is the primary command to execute something in Golem if you are also interested in its result value. Alternatively you can use worker invoke to just trigger the execution of a function without waiting for it. This is useful for long-running functions where you don't want to block until they finish running.

When invoking a function you have to specify the component your worker is based on (as worker names are only unique within a component's scope!). This can be done in multiple ways, as described above.

Either specify:

• --component-id UUID if you know the identifier of the component

Or:

• --component-name if you only know its name.

Note that component names are only unique within a project. If you have multiple projects with components you also have to specify which project you mean, either by its name or its ID:

• --project-name NAME
• OR --project-id UUID

You also have to specify the worker name:

• --worker-name NAME which is the name you gave the worker in the worker add command. If the worker does not exist, it will be created with default parameters (empty environment variables and command line arguments).

And the function to be called with all its parameters:

• --function NAME the fully qualified name of the exported function
• --parameters JSON_ARR a JSON array with all the parameters to be passed to the exported function. If the function does not expect any parameters it should be an empty array ([])

See the Component Interface page for more information about what a fully qualified exported function name is, and how to encode the different types in JSON.

There are two more optional parameters to this command:

• --idempotency-key KEY associates an idempotency key. The idempotency key can be an arbitrary, client-generated string and Golem guarantees to only execute an invocation with a given idempotency key once.
• --use-stdio switches the call into stdio mode. This is useful for tier 2 languages (see Building Components to learn more about tiers) where you cannot define your program's interface with a WIT file. In stdio mode the JSON you provide in --parameters is passed directly to the component's run (or main) function through the standard input, and the result of the call is the program's standard output.

Observing workers

golem-cli worker get

To get the status and some additional metadata about a worker you can use the worker get command.

To use this command you need to specify the component and the worker name, the same way as described above for worker invoke-and-await.

golem-cli worker list

To get the status and some additional metadata about a component workers you can use the worker list command.

To use this command you need to specify the component name or id. You can filter workers metadata:

• --filter "property op value" - filter examples: --filter "name = worker-name", --filter "version >= 0", --filter "status = Running", --filter "env.var1 = value", --filter "created_at > 2024-04-01T12:10:00Z". Can be used multiple times (AND condition is applied between them)

golem-cli worker connect

Connecting to a worker allows you to have a stream of the worker's output, similar to how kubectl log works in a Kubernetes environment.

This is an aggregated streaming log from the following sources:

• The worker's standard output
• The worker's standard error
• The worker's logs via the WASI logging interface (opens in a new tab)

To use this command you need to specify the component and the worker name, the same way as described above for worker invoke-and-await.

Full command reference

Deployment

The deployment facilities of Golem CLI allow developers to create, deploy, manage, and interact with user-defined components within Golem. There is optional --project-name parameters in all deployment commands. If no project is specified, the default project for the account is used.

Projects

The projects facilities of Golem CLI allow developers to create and manage projects, which are collections of components that are owned by an account within Golem Cloud.

When a new user account is created, an automatic default project is created for this user. When a user is working with components and workers and doesn't specify the project, the default one is assumed.

Sharing

The sharing facilities of Golem CLI allow developers to share either account- or project-level access with other accounts on Golem Cloud.

Tokens

The tokens facility of Golem CLI allow developers to create and manage tokens, which are API keys that can be used in programmatic scenarios for interacting with Golem Cloud Services.

Examples

Golem-cli can create new component source code based on examples for different languages

Account

Account command allows users to get or update account details.