Cardano PRISM CLI

The cardano-prism CLI is a tool for managing PRISM DIDs on the Cardano blockchain. It supports key management, DID creation/resolution, VDR (Verifiable Data Registry) operations, and two ways of submitting to the chain — either directly via the Blockfrost API, or by handing the transaction off to a CIP-30 browser wallet (Lace, Eternl, Nami, Yoroi, …). The CLI is structured around modules: mnemonic, key, did, cardano, website, indexer, and vdr.

Install

Install with Coursier

Install Coursier (a pure Scala artifact fetching tool), then set up the alias:

alias cardano-prism='cs launch app.fmgp::cardano-prism-cli:0.1.0-M42 -M fmgp.did.method.prism.cli.PrismCli --'

# Or with fewer JVM warnings
alias cardano-prism='cs launch --java-opt --sun-misc-unsafe-memory-access=allow app.fmgp::cardano-prism-cli:0.1.0-M42 -M fmgp.did.method.prism.cli.PrismCli --'

cardano-prism --help

Install with Homebrew

A brew tap (homebrew-fmgp) is available for installing cardano-prism:

brew install FabioPinheiro/fmgp/cardano-prism
cardano-prism --help

Configuration File

The CLI uses a JSON configuration file (staging state) to persist keys, wallets, and Blockfrost API tokens between commands.

Default location: ~/.cardano-prism-config.json

Create the config file

cardano-prism config-file --create

View the current config

cardano-prism config-file

The config file stores:

SSI and Cardano wallet mnemonics
Derived private keys (Secp256k1, Ed25519, X25519) and randomly generated keys
Blockfrost API tokens per network

Most commands automatically load the config file. Use the -s flag to enable automatic saving of state changes at the end of a command.

Mnemonic Management (`mnemonic`)

Mnemonics are BIP-39 seed phrases used to deterministically derive keys for both the SSI (DID) wallet and the Cardano (ADA) payment wallet.

Generate a new mnemonic

# Generate and save a new SSI wallet mnemonic (saves with -s flag)
cardano-prism mnemonic new -s

# Generate a new ADA wallet mnemonic
cardano-prism mnemonic new -s --wallet-type ada

# Import an existing mnemonic
cardano-prism mnemonic new -s --mnemonic "word1 word2 ... word24"

Display the seed (hex)

# Show seed from stored SSI wallet
cardano-prism mnemonic seed

# Show seed from a specific mnemonic
cardano-prism mnemonic seed --mnemonic "word1 word2 ... word24"

Derive a Cardano address

# Show address for the stored Cardano wallet (mainnet)
cardano-prism mnemonic address

# Show address for a specific network
cardano-prism mnemonic address --network preprod

Key Management (`key`)

Keys are derived from the SSI wallet mnemonic using the Identus HD key derivation (based on CIP-1852).

The derivation path follows the pattern: m/29'/29'/<DID-index>'/<key-usage>'/<key-index>'

Key usages: Master, Issuing, Keyagreement, Authentication, Revocation, Capabilityinvocation, Capabilitydelegation, Vdr

Derive a Secp256k1 key

The Master and VDR keys MUST be of type secp256k1.

# cardano-prism key secp256k1 [--label <name>] <DID-index> <keyUsage> <key-index>
cardano-prism key sepc256k1 0 Master 0 # Saves key as "key-0-Master-0"

cardano-prism key sepc256k1 --label my-master-key 0 Master 0

Derive an Ed25519 key

# cardano-prism key Ed25519 [--label <name>] <DID-index> <keyUsage> <key-index>
cardano-prism key Ed25519 0 Issuing 0 # Saves key as "key-0-Issuing-0"

cardano-prism key Ed25519 0 Authentication 0

Derive an X25519 key

# cardano-prism key X25519 [--label <name>] <DID-index> <keyUsage> <key-index>
cardano-prism key X25519 0 Keyagreement 0 # Saves key as "key-0-KeyAgreement-0"

Generate a random Ed25519 key

Generates a random Ed25519 private key (not derived from a mnemonic) and saves it to the config.

# cardano-prism key random-Ed25519 --label <name>
cardano-prism key random-Ed25519 --label my-ed25519-key

Generate a random X25519 key

Generates a random X25519 private key (not derived from a mnemonic) and saves it to the config.

# cardano-prism key random-X25519 --label <name>
cardano-prism key random-X25519 --label my-x25519-key

Derive a key from a custom derivation path

# cardano-prism key derivation-path [--mnemonic <phrase>] [--derivation-path <path>] [--label <name>]
cardano-prism key derivation-path --derivation-path "m/29'/29'/0'/1'/0'" --label my-key

DID Management (`did`)

Create a deterministic DID (recommended)

Creates a PRISM DID following the deterministic PRISM DID generation proposal. Requires at least the Master key. Outputs the DID and the encoded PRISM events to submit to the blockchain.

# cardano-prism did create-deterministic [-S <id>=<endpoint>] <keyID>...
cardano-prism did create-deterministic key-0-Master-0

# With a DIDComm service endpoint
cardano-prism did create-deterministic -S e1=https://did.example.com key-0-Master-0

# With multiple keys and a service
cardano-prism did create-deterministic -S e1=https://did.example.com key-0-Master-0 key-0-Issuing-0

Example output:

SSI: did:prism:d2ffaf9f8d7fa754d0e008649d29f3de8ac63699b263d4080b3450ac3c0ebdec
create SignedPrismEvent:
0a0e6b65792d302d4d61737465722d30...
update SignedPrismEvent:
0a0e6b65792d302d4d61737465722d30...

The output events are hex-encoded protobuf payloads that must be submitted to the Cardano blockchain (see Submit Events).

Create a DID for VDR

Creates a DID with a master key and optional VDR key.

cardano-prism did create-for-vdr --master key-0-Master-0 --vdr key-0-Vdr-0

Resolve a DID

# Resolve from the PRISM VDR (GitHub-hosted)
cardano-prism did resolve-prism did:prism:<hash>
cardano-prism did resolve-prism --network preprod did:prism:<hash>

# Resolve from a custom endpoint
cardano-prism did resolve did:prism:<hash> https://my-resolver.example.com/

# Resolve using the Universal Resolver (https://dev.uniresolver.io/)
cardano-prism did resolve-universal did:prism:<hash>
cardano-prism did resolve-universal --endpoint https://my-uniresolver.example.com/ did:prism:<hash>

# Resolve using NeoPrism
cardano-prism did resolve-neoprism did:prism:<hash>
cardano-prism did resolve-neoprism --network preprod did:prism:<hash>

Cardano / Blockfrost (`cardano`)

Commands for interacting with the Cardano blockchain via the Blockfrost API.

Save a Blockfrost API token

# cardano-prism cardano blockfrost-token [-s] <network> <token>
cardano-prism cardano blockfrost-token -s preprod preprod<YOUR_API_TOKEN>
cardano-prism cardano blockfrost-token -s mainnet mainnet<YOUR_API_TOKEN>

Networks: mainnet, preprod, preview

Check wallet balance

# Check ADA balance of the stored Cardano wallet
cardano-prism cardano address --network preprod

Submit Events

Submit hex-encoded PRISM signed events to the Cardano blockchain. This path requires:

a Cardano payment wallet stored in the config (covers transaction fees), and
a Blockfrost API token saved for the target network.

# cardano-prism cardano submit --network <network> <event-hex>...
cardano-prism cardano submit --network preprod <create-event-hex> <update-event-hex>

On success, prints the transaction hash and links to Cardanoscan and NeoPrism.

If you'd rather not store a wallet mnemonic or Blockfrost token, see Submit Events via a browser wallet (CIP-30) below.

Website (`website`)

Local-website driven flows. Spawns a one-shot HTTP server on localhost, opens a browser page, and exits as soon as the page reports back. Decoupled from Blockfrost — useful when you'd rather sign and submit through your existing browser wallet than store a mnemonic and a Blockfrost token in the config.

Submit Events via a browser wallet (CIP-30)

Submit PRISM events through a CIP-30 browser wallet (Lace, Eternl, Nami, Yoroi, …). The browser builds the Cardano transaction, the wallet signs it, and the wallet's own backend submits it. No Blockfrost token is needed and no Cardano wallet mnemonic is read from the config — the only thing the CLI knows is the events you pass in.

# cardano-prism website submit-cip30 [--port <integer>] <event-hex>...
cardano-prism website submit-cip30 <create-event-hex> <update-event-hex>

# Custom port (default is 8088)
cardano-prism website submit-cip30 --port 9090 <create-event-hex>

Flow:

The CLI starts a local HTTP server and prints Open http://localhost:8088 in your browser to submit.
Open that URL. The page lists the DID(s) that will be created and shows a wallet picker.
Click Submit. The wallet asks you to approve the transaction.
As soon as the wallet returns a transaction hash, the CLI prints the hash + a CardanoScan link and exits.

The network the transaction lands on is whichever network your wallet is currently set to (mainnet / preprod / preview).

Indexer (`indexer`)

The indexer continuously fetches PRISM events from the Cardano blockchain and indexes them locally, enabling offline DID resolution.

File system mode (in-memory indexer)

Reads and writes state to the local file system. Suitable for lightweight deployments and CI/CD workflows.

# cardano-prism indexer in-memory [--token <BLOCKFROST_APIKEY>] <work-directory>
cardano-prism indexer in-memory --token preprod<YOUR_API_TOKEN> ./prism-vdr/preprod

See a real-world example: indexer.yml

MongoDB mode (database mode)

Stores state in a MongoDB database. Suitable for production deployments.

# cardano-prism indexer mongodb --token <BLOCKFROST_APIKEY> <mongodb-connection>
cardano-prism indexer mongodb \
  --token preprod<YOUR_API_TOKEN> \
  'mongodb+srv://user:password@cluster0.example.mongodb.net/indexer'

VDR — Verifiable Data Registry (`vdr`)

VDR commands manage anchored data entries on the Cardano blockchain, linked to a PRISM DID via a VDR key.

All VDR commands require:

--network — target Cardano network (mainnet, preprod, preview)
--work-directory — local indexer directory
--owner — PRISM DID that owns the entry
--vdr — label of the VDR private key (default: vdr)

Create a bytes entry

cardano-prism vdr create-bytes \
  --network preprod \
  --work-directory ./prism-vdr/preprod \
  --owner did:prism:<hash> \
  --vdr key-0-Vdr-0 \
  <hex-encoded-bytes>

Create an IPFS entry

cardano-prism vdr create-ipfs \
  --network preprod \
  --work-directory ./prism-vdr/preprod \
  --owner did:prism:<hash> \
  <IPFS-CID>

Update a bytes entry

cardano-prism vdr update-bytes \
  --network preprod \
  --work-directory ./prism-vdr/preprod \
  <vdr-entry-ref> \
  <new-hex-encoded-bytes>

Update an IPFS entry

cardano-prism vdr update-ipfs \
  --network preprod \
  --work-directory ./prism-vdr/preprod \
  <vdr-entry-ref> \
  <new-IPFS-CID>

Deactivate an entry

cardano-prism vdr deactivate \
  --network preprod \
  --work-directory ./prism-vdr/preprod \
  <vdr-entry-ref>

Fetch an entry

cardano-prism vdr fetch \
  --network preprod \
  --work-directory ./prism-vdr/preprod \
  <vdr-entry-ref>

Generate proof for an entry

cardano-prism vdr proof \
  --network preprod \
  --work-directory ./prism-vdr/preprod \
  <vdr-entry-ref>

End-to-End Example: Create and Publish a DID

This walkthrough creates a PRISM DID with one master key, one issuing key, and a DIDComm service endpoint, then anchors it on Cardano preprod.

1. Set up keys and a DID

# Create the config file (one-time)
cardano-prism config-file --create

# Generate and save an SSI wallet mnemonic
cardano-prism mnemonic new -s

# Master key — must be secp256k1
cardano-prism key sepc256k1 0 Master 0
# => saves as "key-0-Master-0"

# Issuing key — Ed25519
cardano-prism key Ed25519 0 Issuing 0
# => saves as "key-0-Issuing-0"

# Build the deterministic DID (with a DIDComm service endpoint)
cardano-prism did create-deterministic \
  -S e1=https://did.fabiopinheiro.com/ \
  key-0-Master-0 key-0-Issuing-0

Output:

SSI: did:prism:aab8d14fb60c035ec589195b407978d6ec1316e183ba6fbb920a0a7ff0326422
create SignedPrismEvent:
0a066d617374657212473045022100b32b3dfc1fb47dc102038c1cbc1571b955f0ee7bab27e8b9626f8da62c50a4d6022050dfa98afdfe7503dbe58ed9ae20addb6d52a182521cd67e9d4bb6b79629b0f41a400a3e0a3c123a0a066d617374657210014a2e0a09736563703235366b31122103ebe0934672da51ca01da94d278376a204e0e73a8d235c290bc2d5f1a629f8aec
update SignedPrismEvent:
0a066d6173746572124730450221008c036641c84c182aba386e004803684b069004e192b860542a23f16de023351102201e66c385924c88ac26aeaea76140df6fcb3d8de926091b72b983bf864305a8801afa0112f7010a20aab8d14fb60c035ec589195b407978d6ec1316e183ba6fbb920a0a7ff03264221240616162386431346662363063303335656335383931393562343037393738643665633133313665313833626136666262393230613061376666303332363432321a4b1a490a470a09656e64706f696e74311210444944436f6d6d4d6573736167696e671a287b22757269223a2268747470733a2f2f6469642e666162696f70696e686569726f2e636f6d2f227d1a440a420a400a0f6b65792d302d49737375696e672d3010024a2b0a0745643235353139122018a25f3a42089ae9d41f2ea40549bf045c12021923a4b760487d0237e0e36e40

The DID is now defined locally; the next step anchors the create + update events on Cardano. Pick one of the two paths below.

2a. Submit via Blockfrost (CLI-only)

Requires a Cardano payment wallet in the config and a Blockfrost API token.

# One-time setup: payment wallet + Blockfrost token
cardano-prism mnemonic new -s --wallet-type ada
cardano-prism cardano blockfrost-token -s preprod preprod<YOUR_TOKEN>

# Submit the two events from step 1
cardano-prism cardano submit --network preprod \
  <create-event-hex> \
  <update-event-hex>

2b. Submit via a browser wallet (CIP-30)

No Cardano wallet mnemonic, no Blockfrost token. The CLI opens a local web page; your existing browser wallet (Lace, Eternl, Nami, Yoroi, …) does the signing and submission.

cardano-prism website submit-cip30 \
  <create-event-hex> \
  <update-event-hex>

Open http://localhost:8088 in the browser, pick your wallet, approve the transaction. Make sure the wallet is on the network you intend to publish to.

3. Verify

Either path prints the transaction hash and explorer URLs. Example output:

https://preprod.cardanoscan.io/transaction/f404044f00cae9146d3e9f451e7e26eb2aba80ce6f0fe9a50c57b48d0e0ad9fa?tab=metadata
https://neoprism-preprod.patlo.dev/resolver?did=did:prism:aab8d14fb60c035ec589195b407978d6ec1316e183ba6fbb920a0a7ff0326422

After the transaction is confirmed (~1 block), resolve the DID:

cardano-prism did resolve-neoprism --network preprod \
  did:prism:aab8d14fb60c035ec589195b407978d6ec1316e183ba6fbb920a0a7ff0326422