Command-line interface for the did:btcr2 DID method.
Part of the did-btcr2-js monorepo.
The btcr2 command creates, resolves, updates, and deactivates did:btcr2 identifiers. It decodes and validates identifiers offline. It builds the genesis document of an external identifier. It manages the keys in an encrypted keystore. It reads and writes the CLI config and its profiles. It prints shell completion scripts.
The CLI wraps the @did-btcr2/api SDK. It parses the arguments with commander.js.
btcr2 resolve works with no config. The identifier names its network, and the CLI uses public endpoints (mempool.space, trustless-gateway.link) by default. A flag, an environment variable, or the config file can override each endpoint.
update and deactivate read the signing key from the keystore. Select a key with --signing-key <ref>, or set the active key with btcr2 key use <ref>.
The reference documentation is in docs/. It has one page per command, the global flags, the environment variables, and the precedence rules. docs/DEMO.md is a walkthrough of the full lifecycle on mutinynet.
npm install -g @did-btcr2/cli
Or with pnpm:
pnpm add -g @did-btcr2/cli
The CLI needs Node.js 24.7 or newer.
To run the CLI without a global install, use npx:
npx @did-btcr2/cli resolve -i did:btcr2:k1qq...
| Command | Alias | Description |
|---|---|---|
init |
Set up the home: create the directory, a default config file, and the keystore. | |
quickstart |
Set up the home in one command, record the network, and (optional) cache the session and probe the endpoints. | |
create |
Create an identifier and its initial DID document (offline). | |
resolve |
read |
Resolve the DID document of an identifier. |
update |
Update a DID document. The keystore signs the update. | |
deactivate |
delete |
Deactivate an identifier. This is permanent. The keystore signs the deactivation. |
identifier |
Decode and validate identifiers (offline). | |
genesis |
Build the genesis document of an external identifier (offline). | |
key |
Manage the keys in the keystore. | |
keystore |
Create, inspect, re-key, and unlock the keystore. | |
config |
Read and write the CLI config. | |
profile |
Manage the config profiles. | |
completion |
Print a shell completion script. |
Each page lists the flags, the output, the environment variables, and examples of the command. btcr2 <command> --help prints the flags of a command.
# Set up the home, the config file, and an encrypted keystore on mutinynet.
# Cache the passphrase for two hours.
btcr2 quickstart -n mutinynet --unlock --ttl 2h
# Create an identifier from the active key (offline). With no key yet, generate one.
btcr2 create -n mutinynet
# Resolve the DID document from Bitcoin.
btcr2 resolve -i did:btcr2:k1q5p...
# Update the DID document: sign a JSON Patch and broadcast a beacon signal.
btcr2 update -i did:btcr2:k1q5p... \
-p '[{"op":"add","path":"/alsoKnownAs","value":["https://example.com/demo"]}]'
An update needs a funded beacon. On a test network, create prints the beacon address and the faucet link. docs/DEMO.md has the full sequence.
The CLI keeps its state in one home directory: ~/.btcr2 on Linux and macOS, %LOCALAPPDATA%\btcr2 on Windows. The home holds config.json, keystore.json, and session.json. --home <dir> or BTCR2_HOME moves the home.
A value comes from the first of these sources: a flag, an environment variable, the active profile in the config file, the built-in default of the network. docs/config.md describes the config file and the config subcommands. docs/README.md lists the global flags, the environment variables, and the precedence of each value.