Utila CLI

The CLI is a tool that allows you to interact with the Utila API from the command line. Using the CLI you can set up a device, download key shares and programmatically sign transactions on a machine of your desire.

Downloads

You can download the CLI from the Resource Center in the Utila Console.

CLI Commands

vaults - Vault operations

  • list - List vaults

devices - Device Operations

  • list - List vault devices
  • register - Create device

keys - Keys and key shares operations

  • list - List vault keys
  • download - Download and activate key share

transactions - Transaction operations

  • sign - Sign a transaction

cosigner - Co-Signer operations

  • run - Run the co-signer

auth - CLI Authentication configuration

  • set-service-account-credentials - setup service account

config - CLI configuration
utils - CLI utils

  • generate-keypair - Generate RSA key-pair

For a full list of commands use the --help flag.

Authentication


Authentication in the CLI is done using a service account.
Please refer to the Set up a service account guide to create a service account.

To configure the CLI to authenticate using a service account, you'll need to set the authentication details for the service account using the auth set-service-account-credentials command, and specify the desired account to use when running a command using the --account top-level flag (or using the $UTILA_ACCOUNT environment variable).

Alternatively, you can set the authentication details of the user, in one of following forms:

  • Set the service account's private key using the $UTILA_SA_PRIVATE_KEY environment variable
  • Put the service account's private key under the config dir in the following location: /credentials//private_key.pem\

Configuration

In various CLI commands you will need to specify parameters like vault ID, device ID, key ID, etc.

As you probably will use the CLI with the same vault and the same device, for the ease of use, instead of specifying them on each and every command you can set the default parameters to use using the config set command, as follows:

./utilacli config set account <account-email>

Device Creation

To be able to sign transactions using the CLI and the co-signer, a device and a key share are needed. Follow the following steps to create a device and download a key share.

Prepare a keypair for the device

Device creation requires a key-pair which will be associated with the device. You have multiple options of key-pairs to use for the device keypair:

Re-use the keypair that is associated with the service account.
Generate a new keypair.
You can do it by yourself, or by running the following command:

./utilacli utils generate-keypair --name <key-file-name>

Create device

Once you have your keypair ready, run the following commands to create a device:

./utilacli devices register --vault-id <vault-id> --private-device-key <private-key-file-path>

Approve and sign the device

Now that you've created a device for the service account, it needs to get approved by the admin quorum, signed and get the relevant wallet keyshares, which will be used for signing transactions.

Use the Utila mobile app to approve and sign the service account's device.

Download the wallet keyshares

Now that the device has been approved and signed by the admin quorum and encrypted wallet key shares were generated and uploaded for the new device, run the following command to download and decrypt the key shares:

./utilacli keys download --vault-id <vault-id> --device-id <device-id>