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.

Select appropriate binary

There are 3 different Golem CLI binaries with the same commands.

• Universal golem-cli that supports both open sourse and hosted versions of Golem.
• Open source specific golem-cli without support for the hosted version of Golem.
• golem-cloud-cli without support for the open source version of Golem.

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
• CLI profile configuration

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

CLI profile configuration

Interactive profile configuration

To create default profile use the following command:

golem-cli init

There are 2 main options: Golem - for the standalone open source installation and Golem Cloud - for the hosted version of Golem.

Additional Golem Default option is pre-configurad profile for default docker compose installation. You can use this option if you are running golem locally via docker compose with default .env file.

You can also creade a named profile this way:

golem-cli profile init my-profile-name

Non-interact profile configuration

You can manage profiles via profile command.

This allows you to switch between your open source Golem installation and the hosted version of Golem.

Profile creation

Creating a profile (with the name Cloud) for the hosted version of Golem:

$ golem-cli profile add --set-active golem-cloud Cloud
Profile created

Creating a profile (with the name Cloud) for the hosted version of Golem using golem-cloud-cli:

$ golem-cloud-cli profile add --set-active Cloud
Profile created

Creating a profile (with the name OSS) for the open source version of Golem:

$ golem-cli profile add golem OSS --component-url http://localhost:9881
Profile created

Creating a profile (with the name OSS) for the open source version of Golem using open source specific golem-cli:

$ golem-cli profile add OSS --component-url http://localhost:9881
Profile created

Switching profile

Get profiles list:

$ golem-cli profile list
 * Cloud
   OSS

Change active profile:

$ golem-cli profile switch OSS
Active profile updated

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-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.

Output format

There are 3 output formats supported:

• text - human readable. Default.
• json
• yaml

Most of commands support output format configuration.

You can specify output format via -F (--format) option or via CLI profile configuration. You can specify default format while creating your profile, you can also change it via the following command:

golem-cli profile config format FORMAT

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 name or Golem URI:

• --project-name NAME
• --project urn:project: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 URI (an URN you get when you execute component add).

Either specify:

• --component URI if you know the URN 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 URI:

• --project-name NAME
• OR --project URI

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 worker name or worker URI.

Either specify:

• --worker URI if you know the URN - you can get it as part of worker metadata.

Or:

• --worker-name NAME if you only know its name.

When using worker name 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 URI if you know the URN 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 URI:

• --project-name NAME
• OR --project URI

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

You can specify parameters either as JSON array:

• --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 ([]) Or as separate parameters in WAVE format:
• --arg '"str"' --arg '[1, 2, 3]'

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 is one 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.

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.

Golem resources

There are multiple types of Golem Resources:

• Component
• Worker
• Worker function
• API definition
• API deployment

There are also some Golem Cloud specific resources:

• Account
• Project
• Token
• Certificate
• Domain
• Project policy

Golem resource URI

Each Golem resource can be identifyed using Golem URI.

There are 2 kinds of URI: URN and URL. In Golem CLI URN and URL can be used whenever user has to identify the resource. If you want to invoke worker function you can identify worker via --worker URI instead of worker name and component name. If you want to update component you can identify component via --component URI instead of component name and project name.

Golem resource URL

Golem resource URL supposed to be human readable and can be constructed by user.

Some examples of Golem resource URLs:

• component:///component-name - component with name component-name
• worker:///component-name/worker-name - worker with name worker-name of component component-name
• api-definition:///definition-id/version - API definition with name and version
• api-deployment:///subdomain.host

Golem resource URN

Golem resource URN is not supposed to be human readable and user should not try to cunstruct a URN. User can get resource URN as part of resource metadata. Resource creation command and resource search command should return resource URN together with resource description.

Unlike URL, resource URN requires no additional actions to resolve resource location, so it might be slightly more efficient to use URN to identify resource.

Worker URN is the same URN that should be used for worker RPC calls.

Some examples of Golem resource URNs:

• urn:component:c201c162-fd68-4750-9e7b-9aee8993beff
• urn:worker:c201c162-fd68-4750-9e7b-9aee8993beff/worker_name

Getting Golem resource metadata

Having Golem resource URI you can get resource metagata using the following command:

golem-cli get URI

This command returns resource metadata in resource type cpecific format. i.e. golem-cli get component:///component-name is similar to golem-cli component get --component-name component-name.