agent-did

Documentation

Complete guide to using agent-did CLI and OpenClaw plugin for AI agent identity management

Installation

Install the agent-did CLI globally via npm:

npm install -g agent-did

Or use without installing: npx agent-did --help

Quick Start

1

Set Owner + Agent Passphrases

export OWNER_DID_PASSPHRASE="owner-secure-passphrase"
export AGENT_DID_PASSPHRASE="agent-secure-passphrase"

OWNER_DID_PASSPHRASE is used for owner/issuer keys. AGENT_DID_PASSPHRASE is used for agent keys.

Also supported for owner operations: AGENT_DID_OWNER_PASSPHRASE. Legacy owner fallback from AGENT_DID_PASSPHRASE still works with a warning.

Create Identities

Create an owner identity (you/your organization) and an agent identity:

# Create owner
agent-did create owner --name "My Organization"

# Create agent linked to owner (separate agent passphrase by default)
agent-did create agent   --name "Support Bot"   --owner did:key:z6Mk...

# Optional: explicitly reuse owner passphrase
agent-did create agent   --name "Support Bot"   --owner did:key:z6Mk...   --reuse-owner-passphrase   --owner-passphrase "$OWNER_DID_PASSPHRASE"

Issue Credentials

Issue Verifiable Credentials to prove ownership and grant capabilities. By default, JWT files are written to ~/.agent-did/vc/ and can be discovered with agent-did vc list.

# Issue ownership credential
OWNER_DID_PASSPHRASE="owner-secure-passphrase" agent-did vc issue ownership   --issuer did:key:z6Mk...   --subject did:key:z6Mk...

# Issue capability credential
OWNER_DID_PASSPHRASE="owner-secure-passphrase" agent-did vc issue capability   --issuer did:key:z6Mk...   --subject did:key:z6Mk...   --scopes "read,write"   --expires "2025-12-31T23:59:59Z"

# Optional custom output path
agent-did vc issue ownership --issuer did:key:z6Mk... --subject did:key:z6Mk... --out ownership.jwt

# List local credentials (with optional signature verification)
agent-did vc list --verify

Authenticate

Sign authentication challenges to prove control of your DID:

# Sign challenge
AGENT_DID_PASSPHRASE="agent-secure-passphrase" agent-did auth sign   --did did:key:z6Mk...   --challenge "server-nonce"   --audience "agent-did.xyz"   --domain "agent-did.xyz"   --json

What's New: VC Storage + Listing Fix

# Migrate legacy JWT files into canonical vc/ directory
agent-did keystore doctor --migrate-vc --yes

# Optional: move instead of copy
agent-did keystore doctor --migrate-vc --move --yes

# Inspect full keystore health (keys, vc, backups, permissions)
agent-did keystore doctor --json

Command Reference

Identity Management

Create owner identity

agent-did create owner --name "Organization Name" [--owner-passphrase <passphrase>]

Create agent identity

agent-did create agent --name "Agent Name" --owner <owner-did> [--agent-passphrase <passphrase>]

List all identities

agent-did list

Inspect a DID

agent-did inspect --did <did>

Delete identity

agent-did delete --did <did> --yes
Verifiable Credentials

Issue ownership credential

agent-did vc issue ownership --issuer <did> --subject <did> [--owner-passphrase <passphrase>] [--out <file>] [--no-store]

Issue capability credential

agent-did vc issue capability --issuer <did> --subject <did> --scopes "read,write" [--owner-passphrase <passphrase>] --expires "2025-12-31" [--out <file>] [--no-store]

Verify credential

agent-did vc verify --file credential.jwt

List local credential JWT files

agent-did vc list [--verify]

Scans ~/.agent-did/vc/ plus legacy ~/.agent-did/credentials/*.jwt.

Revoke credential

agent-did vc revoke --file credential.jwt --reason "Revocation reason"
Authentication

Sign authentication challenge

agent-did auth sign --did <did> --challenge <nonce> --audience "agent-did.xyz" --domain "agent-did.xyz" [--agent-passphrase <passphrase>] --json

Verify signature

agent-did auth verify --did <did> --payload <base64> --signature <base64>
Key Rotation

Rotate key for a DID

agent-did rotate-key --did <did> --reason "Security rotation"

View rotation history

agent-did rotation-history
Keystore Management

Check keystore health

agent-did keystore doctor

Migrate legacy credential JWT files

agent-did keystore doctor --migrate-vc --yes

Backup keystore

agent-did keystore backup --out backup.json --encrypt

Restore keystore

agent-did keystore restore --file backup.json

Common Options

--json

Output as JSON for scripting

--owner-passphrase <passphrase>

Owner/issuer key passphrase override

--agent-passphrase <passphrase>

Agent key passphrase override

--no-encryption

Skip keystore encryption (dev only)

--store <path>

Custom keystore location

--out <file>

Write JWT to file; still stores in ~/.agent-did/vc/ unless --no-store

--no-store

Skip keystore metadata storage and skip default ~/.agent-did/vc/ storage

Environment Variables

OWNER_DID_PASSPHRASE

Passphrase for owner/issuer key decryption and owner key creation.

AGENT_DID_PASSPHRASE

Passphrase for agent key decryption and agent key creation.

AGENT_DID_OWNER_PASSPHRASE

Alternate owner env var name for compatibility with existing setups.

AGENT_DID_HOME

Custom keystore path (default: ~/.agent-did)

CLI & OpenClaw Compatibility

The CLI and OpenClaw plugin share the same keystore and are fully interchangeable:

# Create with plugin
openclaw agent-did create owner --name "Alice"

# List with CLI
agent-did list

# Both access the same identities and credentials

For AI Agents

Download the SKILL.md file to teach AI agents how to use these tools.

Download SKILL.mdView Directory