Command Line Interface (CLI)

The Kaleido CLI is an admin utility that abstracts the core RESTful APIs and allows for resource management calls to be sent from the command line. Authorization and Content-Type headers, as well as the targetable URL, can be persisted in a config file, keeping calls lightweight and streamlined. The standard Kaleido APIs (i.e. /consortia, /environment, /memberships and /nodes) are exposed as parameters to the command line. The SDK is also leveraged for interaction with the On-Chain Registry service when key materials and certificates are generated and maintained privately on the client side.

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

api:
  url: https://console.kaleido.io/api/v1
  key: <YOUR_API_KEY>

If you don’t have an APIKEY, login to your account and generate one.

Option 2

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:

export KLD_API_URL="https://console.kaleido.io/api/v1"
export KLD_API_KEY="YOUR_API_KEY"

The help text

The CLI tool provides nested levels of help output similar to other popular command line utilities (e.g. kubectl). The top level help printed out with ./kld -h is as follows:

Command Line Tool for Kaleido resources management

Usage:
  kld [flags]
  kld [command]

Available Commands:
  create      Create various resources: consortium, membership, environment, node
  delete      Delete various resources: consortium, membership, environment, node
  get         Get details of a resource: consortium, membership, environment, node
  help        Help about any command
  list        List various resources this user account owns: consortium, membership, environment, node

Flags:
      --config string   Config file that captures re-usable settings such as API URl, API Key, etc. (default is $HOME/.kld.yaml)
  -h, --help            help for kld

Use "kld [command] --help" for more information about a command.

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:

[
  {
    "_id": "usshelpjdb",
    "name": "consortium abc",
    "description": "cli test",
    "state": "setup"
  }
]

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:

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

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
-n – a name for the environment
-c – the consortium ID
-d – an optional description

The call will resemble the following:

./kld create environment -p geth -k poa -n "test environment" -d "cli test" -c $CONSORTIUM | jq

Example output:

[
  {
    "name": "test environment",
    "description": "cli test",
    "provider": "geth",
    "consensus_type": "poa",
    "_id": "usvyjl20za"
  }
]

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:

-c – the consortium ID
-e – the environment ID
-m – the membership ID that the node will belong to
-n – the name of the node

The call will resemble the following:

./kld create node -c $CONSORTIUM -e $ENVIRONMENT -m $org1 -n "org1 node" | jq

A successful node creation call will return a JSON array containing the details for the newly created node. Example output:

{
  "name": "org1 node",
  "membership_id": "zzzgmh6d31",
  "role": "validator",
  "state": "initializing",
  "provider": "geth",
  "consensus_type": "poa",
  "_id": "zzccu1tstd",
  "_revision": "0",
  "created_at": "2018-04-20T12:50:46.130Z"
}

You can continue to populate your environment with up to four nodes.

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. See the connect to your node section.