A command-line client for managing Decentralized Identifiers.
The current client supports the creation of Testnet DIDs on the Veres One ledger as well as the retrieval of those DIDs from the Testnet. You can try the tool out by doing the following commands on a system that has node.js installed:
npm install did-cli
cd node_modules/did-cli
./did generate -r
To retrieve the freshly generated DID:
./did info <DID>
By default, keys and DID Documents will be stored in ~/.dids/<method>/<mode>/,
see Setting Up Storage for more details.
- Linux or Mac OS X
- Node.js >= 8.6.x
- npm >= 3.x
Install in a development directory:
npm install did-cli
./node_modules/.bin/did ...
Install globally:
npm install -g did-cli
did ...
Run from npx:
npx did-cli ...
To download the source and install the client:
git clone https://github.com/digitalbazaar/did-cli.git
cd did-cli
npm install
./did ...
The did command has many commands and options. Help is available with the
--help/-h command line option:
did -h
did COMMAND -h
Commands can be more verbose with one ore more --verbose/-v options, or
quieted more than the default with --quiet/-q:
did COMMAND -v ...
did COMMAND -vv ...
did COMMAND -q ...
Copies of registered DIDs, keys, and metadata are all stored in your
$HOME/.dids/ directory.
Remote commands operate on a ledger. Various ledgers may be available. They
can be selected with the --ledger/-l option which defaults to veres.
did COMMAND -l LEDGER ...
Remote ledger commands also have a "live", "test", or "dev" mode selected with
--mode/-m which defaults to test:
did COMMAND -m MODE ...
The combination of ledger and mode options will select the default hostnames to
connect to. Specific hostnames can be selected with --hostname/-H:
did COMMAND -l example -m test -H host1.example.com ...
A DID is generated locally with the generate command:
did generate
Other options:
--passphrase/-p PASSPHRASE: set a key passphrase--type/-t TYPE: set key type (ex:ed25519orrsa)--name NAME: set a private name note--description DESCRIPTION: set a private description note--register/-r: register on a ledger
By default generate will only store a DID locally. If you want to also
immediately register it to the default Veres One testnet ledger:
did generate -r
You can register local DIDs to a ledger with the register command:
did register DID
Some ledgers may require DID authorization (this topic is outside of the scope
of this tool). You can specify an authorization DID key with --auth/-a:
did register DID -a AUTHDID
Some ledgers may require proof-of-work to accept a DID request. Others may
allow "accelerators" to be used. These are specified with --accelerator/-A
and require an authorization DID:
did register DID -a AUTHDID -A ACCELERATORHOSTNAME
Pending (created but not registered) and registered DIDs can be listed with the
list command:
did list
Information on a DID can be found with the info command:
did info DID
It can be useful to store private local notes about DIDs which are
otherwise somewhat opaque identifiers. The notes command adds this ability
with simple key/value pairs.
All notes for all DIDs can be shown with:
did notes
Notes for specific DID can be shown:
did notes DID
Various notes operations are available:
--clear: remove all notes--add KEY VALUE: append VALUE to an array for KEY--remove: remove VALUE from array for KEY--get KEY: get KEY value--set KEY VALUE: set single VALUE for KEY--delete: delete all values for KEY--find KEY VALUE: find DIDs with VALUE set for KEY
If a DID is not specified the commands will operate on all DIDs. As this can
be dangerous, any operation with operates on many DIDs must use the --all
option.
did notes --delete old-property --all
You can choose any KEY values you wish, although simple strings will be easiest
to use. The generate and register commands have an "auto" feature to write
some notes. The "name" note is useful to assign simple names to DIDs. The
"ledger" note is useful to keep track of where DIDs have been sent.
$ did notes did:example:test:1234 --set name shortname
$ did notes did:example:test:1234 --get name
did:example:test:1234 name
$ did notes --find name shortname
did:example:test:1234
$ did notes did:example:test:A --add url https://example.com/
$ did notes did:example:test:B --add url https://example.com/
$ did notes did:example:test:C --add url https://example.org/
$ did notes --find url https://example.com/
did:example:test:A
did:example:test:B
$ did notes --get url
did:example:test:A url https://example.com/
did:example:test:B url https://example.com/
did:example:test:C url https://example.org/
The notes data is stored in the config.jsonld file in your local DID dir. It
can be freely edited as needed. Warning: This file is not currently safe
to write to concurrently!
A DID has a number of application suite parameters that can store keys. Keys
are managed with the with the authn-* commands. To inspect the keys use
info:
# show the DID JSON including keys
did info did:example:1234
# show more readable summary
did info did:example:1234 -f human
# show summary with public keys
did info did:example:1234 -f human --public-key
# show local summary with private keys
did info did:example:1234 -f human -L local --private-key
Key material can be added with ed25519-key-add. A unique cryptonym key id
will be generated. Note that the updates will be automatically
registered on the ledger unless --no-register is provided:
# add a public and private key
did ed25519-key-add did:example:1234 -p authentication --pub PUBLICKEYINFO \
--pvt PRIVATEKEYINFO
Basic generate and check DID is on ledger:
# generate and register on ledger
did generate -r # generate and register on ledger
# wait a few moments
# ...
did info DID
More extreme checking if ledger has details of multiple hosts. As of this
writing, Veres One has multiple testnet hosts hardcoded, but you can specify
your own with multiple -H options:
# generate and register on ledger
did generate -r # generate and register to ledger
did info DID
Depending on the ledger, you may be able to see consensus happening after a generate:
# start a retry loop, see info --help for other options
did info DID -f found -L all --retry
Use an accelerator to register a DID faster. This assumes you have registered
did:ex:my-did at the accelerator:
did generate -r -a did:ex:test:my-did -A accelerator.example.com
Split creation and later register to multiple ledgers (because you are an expert and have solid reasons for doing this):
# generate with a private name, do not register
did generate --name my-did
# ... time passes
# ...
# ... grrr, I forgot the long DID name
did list
... many many DIDs ...
# hmm... lots of random DID names, which one is it?
did notes --get name
... many other DIDs with names ...
did:example:test:1234 name my-did
# ah! there it is!
# register on a ledger
did register did:example:test:1234
# i'd like to use on other ledgers too
did register -H ledger2.example.com did:example:test:1234
Show which DIDs have a note about being on a ledger:
did notes --get ledger
Tips and tricks:
# reload DIDs on a dev ledger after a wipe
did notes --find ledger veres:dev | xargs -I {} did register -m dev {}
# alternative
for d in `did notes --find ledger veres:dev`; do did register -m dev $did; done
There are plans to support the following other commands and features:
- Rotating authentication credentials
- Adding and removing authorization capability descriptions
- Adding and removing service descriptions
- Checking the validity of a DID (deep blockchain check)
Bugs, suggestions, requests, and code issues:
Commercial support is available upon request from Digital Bazaar:
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent