Key pair management in Chromia CLI

This document describes how key pairs are read and managed within the Chromia CLI for various commands.

Prerequisites: Generate your key pair

Before managing key pairs, you need to generate them first. See the keygen command documentation for detailed instructions.

Once you have generated your key pair, you can configure and manage how the CLI uses it across different operations.

Key pair reading flow

The Chromia CLI follows a specific precedence order when determining which key pair to use for operations, from highest precedence to lowest:

1. Secret file option

   • The --secret option pointing to a file containing key pair information takes the highest precedence
   • This overrides all other key pair sources

2. Key ID option

   • If the user specifies a key ID directly using the --key-id option for a command, this takes precedence over all configuration files
   • Keys are still located and read from the ~/.chromia directory

3. Explicit configuration path

   • If a user specifies a configuration path using the --config option, the key.id from that configuration takes precedence
   • Keys are still located and read from the ~/.chromia directory

4. Project-specific configuration

   • If a project has a local configuration file at the default location <project-path>/.chromia/config, the property key.id = <key_id> specified there takes precedence over the global configuration
   • Keys are still located and read from the ~/.chromia directory

5. Global configuration

   • Finally, if none of the above are set, the CLI reads the property key.id = <key_id> from the global configuration file located at ~/.chromia/config
   • This global configuration applies to all commands unless overridden

Key storage

Key ID

Keys are stored in the ~/.chromia directory by default. When using the keygen command with the --key-id option, the following files are created:

• ~/.chromia/{key-id} – Contains the private key
• ~/.chromia/{key-id}.pubkey – Contains the public key
• ~/.chromia/{key-id}_mnemonic – Contains the mnemonic phrase for recovery

chr keygen --key-id=<value>

Secret file

When using the keygen command with the --file option the following files are created:

• <file_name> – Contains the keypair
• <file_name>_mnemonic – Contains the mnemonic phrase for recovery

chr keygen --file=<path>