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>