# Key pair management in Chromia CLI · Chromia Docs (concept)

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

Source: https://docs.chromia.com/build/cli/key-pair-management/

# Key pair management in Chromia CLI

On this page

* [Generate your key pair](#generate-your-key-pair)
* [Key pair reading flow](#key-pair-reading-flow)
* [Key storage](#key-storage)
* [Key ID](#key-id)
* [Secret file](#secret-file)

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

## Generate your key pair

Before managing key pairs, you need to generate them first. See the [keygen command documentation](https://docs.chromia.com/build/cli/commands/keygen/)
for detailed instructions on how to create a new key pair.

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

🔑 New to key pairs? Learn why you need them and how they work

In blockchain development, key pairs are fundamental to security and identity:

* **Private Key**: Like a password - keep it secret! Used to sign transactions and prove you own an account.
* **Public Key**: Derived from your private key, safe to share. Used to verify signatures and generate your Account ID.
* **Account ID**: Generated by hashing your public key. This is your unique identifier on the blockchain.

**The relationship:**

Plain text

```
Private Key (secret) → Public Key (shareable) → Account ID (your blockchain identity)
```

**How it works in practice:**

1. You generate a private key (using `chr keygen`)
2. Your public key is automatically derived from your private key
3. Your Account ID is calculated by hashing your public key
4. You sign transactions with your private key
5. Others verify your signature using your public key, without ever seeing your private key

**Security note:** Never share your private key! Anyone with your private key can control all accounts associated with
it. If you lose your private key, you lose access to your accounts permanently.

For more about these concepts, see [Terminology](https://docs.chromia.com/reference/terminology/#key-pair).

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

Terminal

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

Terminal

```
chr keygen --file=<path>
```

[View this page on docs.chromia.com](https://docs.chromia.com/build/cli/key-pair-management/)Content mirrored from the live docs
