Using the Kaleido CLI

The Kaleido CLI is a lightweight interface that abstracts the REST API and allows administrative resource management calls to be sent from the command line while forgoing the common Authorization and Content-Type headers, as well as the API URL. The standard Kaleido APIs (i.e. /consortia, /environment, /memberships and /nodes) are exposed as parameters to the command line.

Download the binary

Visit the Kaleido CLI github repository release page and download the appropriate version based on your operating system. Mac, Linux and Windows 64bit versions are supplied as available OS flavors. The CLI will download as kld-$OS into your /Downloads directory (e.g. $HOME/Downloads/kld-mac). Remove the OS tag and save as kld. Then move the tool into an alternate working directory of your choice, and make it an executable.

chmod +x kld

Configuration

The CLI requires two pieces of configuration – APIURL and APIKEY. The tool can ingest these variables in one of two ways:

supplied directly as environment variables in the present working directory of the tool

specified through a configuration file in .yaml, .json or .toml format.

the --config flag can be used to specify the explicit location of the file

if --config is not supplied, the tool looks in the home directory for a .kld.<yaml/json/toml> file

NOTE: Environment variables take precedent and will override the same properties supplied via config files

Option 1

In your home directory create a .kld.yaml, .kld.json or .kld.toml file and provide the following values:

Place the configuration file in a directory of your choosing and specify the explicit path with the --config flag when exercising the tool. The configuration file does not need to be hidden if it exists outside the default home directory. For example:

./kld --config /path/to/your/kld.yaml create consortium

Option 3

Set the values through environment variables in the present working directory of the CLI. Environment variables will override any configuration files, even if --config is passed. The variables must be declared in all caps as KLD_API_URL and KLD_API_KEY. For example:

You can use the help command to reveal the required fields for any calls. For example:

./kld create -h

./kld create consortium -h

As you start provisioning resources, use the list command to reveal resource overviews. For example:

./kld consortium list | jq

Or use the get command to see details about specific resources. For example:

./kld get consortium --id <consortium_id> | jq

Create a consortium

Using the help command, a ./kld create consortium -h reveals that this call requires values for two flags:

-n – a name for the consortium

-d – a brief description of the consortium

The call will resemble the following:

./kld create consortium -n "consortium abc" -d "cli test" | jq

And if successful, will return a JSON array with details for the consortium. Using the list command, a ./kld consortium list | jq will return an overview of the existing consortia associated with your account. Example output:

Take note of the consortium ID and optionally export as an environment variable for convenience. This ID is required on subsequent calls to create memberships, environments, nodes and app credentials. For example:

export CONSORTIUM="usshelpjdb"

Each organization can be privy to up to two consortia.

Create/delete members

The newly created consortium is provisioned with an auto-generated Default Organization. Using the listcommand, a ./kld list membership -c $CONSORTIUM | jq will reveal the details. Example output:

[{"org_name":"Default Organization","_id":"uspxumxerp"}]

NOTE: This org can be deleted after the creation of a subsequent membership

create members

Go ahead and create a few unique member organizations to participate in the network. Using the helpcommand, a ./kld create membership -h reveals that this call requires values for two flags:

-c – the consortium ID the member will join

-n – a name for the member

The call will resemble the following:

./kld create membership -c $CONSORTIUM -n org1 | jq

A successful membership creation will return a JSON array containing the membership-specific details of the newly created org. Passing the ./kld list membership -c $CONSORTIUM | jq call again will reveal the newly created membership as a part of the consortium. Example output:

As with the consortium ID, take note of the membership ID and optionally export it as an environment variable for convenience. This ID is required on subsequent calls to create nodes and app credentials. For example:

export org1="uscehmk6bz"

Continue to populate your consortium with up to four memberships.

delete members

The auto-generated org (or any other orgs) can be removed from the consortium by calling the delete membership command against the consortium ID and targeted membership ID. The call will resemble the following:

./kld delete membership -c $CONSORTIUM --id uspxumxerp

Create/delete environments

Newly created consortia are, by default, devoid of environments. Environments are the isolated domains used to host the node runtimes and provision app credentials.

Using the list command, a ./kld list environment -c $CONSORTIUM | jq should return an empty array indicating a lack of environments. Let’s go ahead and spin one up:

create environments

Using the help command, a ./kld create environment -h reveals that this call requires values for four flags and one optional flag:

-p – the underlying client protocol, where quorum and geth are accepted values

-k – the consensus algorithm for the specified protocol. quorum defaults to raft and accepts ibft as an alternate value. geth requires a value of poa

You can continue to populate your consortium with up to three environments.

Consider exporting each environment ID as an environment variable as well. The upcoming create node call requires a value for the environment parameter, as nodes are always defined within the context of a specific environment.

delete environments

Any environment can be removed by calling the delete environment command against the consortium ID and targeted environment ID. The call will resemble the following:

./kld delete environment -c $CONSORTIUM --id usvyjl20za

Create/delete nodes

Once you have a consortium populated with member organizations and an active environment, you can start provisioning nodes on behalf of the member organizations. Using the help command, a ./kld create node -h reveals that this call requires values for four flags:

Use the list command and a ./kld list node -c $CONSORTIUM -e $ENVIRONMENT | jq call to return a listing of all nodes in a specified environment. Use the get command to retrieve details about a specific node. For example:

./kld get node -c $CONSORTIUM -e $ENVIRONMENT -n <node_ID> | jq

Generate authentication credentials

You can follow one of two routes to generate the basic access auth credentials: UI or admin REST API. The connect to your node section outlines the two processes and exposes the proper way to connect using the web3.provider API.