The KLI provides complete lifecycle management for Autonomic Identifiers (AIDs):

Inception Operations: The kli incept command creates new AIDs by generating an inception event that establishes the initial key state. This operation binds the identifier to its initial set of authoritative keypairs and configures critical parameters including:

• Signing thresholds (--isith) defining how many signatures are required
• Key counts (--icount) specifying the number of signing keys
• Pre-rotated keys (--ncount, --nsith) for secure key rotation
• Witness configuration (--wits) designating entities to receipt events
• Threshold of Accountable Duplicity (--toad) setting witness confirmation requirements

Key Rotation: The kli rotate command performs key rotation operations, changing the authoritative keypairs while maintaining identifier continuity. The KLI supports:

• Full rotation replacing all keys
• Partial rotation keeping some keys in reserve
• Custodial rotation enabling split authority between signing and rotation
• Multi-signature rotation requiring coordination among group members

Status Inspection: The kli status command queries the current key state of any AID, displaying:

• Current authoritative public keys
• Signing and rotation thresholds
• Witness configuration
• KEL sequence number and digest
• Delegation status if applicable

Keystore and Habitat Management

The KLI organizes cryptographic material and identifier state using the Habitat (Hab) abstraction—a keystore for one identifier. Most KLI commands require a --name parameter referencing a named Habitat:

Initialization: The kli init command creates a new keystore with:

kli init --name my-keystore \
  --passcode <encryption-password> \
  --salt <deterministic-seed> \
  --config-dir ./config \
  --config-file keystore-config.json

This creates three directory structures:

• KERI Keystore (/usr/local/var/keri/ks/{name}) - Encrypted private key storage
• KERI Database (/usr/local/var/keri/db/{name}) - KEL and state tracking
• KERI Credential Store (/usr/local/var/keri/reg/{name}) - Credential registry data

Security Model: The --passcode encrypts the keystore, while the --salt provides deterministic key generation. The salt combined with the keystore's authentication encryption identifier (aeid) deterministically generates all keypairs, enabling keystore recovery from the salt if the keystore is lost.

Multi-Signature Group Operations

The KLI provides comprehensive support for multi-signature identifiers where control authority is distributed among multiple participants:

Group Inception: Creating a multisig group requires coordination between all participants:

1. Each participant creates a local single-sig AID
2. Participants exchange OOBIs for discovery
3. One participant initiates group inception with kli multisig incept
4. Other participants join with kli multisig join
5. All participants sign the inception event
6. Once threshold signatures are collected, the group AID is established

Threshold Configuration: Groups support flexible threshold policies:

• Simple thresholds (e.g., "2 of 3")
• Weighted thresholds where participants have different voting power
• Separate thresholds for signing vs. rotation operations

Mailbox Authorization: Multi-sig operations require asynchronous coordination. The kli ends add command authorizes witnesses to act as mailboxes:

kli ends add --name keystore --alias my-aid \
  --eid <witness-aid> --role mailbox

This enables participants to deposit and retrieve messages when not simultaneously online.

Delegated Identifier Operations

The KLI implements cooperative delegation where both delegator and delegate must participate:

Delegated Inception: The kli incept command with --delpre creates a delegated AID:

kli incept --name delegate-keystore \
  --alias delegate-aid \
  --delpre <delegator-aid-prefix> \
  --file delegation-config.json

The delegator must approve by anchoring a seal of the delegated inception event in their KEL using kli delegate confirm.

Delegation Hierarchies: The KLI supports recursive delegation, enabling arbitrarily complex trees where delegates can themselves become delegators. This enables organizational hierarchies and graduated security policies.

Credential Operations (ACDC)

The KLI provides complete ACDC credential lifecycle management:

Registry Creation: Before issuing credentials, create a credential registry:

kli vc registry incept --name keystore \
  --alias issuer-aid \
  --registry-name my-registry

This creates a Transaction Event Log (TEL) anchored to the issuer's KEL for tracking credential state.

Credential Issuance: The kli vc create command issues credentials:

kli vc create --name keystore \
  --alias issuer-aid \
  --registry-name my-registry \
  --schema <schema-said> \
  --recipient <issuee-aid> \
  --data @credential-data.json

Credential Presentation: The IPEX protocol enables credential presentation:

• kli ipex grant - Holder presents credential to verifier
• kli ipex admit - Verifier accepts presented credential
• kli ipex apply - Request credential from issuer

Credential Revocation: The kli vc revoke command revokes issued credentials, updating the TEL state.

OOBI Operations

The KLI implements the OOBI protocol for discovery and trust bootstrapping:

OOBI Generation: Create OOBIs for your identifiers:

kli oobi generate --name keystore \
  --alias my-aid \
  --role witness

This produces a URL like:

http://witness-host:5642/oobi/<aid-prefix>/witness/<witness-aid>

OOBI Resolution: Resolve OOBIs to discover KELs and establish trust:

kli oobi resolve --name keystore \
  --oobi-alias contact-name \
  --oobi <oobi-url>

This retrieves the target's KEL from the specified endpoint and stores it locally for verification.

Infrastructure Operations

The KLI enables deployment and management of KERI infrastructure components:

Witness Operations: The kli witness demo command starts a demonstration witness network with six pre-configured witnesses. For production deployments, kli witness start launches individual witness nodes with custom configuration.

Watcher Operations: Watchers run in promiscuous mode, monitoring KELs for duplicity detection. The KLI provides commands for watcher deployment and KEL querying.

Agent Operations: The KLI can initialize and manage cloud agents that provide remote key management and high-availability services for identifiers.

Utility Functions

The KLI provides numerous utility commands:

Version Information: kli version displays the KERIpy version

Salt Generation: kli salt generates cryptographically secure random salts for keystore initialization

Passcode Generation: kli passcode generate creates random passphrases for keystore encryption

Timestamp Generation: kli time outputs ISO 8601 formatted timestamps

Signing and Verification:

• kli sign - Sign arbitrary data with an AID's keys
• kli verify - Verify signatures using public keys from KELs

Installation & Setup

Installation Methods

From Source (recommended for development):

git clone https://github.com/WebOfTrust/keripy.git
cd keripy
python3 -m pip install -e ./

Via PyPI (for stable releases):

pip install keri

Docker (for containerized deployments):

docker pull weboftrust/keri:1.1.32
docker run -it weboftrust/keri:1.1.32 kli version

Dependencies

Binary Requirements:

• Python 3.12.1 or higher
• libsodium 1.0.18+ (cryptographic library)

On macOS with Homebrew, libsodium requires manual linking:

sudo ln -s /opt/homebrew/lib /usr/local/lib

Python Package Dependencies:

• lmdb 0.98+ - Lightning Memory-Mapped Database for KEL storage
• pysodium 0.7.5+ - Python bindings for libsodium
• blake3 0.1.5+ - BLAKE3 hash function
• msgpack 1.0.0+ - MessagePack serialization
• simplejson 3.17.0+ - Enhanced JSON codec
• cbor2 5.1.0+ - CBOR serialization

Basic Configuration

Configuration files use JSON format and typically specify:

Keystore Configuration (keystore-config.json):

{
  "dt": "2024-01-01T00:00:00.000000+00:00",
  "iurls": [
    "http://witness1:5642/oobi/<witness-aid>/controller",
    "http://witness2:5643/oobi/<witness-aid>/controller",
    "http://witness3:5644/oobi/<witness-aid>/controller"
  ]
}

AID Inception Configuration (aid-config.json):

{
  "transferable": true,
  "wits": [
    "<witness1-aid>",
    "<witness2-aid>",
    "<witness3-aid>"
  ],
  "toad": 2,
  "icount": 1,
  "isith": "1",
  "ncount": 1,
  "nsith": "1"
}

Usage & API

Command Structure

KLI commands follow a consistent pattern:

kli <command> <subcommand> --name <keystore> --alias <aid> [options]

Common Usage Patterns

Complete Identifier Setup:

# Generate cryptographic material
SALT=$(kli salt)
PASSCODE=$(kli passcode generate)

# Initialize keystore
kli init --name my-keystore \
  --passcode "$PASSCODE" \
  --salt "$SALT" \
  --config-dir ./config \
  --config-file keystore-config.json

# Create identifier
kli incept --name my-keystore \
  --alias my-identifier \
  --file aid-config.json

# Generate OOBI for sharing
kli oobi generate --name my-keystore \
  --alias my-identifier \
  --role witness

Establishing Connections:

# Resolve contact's OOBI
kli oobi resolve --name my-keystore \
  --oobi-alias contact-name \
  --oobi "http://witness:5642/oobi/<contact-aid>/witness/<witness-aid>"

# Verify connection
kli status --name my-keystore --alias contact-name

Credential Workflow:

# Create registry
kli vc registry incept --name issuer-keystore \
  --alias issuer-aid \
  --registry-name credentials

# Issue credential
kli vc create --name issuer-keystore \
  --alias issuer-aid \
  --registry-name credentials \
  --schema <schema-said> \
  --recipient <holder-aid> \
  --data @credential.json

# List issued credentials
kli vc list --name issuer-keystore \
  --alias issuer-aid \
  --issued

# Revoke credential
kli vc revoke --name issuer-keystore \
  --alias issuer-aid \
  --registry-name credentials \
  --said <credential-said>

Integration with KERIA

The KLI can interact with KERIA cloud agents:

# Initialize agent connection
kli agent start --config-dir ./config \
  --config-file agent-config.json

# Perform operations through agent
kli incept --name agent-keystore \
  --alias agent-aid \
  --agent-url http://localhost:3901

Related Implementations

Alternative Implementations

KERIox - Rust implementation providing:

• High-performance CESR parsing
• Memory-safe cryptographic operations
• Integration with Rust ecosystem

SignifyTS - TypeScript/JavaScript client library:

• Browser-compatible KERI operations
• Integration with KERIA agents
• Signing-at-the-edge architecture

SignifyPy - Python client library:

• Programmatic KERI operations
• Alternative to CLI for automation
• Integration with Python applications

Integration Points

KERIA Integration: The KLI can bootstrap and interact with KERIA cloud agents, enabling hybrid architectures where some operations use CLI and others use agent APIs.

Witness Networks: The KLI connects to witness networks regardless of implementation, supporting interoperability across different KERI deployments.

vLEI Ecosystem: The KLI is used extensively in GLEIF vLEI workflows for QVI, Legal Entity, and role credential operations.

Implementation Architecture

Habitat (Hab) System

The KLI organizes operations around Habitats—isolated keystores for individual identifiers. Each Habitat contains:

• Encrypted private keys
• KEL database
• Credential registry
• Contact database (resolved OOBIs)
• Configuration state

This isolation enables:

• Multiple identifiers per system
• Independent security policies
• Clean separation of concerns

Event Processing Pipeline

KLI operations follow a consistent event processing pattern:

1. Command Parsing - CLI arguments parsed and validated
2. Keystore Access - Habitat unlocked with passcode
3. Event Creation - KERI event constructed per protocol
4. Signing - Event signed with authoritative keys
5. Witness Distribution - Event sent to configured witnesses
6. Receipt Collection - Witness receipts gathered
7. KEL Update - Event appended to local KEL
8. State Update - Key state updated in database

Configuration System

The KLI uses a layered configuration approach:

Default Configuration - Built-in defaults for common scenarios

File Configuration - JSON files specifying:

• Witness endpoints and AIDs
• Threshold policies
• Network timeouts
• Cryptographic parameters

Command-Line Overrides - CLI flags override file configuration

Environment Variables - System-level configuration (e.g., KERI_KEYSTORE_DIR)

Production Deployment Considerations

Security Best Practices

Keystore Protection:

• Use strong passphrases (minimum 20 characters)
• Store salts securely (equivalent to private keys)
• Consider hardware security modules for high-value identifiers
• Implement key rotation schedules

Witness Configuration:

• Use geographically distributed witnesses
• Set appropriate TOAD thresholds (typically N-1 for N witnesses)
• Monitor witness availability
• Implement witness rotation procedures

Operational Security:

• Run KLI in isolated environments
• Audit all operations
• Implement access controls
• Regular backup procedures

Performance Optimization

Database Tuning: LMDB parameters can be tuned for specific workloads:

• Map size for large KEL databases
• Read-ahead for sequential access patterns
• Write batching for bulk operations

Network Optimization:

• Connection pooling for witness communication
• Parallel OOBI resolution
• Caching of frequently accessed KELs

Monitoring and Observability

The KLI supports various logging levels:

kli --loglevel DEBUG <command>

Log output includes:

• Event creation and signing
• Witness communication
• KEL updates
• Error conditions

Ecosystem Context

The KLI serves as the reference implementation for KERI protocol operations and is used extensively in:

vLEI Ecosystem: GLEIF uses KLI for GAR, QVI, and Legal Entity operations.

Development and Testing: The KLI provides the canonical behavior for protocol operations, serving as the reference for other implementations.

Production Deployments: Organizations use KLI for operational identifier management, particularly in scenarios requiring command-line automation.

Educational Materials: Training programs use KLI to teach KERI concepts through hands-on exercises.

The KLI represents the most mature and feature-complete KERI implementation, providing the foundation for the broader KERI ecosystem.

Credential Registry Management

Credential registries (TELs) have specific requirements:

• Must be created before issuing credentials
• Registry inception is anchored in issuer's KEL via interaction event
• Registry name is local to the issuer
• Multiple registries can be created for different credential types
• Registry state changes (issuance, revocation) are anchored in issuer's KEL

Configuration File Structure

Configuration files use specific JSON structures:

Keystore Config:

{
  "dt": "<ISO-8601-timestamp>",
  "iurls": ["<witness-oobi-1>", "<witness-oobi-2>"]
}

AID Inception Config:

{
  "transferable": true,
  "wits": ["<witness-aid-1>", "<witness-aid-2>"],
  "toad": 2,
  "icount": 1,
  "isith": "1",
  "ncount": 1,
  "nsith": "1"
}

Docker Deployment Considerations

When using Docker:

• Mount local directories to /usr/local/var/keri for persistence
• Use --pull=never to ensure local image is used
• Network configuration must allow witness communication
• Volume cleanup (docker compose down -v) required for clean state

Performance Considerations

LMDB Database: The KLI uses LMDB for KEL storage:

• High-performance memory-mapped database
• Supports concurrent readers
• Single writer at a time
• Database files grow automatically
• Regular backups recommended

Witness Communication: Operations requiring witness receipts:

• Network latency affects operation completion time
• Timeout configuration in config files
• Parallel witness communication for efficiency
• Retry logic for transient failures

Error Handling

Common error scenarios:

• Keystore locked: Incorrect passcode provided
• Witness unreachable: Network connectivity or witness down
• Threshold not met: Insufficient signatures for multi-sig operation
• OOBI resolution failure: Invalid OOBI URL or endpoint unavailable
• Delegation not approved: Delegator has not confirmed delegation

Integration with Other Tools

The KLI integrates with:

• KERIA: Can bootstrap agents and perform operations through agent APIs
• vLEI-server: Resolves ACDC schemas for credential operations
• Sally: Presents credentials to verification services
• SignifyTS/SignifyPy: Complementary client libraries for programmatic access

Production Deployment Checklist

• Strong passphrases for all keystores
• Secure salt storage (equivalent to private keys)
• Geographically distributed witnesses
• Appropriate TOAD thresholds
• Regular keystore backups
• Monitoring of witness availability
• Key rotation schedule
• Audit logging enabled
• Access controls implemented
• Disaster recovery procedures documented