@did-btcr2/cli 0.6.0 → 0.9.0

package/README.md

@@ -10,6 +10,8 @@ This package provides the `btcr2` CLI for creating, resolving, updating, and dea
 
 Out of the box, `btcr2 resolve` works with zero configuration. The Bitcoin network is derived from the DID itself, and public endpoints (mempool.space, ipfs.io) are used as defaults. Override endpoints via CLI flags, environment variables, or a config file.
 
+> **Note:** `update` and `deactivate` are parsed and validated but will exit with an error. CLI signing is not yet implemented; use `@did-btcr2/api` with a `Signer` directly until this is wired up.
+
 ## Install
 
 ```bash
@@ -24,24 +26,77 @@ pnpm add -g @did-btcr2/cli
 
 Requires Node.js >= 22.
 
+Without installing globally, run directly via npx:
+
+```bash
+npx @did-btcr2/cli resolve -i did:btcr2:k1qq...
+```
+
+## Commands
+
+| Command | Alias | Status | Description |
+|---|---|---|---|
+| `create` | - | Working | Create an identifier and initial DID document |
+| `resolve` | `read` | Working | Resolve a DID document |
+| `update` | - | Not implemented | Update a DID document (CLI signing pending) |
+| `deactivate` | `delete` | Not implemented | Deactivate a DID permanently (CLI signing pending) |
+
+### create
+
+Required flags: `-t/--type`, `-n/--network`, `-b/--bytes`.
+
+| Flag | Description |
+|---|---|
+| `-t, --type <type>` | Identifier type: `k` (deterministic, 33-byte compressed pubkey) or `x` (external, 32-byte SHA-256 hash) |
+| `-n, --network <network>` | Bitcoin network: `bitcoin`, `testnet3`, `testnet4`, `signet`, `mutinynet`, or `regtest` |
+| `-b, --bytes <bytes>` | Genesis bytes as a hex string |
+
+### resolve (alias: read)
+
+Required flag: `-i/--identifier`. At most one of `-r` or `-p` may be given.
+
+| Flag | Description |
+|---|---|
+| `-i, --identifier <identifier>` | did:btcr2 identifier to resolve (required) |
+| `-r, --resolution-options <json>` | Resolution options as an inline JSON string |
+| `-p, --resolution-options-path <path>` | Path to a JSON file containing resolution options |
+
+### update (not yet implemented)
+
+Parses and validates flags, then exits with `NOT_IMPLEMENTED_ERROR`. Use `@did-btcr2/api` with a `Signer` directly.
+
+Required flags: `-s/--source-document`, `--source-version-id`, `-p/--patches`, `-m/--verification-method-id`, `-b/--beacon-id`.
+
+### deactivate (alias: delete, not yet implemented)
+
+Parses and validates flags, then exits with `NOT_IMPLEMENTED_ERROR`. Use `@did-btcr2/api` with a `Signer` directly.
+
+Required flags: `-s/--source-document`, `--source-version-id`, `-m/--verification-method-id`, `-b/--beacon-id`.
+
 ## Usage
 
 ### Create a DID
 
 ```bash
-# Deterministic (type=k) — from a compressed secp256k1 public key (33 bytes hex)
+# Deterministic (type=k): from a compressed secp256k1 public key (33 bytes hex)
 btcr2 create -t k -n regtest -b 02aa...
 
-# External (type=x) — from a SHA-256 hash of a genesis document (32 bytes hex)
+# External (type=x): from a SHA-256 hash of a genesis document (32 bytes hex)
 btcr2 create -t x -n bitcoin -b bb...
 ```
 
 ### Resolve a DID
 
 ```bash
-# Zero-config — network and endpoints are derived from the DID
+# Zero-config: network and endpoints are derived from the DID
 btcr2 resolve -i did:btcr2:k1qq...
 
+# Alias: read
+btcr2 read -i did:btcr2:k1qq...
+
+# With resolution options as inline JSON
+btcr2 resolve -i did:btcr2:k1qq... -r '{"versionId":"1"}'
+
 # With resolution options from a JSON file
 btcr2 resolve -i did:btcr2:k1qq... -p resolution-options.json
 
@@ -49,37 +104,31 @@ btcr2 resolve -i did:btcr2:k1qq... -p resolution-options.json
 btcr2 -o json resolve -i did:btcr2:k1qq...
 ```
 
-### Update a DID
+### Update a DID (not yet implemented)
 
-```bash
-btcr2 update \
-  -s '{"id":"did:btcr2:k1qq...","service":[...]}' \
-  --source-version-id 1 \
-  -p '[{"op":"add","path":"/service/1","value":{...}}]' \
-  -m '#initialKey' \
-  -b '#beacon-0'
+The command is registered and flags are validated, but it will always exit with an error:
+
+```
+CLI signing is not yet implemented. Use @did-btcr2/api with a Signer directly.
 ```
 
-### Deactivate a DID
+### Deactivate a DID (not yet implemented)
 
-```bash
-btcr2 deactivate \
-  -s '{"id":"did:btcr2:k1qq...","service":[...]}' \
-  --source-version-id 2 \
-  -m '#initialKey' \
-  -b '#beacon-0'
-```
+Same as `update` - flags are parsed but the command exits with `NOT_IMPLEMENTED_ERROR`.
 
 ## Configuration
 
-Override precedence (highest wins): CLI flags > environment variables > config file > network defaults.
+Override precedence, highest wins: CLI flags, then environment variables, then config file, then network defaults.
 
-### CLI flags
+### Global flags
 
 | Flag | Description |
 |---|---|
+| `-v, --version` | Output the current version |
 | `-o, --output <format>` | Output format: `json` or `text` (default: `text`) |
-| `-c, --config <path>` | Path to config file |
+| `--verbose` | Verbose output |
+| `--quiet` | Suppress non-essential output |
+| `-c, --config <path>` | Path to config file (default: `$XDG_CONFIG_HOME/btcr2/config.json`) |
 | `--profile <name>` | Config profile name (default: auto-detected from network) |
 | `--btc-rest <url>` | Override Bitcoin REST endpoint (Esplora API) |
 | `--btc-rpc-url <url>` | Override Bitcoin Core RPC endpoint |
@@ -126,8 +175,8 @@ Profiles are matched by network name when `--profile` is not specified. For exam
 
 When no overrides are configured:
 
-- **Bitcoin REST**: [mempool.space](https://mempool.space) for public networks, `localhost:3000` for regtest
-- **Bitcoin RPC**: `localhost:18443` for regtest (credentials required), not configured for public networks
+- **Bitcoin REST**: [mempool.space](https://mempool.space) for `bitcoin`, `testnet3`, `testnet4`, and `signet`; [mutinynet.com](https://mutinynet.com) for `mutinynet`; `http://localhost:3000` for `regtest`
+- **Bitcoin RPC**: `http://localhost:18443` for `regtest` (credentials required), not configured for public networks
 - **CAS**: [ipfs.io](https://ipfs.io) HTTP gateway (read-only)
 
 ## Links
@@ -136,3 +185,7 @@ When no overrides are configured:
 - [did-btcr2-js monorepo](https://github.com/dcdpr/did-btcr2-js)
 - [npm: @did-btcr2/cli](https://www.npmjs.com/package/@did-btcr2/cli)
 - [Implementation docs](https://btcr2.dev/impls/ts)
+
+## License
+
+[MPL-2.0](https://github.com/dcdpr/did-btcr2-js/blob/main/LICENSE)