Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 96 GitHub source documents. All source documents are searchable here.
Last updated: October 7, 2025
This content is meant to be consumed by AI agents via MCP. Click here to get the MCP configuration.
Note: In rare cases it may contain LLM hallucinations.
For authoritative documentation, please consult the official GLEIF vLEI trainings and the ToIP Glossary.
The KERI Command Line Interface (KLI) is a comprehensive command-line tool for interacting with the KERI protocol, providing operations for creating and managing Autonomic Identifiers (AIDs), cryptographic keys, Key Event Logs (KELs), delegated identifiers, multi-signature groups, and infrastructure components including witnesses, watchers, and cloud agents.
The KERI Command Line Interface (KLI) is the primary command-line tool for interacting with the KERI protocol, implemented as part of KERIpy—the Python reference implementation of KERI. The KLI serves as both a developer tool and an operational interface for managing decentralized identifiers and their associated cryptographic infrastructure.
Programming Language: Python 3.12.1+
Purpose and Scope: The KLI provides comprehensive functionality spanning the entire KERI ecosystem, from basic identifier creation to complex multi-party operations. It bridges the gap between the KERI protocol specification and practical deployment, offering both low-level protocol operations and high-level workflow automation.
Relationship to Protocol Specifications: The KLI directly implements operations defined in the KERI specification, ACDC specification, OOBI protocol, and IPEX protocol. It serves as the canonical reference for how these protocols should be implemented in practice.
The --passcode and --salt parameters are equally critical to security:
Witness configuration must be consistent across operations:
Multi-sig operations require careful coordination:
kli ends add --role mailbox) is required for asynchronous coordinationVersion Compatibility: Delegation ceremonies changed significantly in KERIpy 1.2.6. Scripts and workflows designed for 1.1.x will not work with 1.2.6+ witnesses.
The delegation process requires:
--delpre flagkli delegate confirm --interactOOBI resolution follows specific patterns:
/witness/<witness-aid>)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:
--isith) defining how many signatures are required--icount) specifying the number of signing keys--ncount, --nsith) for secure key rotation--wits) designating entities to receipt events--toad) setting witness confirmation requirementsKey Rotation: The kli rotate command performs key rotation operations, changing the authoritative keypairs while maintaining identifier continuity. The KLI supports:
Status Inspection: The kli status command queries the current key state of any AID, displaying:
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:
/usr/local/var/keri/ks/{name}) - Encrypted private key storage/usr/local/var/keri/db/{name}) - KEL and state tracking/usr/local/var/keri/reg/{name}) - Credential registry dataSecurity 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.
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:
kli multisig inceptkli multisig joinThreshold Configuration: Groups support flexible threshold policies:
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.
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.
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 verifierkli ipex admit - Verifier accepts presented credentialkli ipex apply - Request credential from issuerCredential Revocation: The kli vc revoke command revokes issued credentials, updating the TEL state.
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.
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.
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 keyskli verify - Verify signatures using public keys from KELsFrom 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
Binary Requirements:
On macOS with Homebrew, libsodium requires manual linking:
sudo ln -s /opt/homebrew/lib /usr/local/lib
Python Package Dependencies:
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"
}
KLI commands follow a consistent pattern:
kli <command> <subcommand> --name <keystore> --alias <aid> [options]
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>
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
KERIox - Rust implementation providing:
SignifyTS - TypeScript/JavaScript client library:
SignifyPy - Python client library:
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.
The KLI organizes operations around Habitats—isolated keystores for individual identifiers. Each Habitat contains:
This isolation enables:
KLI operations follow a consistent event processing pattern:
The KLI uses a layered configuration approach:
Default Configuration - Built-in defaults for common scenarios
File Configuration - JSON files specifying:
Command-Line Overrides - CLI flags override file configuration
Environment Variables - System-level configuration (e.g., KERI_KEYSTORE_DIR)
Keystore Protection:
Witness Configuration:
Operational Security:
Database Tuning: LMDB parameters can be tuned for specific workloads:
Network Optimization:
The KLI supports various logging levels:
kli --loglevel DEBUG <command>
Log output includes:
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.
/controller?name=Alice&tag=contact)Credential registries (TELs) have specific requirements:
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"
}
When using Docker:
/usr/local/var/keri for persistence--pull=never to ensure local image is useddocker compose down -v) required for clean stateLMDB Database: The KLI uses LMDB for KEL storage:
Witness Communication: Operations requiring witness receipts:
Common error scenarios:
The KLI integrates with: