@did-btcr2/cli 0.13.0 → 0.15.0

package/dist/types/src/types.d.ts

@@ -2,9 +2,18 @@ import type { DidUpdateResult } from '@did-btcr2/api';
 import type { PatchOperation } from '@did-btcr2/common';
 import type { Btcr2DidDocument, ResolutionOptions } from '@did-btcr2/method';
 import type { DidResolutionResult } from '@web5/dids';
+import type { DoctorReport, EffectiveConfig } from './config.js';
+import type { ConfigIssue } from './config-schema.js';
 export type NetworkOption = 'bitcoin' | 'testnet3' | 'testnet4' | 'signet' | 'mutinynet' | 'regtest';
 export type OutputFormat = 'json' | 'text';
 export declare const SUPPORTED_NETWORKS: NetworkOption[];
+/**
+ * Normalizes a blank value (empty or whitespace-only) to `undefined`, so a
+ * blank at any precedence layer defers to the next layer instead of masking it.
+ * A non-blank value is returned unchanged. This mirrors the `|| undefined`
+ * treatment the environment layer already applies in `readEnvOverrides`.
+ */
+export declare function blankToUndef(value: string | undefined): string | undefined;
 export interface ResolveCommandOptions {
     identifier: string;
     options?: ResolutionOptions;
@@ -100,6 +109,24 @@ export type CommandResult = {
 } | {
     action: 'config-list';
     data: unknown;
+} | {
+    action: 'config-validate';
+    data: {
+        ok: boolean;
+        issues: ConfigIssue[];
+    };
+} | {
+    action: 'config-effective';
+    data: EffectiveConfig;
+} | {
+    action: 'config-path';
+    data: {
+        config: string;
+        keystore: string;
+    };
+} | {
+    action: 'config-doctor';
+    data: DoctorReport;
 } | {
     action: 'profile-add';
     data: {
@@ -130,6 +157,12 @@ export interface GlobalOptions {
     btcRpcUser?: string;
     btcRpcPass?: string;
     casGateway?: string;
+    casRpcUrl?: string;
+    btcTimeout?: string;
+    casTimeout?: string;
+    btcRestHeader?: string[];
+    btcRpcWallet?: string;
+    btcRpcHeader?: string[];
     keystore?: string;
     passphraseFile?: string;
     signingKey?: string;

package/dist/types/src/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@did-btcr2/cli",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "type": "module",
   "description": "CLI for interacting with did-btcr2-js, the JavaScript/TypeScript reference implementation of the did:btcr2 method. Exposes various parts of multiple packages in the did-btcr2-js monorepo.",
   "main": "./dist/cjs/index.js",
@@ -61,11 +61,11 @@
     "@scure/base": "^1.2.6",
     "@web5/dids": "^1.2.0",
     "commander": "^13.1.0",
-    "@did-btcr2/api": "^0.15.0",
+    "@did-btcr2/keypair": "^0.13.1",
+    "@did-btcr2/api": "^0.16.1",
     "@did-btcr2/key-manager": "^0.7.0",
     "@did-btcr2/common": "^9.1.0",
-    "@did-btcr2/keypair": "^0.13.1",
-    "@did-btcr2/method": "^0.54.0"
+    "@did-btcr2/method": "^0.54.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.21.0",

package/src/cli.ts

@@ -10,7 +10,7 @@ import {
   registerResolveCommand,
   registerUpdateCommand,
 } from './commands/index.js';
-import { defaultApiFactory, keystoreApiFactory, type ApiFactory } from './config.js';
+import { defaultApiFactory, keystoreApiFactory, resolveOutputFormat, type ApiFactory } from './config.js';
 import type { GlobalOptions } from './types.js';
 import { VERSION } from './version.js';
 
@@ -41,7 +41,7 @@ export class DidBtcr2Cli {
     this.program = new Command('btcr2')
       .version(`btcr2 ${VERSION}`, '-v, --version', 'Output the current version')
       .description('CLI tool for the did:btcr2 method')
-      .option('-o, --output <format>', 'Output format <json|text>', 'text')
+      .option('-o, --output <format>', 'Output format <json|text> (default: config defaults.output, else text)')
       .option('--verbose', 'Verbose output', false)
       .option('--quiet', 'Suppress non-essential output', false)
       .option('-c, --config <path>', 'Path to config file (default: $XDG_CONFIG_HOME/btcr2/config.json)')
@@ -50,13 +50,29 @@ export class DidBtcr2Cli {
       .option('--btc-rpc-url <url>', 'Override Bitcoin Core RPC endpoint')
       .option('--btc-rpc-user <user>', 'Bitcoin Core RPC username')
       .option('--btc-rpc-pass <pass>', 'Bitcoin Core RPC password')
-      .option('--cas-gateway <url>', 'IPFS HTTP gateway for CAS reads')
+      .option('--cas-gateway <url>', 'IPFS HTTP gateway for CAS reads (read-only)')
+      .option('--cas-rpc-url <url>', 'IPFS HTTP RPC endpoint for a writable CAS (reads + writes; enables --publish-to-cas)')
+      .option('--btc-timeout <ms>', 'Bitcoin REST/RPC request timeout in milliseconds (default: unbounded)')
+      .option('--cas-timeout <ms>', 'CAS request timeout in milliseconds (default: 30000; 0 disables)')
+      .option('--btc-rest-header <header>', 'Extra Bitcoin REST header "Key: Value" (repeatable)', collectHeader, [])
+      .option('--btc-rpc-wallet <name>', 'Bitcoin Core wallet name for wallet-scoped RPCs')
+      .option('--btc-rpc-header <header>', 'Extra Bitcoin Core RPC header "Key: Value" (repeatable)', collectHeader, [])
       .option('--keystore <path>', 'Path to the keystore file (default: $XDG_DATA_HOME/btcr2/keystore.json)')
       .option('--passphrase-file <path>', 'Read the keystore passphrase from a file (unattended use)')
       .option('--signing-key <ref>', 'Key for create/update/deactivate signing: a URN, fingerprint prefix, or name');
 
     const globals = (): GlobalOptions => this.program.opts() as GlobalOptions;
 
+    // Resolve the effective output format (flag -> BTCR2_OUTPUT -> config
+    // defaults.output -> 'text') before any command action runs, so a configured
+    // default is honored while an explicit flag still wins. The commander option
+    // carries no hard default (which would mask defaults.output); the resolved
+    // value is written back so every command reads it through globals().output.
+    this.program.hook('preAction', () => {
+      const opts = this.program.opts() as GlobalOptions;
+      opts.output = resolveOutputFormat({ output: opts.output, config: opts.config });
+    });
+
     registerCreateCommand(this.program, factory, keystoreFactory, globals);
     registerResolveCommand(this.program, factory, globals);
     registerUpdateCommand(this.program, keystoreFactory, globals);
@@ -83,6 +99,14 @@ export class DidBtcr2Cli {
   }
 }
 
+/**
+ * Commander collector for a repeatable header option: accumulates each
+ * `Key: Value` occurrence into an array, preserving order.
+ */
+function collectHeader(value: string, previous: string[]): string[] {
+  return [ ...previous, value ];
+}
+
 /**
  * Normalizes argv to ensure it has at least two elements.
  * @param {string[]} argv - The original argv array.

package/src/commands/config.ts

@@ -5,15 +5,21 @@ import {
   CONFIG_SCHEMA_VERSION,
   defaultConfigPath,
   getConfigPath,
+  parseConfigFileRaw,
   readConfigFile,
+  resolveDefaultNetwork,
+  resolveEffectiveConfig,
+  runDoctor,
   setConfigPath,
   unsetConfigPath,
   writeConfigFile,
 } from '../config.js';
+import { findConfigIssues, validateConfigSet } from '../config-schema.js';
 import { CLIError } from '../error.js';
 import { ensureDir, writeFileAtomic } from '../keystore/atomic.js';
-import { formatResult } from '../output.js';
-import type { CommandResult, GlobalOptions } from '../types.js';
+import { defaultKeystorePath } from '../keystore/paths.js';
+import { formatResult, REDACTED, redactSecrets, scrubUrlUserinfo } from '../output.js';
+import type { CommandResult, GlobalOptions, NetworkOption } from '../types.js';
 import { SUPPORTED_NETWORKS } from '../types.js';
 
 /** Registers the `config` command group for reading and writing CLI configuration. */
@@ -44,16 +50,26 @@ export function registerConfigCommand(program: Command, globals: () => GlobalOpt
   config
     .command('get [path]')
     .description('Print a value at a dotted path, or the whole config.')
-    .action((dotted?: string) => {
+    .option('--show-secrets', 'Reveal secret values (RPC password, etc.) instead of redacting them.', false)
+    .action((dotted: string | undefined, opts: { showSecrets?: boolean }) => {
       const file = (readConfigFile(path()) ?? {}) as Record<string, unknown>;
-      print({ action: 'config-get', data: (dotted ? getConfigPath(file, dotted) : file) ?? null });
+      const raw = (dotted ? getConfigPath(file, dotted) : file) ?? null;
+      const leaf = dotted ? dotted.split('.').pop() : undefined;
+      print({ action: 'config-get', data: opts.showSecrets ? raw : redactSecrets(raw, leaf) });
     });
 
   config
     .command('set <path> <value>')
     .description('Set a value at a dotted path. The value is parsed as JSON when valid, else stored as a string.')
     .action((dotted: string, value: string) => {
-      writeConfigFile(path(), raw => setConfigPath(raw, dotted, parseValue(value)));
+      const parsed = parseValue(dotted, value);
+      // Reject an invalid enum value for a known key up-front; warn (but still
+      // write) an unknown path so forward-compatible and third-party keys work.
+      const { unknownPath } = validateConfigSet(dotted, parsed);
+      if (unknownPath && !globals().quiet) {
+        console.error(`Warning: "${dotted}" is not a known config path; writing it anyway.`);
+      }
+      writeConfigFile(path(), raw => setConfigPath(raw, dotted, parsed));
       print({ action: 'config-set', data: { path: dotted } });
     });
 
@@ -69,16 +85,127 @@ export function registerConfigCommand(program: Command, globals: () => GlobalOpt
     .command('list')
     .alias('ls')
     .description('Print the entire config file.')
+    .option('--show-secrets', 'Reveal secret values (RPC password, etc.) instead of redacting them.', false)
+    .action((opts: { showSecrets?: boolean }) => {
+      const file = readConfigFile(path()) ?? {};
+      print({ action: 'config-list', data: opts.showSecrets ? file : redactSecrets(file) });
+    });
+
+  config
+    .command('validate')
+    .description('Check the config for unknown keys, invalid enum values, and an unsupported schema version.')
+    .action(() => {
+      // Read raw (bypassing the schema-version ceiling that readConfigFile
+      // enforces) so a newer-than-supported version is reported as a finding
+      // rather than aborting the very command meant to diagnose it.
+      const file = parseConfigFileRaw(path()) ?? {};
+      const issues = findConfigIssues(file, CONFIG_SCHEMA_VERSION);
+      if (issues.length > 0) process.exitCode ??= 1;
+      print({ action: 'config-validate', data: { ok: issues.length === 0, issues } });
+    });
+
+  config
+    .command('effective')
+    .description('Print the resolved connection config with per-value provenance (flag|env|file|default).')
+    .option('-n, --network <network>', 'Network to resolve for (default: config default network)')
+    .option('--show-secrets', 'Reveal secret values (RPC password) instead of redacting them.', false)
+    .action((opts: { network?: string; showSecrets?: boolean }) => {
+      const network = resolveIntrospectionNetwork(opts.network, globals());
+      const data = resolveEffectiveConfig(network, globals());
+      // Redact the resolved RPC password and any password embedded in an endpoint
+      // URL by default; provenance still shows where each value came from.
+      // --show-secrets reveals them for deliberate debugging.
+      if (!opts.showSecrets) {
+        if (data.btc.rpcPass.value !== undefined) {
+          data.btc.rpcPass = { ...data.btc.rpcPass, value: REDACTED };
+        }
+        for (const entry of [ data.btc.rest, data.btc.rpcUrl, data.cas.gateway, data.cas.rpcUrl ]) {
+          if (typeof entry.value === 'string') entry.value = scrubUrlUserinfo(entry.value);
+        }
+      }
+      print({ action: 'config-effective', data });
+    });
+
+  config
+    .command('path')
+    .description('Print the resolved config-file and keystore paths.')
     .action(() => {
-      print({ action: 'config-list', data: readConfigFile(path()) ?? {} });
+      const data = {
+        config   : globals().config ?? defaultConfigPath(),
+        keystore : globals().keystore ?? defaultKeystorePath(),
+      };
+      print({ action: 'config-path', data });
+    });
+
+  config
+    .command('doctor')
+    .description('Probe reachability of the resolved endpoints (read-only; touches the network).')
+    .option('-n, --network <network>', 'Network to resolve for (default: config default network)')
+    .action(async (opts: { network?: string }) => {
+      const network = resolveIntrospectionNetwork(opts.network, globals());
+      const report = await runDoctor(network, globals());
+      if (report.checks.some(check => !check.ok)) process.exitCode ??= 1;
+      print({ action: 'config-doctor', data: report });
     });
 }
 
-/** Parses a value as JSON when valid, otherwise treats it as a plain string. */
-function parseValue(value: string): unknown {
+/**
+ * Resolves the network an introspection command (`effective`/`doctor`) operates
+ * on: an explicit `--network`, validated, else the config's default network.
+ */
+function resolveIntrospectionNetwork(explicit: string | undefined, globals: GlobalOptions): NetworkOption {
+  if (explicit) {
+    if (!SUPPORTED_NETWORKS.includes(explicit as NetworkOption)) {
+      throw new CLIError(
+        `Invalid network "${explicit}". Must be one of ${SUPPORTED_NETWORKS.join(', ')}.`,
+        'INVALID_ARGUMENT_ERROR',
+        { network: explicit },
+      );
+    }
+    return explicit as NetworkOption;
+  }
+  return resolveDefaultNetwork(globals);
+}
+
+/**
+ * Parses a `config set` value. Known scalar endpoint, credential, and defaults
+ * paths are stored as raw strings so a bare `8080` is not coerced to the number
+ * `8080` (which would flow into a host field as a non-string). Every other path
+ * is parsed as JSON when valid, else stored as a plain string, so structured
+ * values (objects, arrays, booleans, and genuinely numeric fields) still work.
+ */
+function parseValue(dotted: string, value: string): unknown {
+  if (isStringScalarPath(dotted)) return value;
   try {
     return JSON.parse(value);
   } catch {
     return value;
   }
 }
+
+/**
+ * Whether a dotted config path addresses a leaf that must be stored as a string
+ * (an endpoint URL, a credential, a network/profile/output name), so JSON
+ * coercion never turns it into a non-string.
+ */
+function isStringScalarPath(dotted: string): boolean {
+  const segments = dotted.split('.');
+
+  if (segments.length === 2 && segments[0] === 'defaults') {
+    return [ 'profile', 'network', 'output' ].includes(segments[1]);
+  }
+
+  if (segments.length === 3 && segments[0] === 'profiles' && segments[2] === 'network') {
+    return true;
+  }
+
+  if (segments.length === 4 && segments[0] === 'profiles') {
+    const group = segments[2];
+    const leaf = segments[3];
+    if (group === 'btc') return [ 'rest', 'rpcUrl', 'rpcUser', 'rpcPass', 'changeAddress', 'wallet' ].includes(leaf);
+    if (group === 'cas') return [ 'gateway', 'rpcUrl' ].includes(leaf);
+    if (group === 'identity') return [ 'keystore', 'default' ].includes(leaf);
+  }
+
+  return false;
+}

package/src/commands/create.ts

@@ -1,7 +1,7 @@
 import { bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
 import type { Command } from 'commander';
 import type { ApiFactory, ConnectionOverrides } from '../config.js';
-import { resolveDefaultNetwork } from '../config.js';
+import { profileNetworkMismatch, resolveDefaultNetwork } from '../config.js';
 import { CLIError } from '../error.js';
 import { resolveKeyRef } from '../keystore/resolve-key-ref.js';
 import { formatResult } from '../output.js';
@@ -63,6 +63,18 @@ export function registerCreateCommand(
       const network = resolveNetwork(options.network, overrides);
       const signingKey = g.signingKey;
 
+      // Warn (never block) when the network being encoded disagrees with the
+      // active profile's declared network, so a `production` profile holding
+      // mainnet endpoints cannot silently mint a regtest DID.
+      const mismatch = profileNetworkMismatch(network, overrides);
+      if (mismatch && !g.quiet) {
+        process.stderr.write(
+          `Warning: creating a "${network}" identifier while the active profile `
+          + `"${mismatch.profile}" declares network "${mismatch.declared}". The `
+          + 'identifier\'s network and the profile\'s endpoints may not match.\n'
+        );
+      }
+
       /** Prints the result, plus a stderr provenance line in text mode. */
       const print = (result: CommandResult, note?: string): void => {
         console.log(formatResult(result, g));

package/src/commands/deactivate.ts

@@ -1,6 +1,7 @@
+import type { PublishToCasMode } from '@did-btcr2/api';
 import { KeyManagerSigner } from '@did-btcr2/key-manager';
 import type { Command } from 'commander';
-import { deriveNetwork, type ApiFactory } from '../config.js';
+import { deriveNetwork, resolveBroadcastOptions, resolveSigningKeyRef, type ApiFactory } from '../config.js';
 import { CLIError } from '../error.js';
 import { resolveKeyRef } from '../keystore/resolve-key-ref.js';
 import { formatResult } from '../output.js';
@@ -36,11 +37,31 @@ export function registerDeactivateCommand(
       'Beacon ID as a JSON string',
       parseJsonArg('--beacon-id'),
     )
+    .option(
+      '--publish-to-cas <mode>',
+      'Publish update artifacts to a writable CAS before broadcast: auto|always|never. '
+        + 'CAS publication is optional; the default distributes the returned artifacts via sidecar.',
+      parsePublishToCasMode,
+      'never',
+    )
+    .option(
+      '--fee-rate <satsPerVByte>',
+      'Fee rate in sats/vByte for the beacon transaction (default: 5). '
+        + 'Raise it under congestion so the transaction confirms.',
+    )
+    .option(
+      '--change-address <address>',
+      'Send transaction change to this address instead of the beacon address, '
+        + 'so a DID\'s announcements are not linked on-chain (ADR 044).',
+    )
     .action(async (options: {
       sourceDocument       : unknown;
       sourceVersionId      : string;
       verificationMethodId : string;
       beaconId             : unknown;
+      publishToCas         : PublishToCasMode;
+      feeRate?             : string;
+      changeAddress?       : string;
     }) => {
       if (!/^\d+$/.test(options.sourceVersionId)) {
         throw new CLIError(
@@ -68,11 +89,21 @@ export function registerDeactivateCommand(
       // method has no separate deactivate path, so this routes through update.
       const network = deriveNetwork(did);
       const api = factory(network, globals());
-      const keyId = resolveKeyRef(api.kms.kms, globals().signingKey);
+      const keyId = resolveKeyRef(api.kms.kms, resolveSigningKeyRef(globals()));
       const signer = new KeyManagerSigner(api.kms.kms, keyId);
-      // The CLI's CAS is a read-only gateway (no writable CAS is configurable
-      // yet), so CAS publication is disabled explicitly. The returned artifacts
-      // (txid, announcement, proof) are printed for manual sidecar distribution.
+      // Resolve fee-rate/change-address through the flag -> env -> profile chain
+      // into beacon broadcast options. Undefined when neither is set, so the
+      // SDK defaults (5 sat/vB, change back to the beacon address) still apply.
+      const broadcastOptions = resolveBroadcastOptions(network, globals(), {
+        feeRate       : options.feeRate,
+        changeAddress : options.changeAddress,
+      });
+      // CAS publication is optional and never required: every beacon update can
+      // be completed and shared via sidecar alone. It is opt-in and defaults to
+      // 'never'; pass --publish-to-cas auto|always to publish the signed update
+      // (and, for CAS beacons, the announcement) to a writable CAS configured
+      // via --cas-rpc-url. The returned artifacts (txid, announcement, proof)
+      // are always printed for sidecar distribution regardless.
       const data = await api.btcr2.update({
         sourceDocument       : parsed.sourceDocument,
         patches              : parsed.patches,
@@ -80,12 +111,28 @@ export function registerDeactivateCommand(
         verificationMethodId : parsed.verificationMethodId,
         beaconId             : parsed.beaconId,
         signer,
-        publishToCas         : 'never',
+        publishToCas         : options.publishToCas,
+        ...(broadcastOptions ? { broadcastOptions } : {}),
       });
       console.log(formatResult({ action: 'deactivate', data }, globals()));
     });
 }
 
+/**
+ * Commander argParser for `--publish-to-cas`. Validates the value is one of the
+ * three {@link PublishToCasMode} policies, erroring at parse time otherwise.
+ */
+function parsePublishToCasMode(value: string): PublishToCasMode {
+  if (value !== 'auto' && value !== 'always' && value !== 'never') {
+    throw new CLIError(
+      '--publish-to-cas must be one of "auto", "always", or "never".',
+      'INVALID_ARGUMENT_ERROR',
+      { value },
+    );
+  }
+  return value;
+}
+
 /**
  * Returns a commander argParser that validates JSON.
  * Errors at parse time with a clear flag reference.

package/src/commands/profile.ts

@@ -1,7 +1,7 @@
 import type { Command } from 'commander';
 import { defaultConfigPath, readConfigFile, writeConfigFile } from '../config.js';
 import { CLIError } from '../error.js';
-import { formatResult } from '../output.js';
+import { formatResult, redactSecrets } from '../output.js';
 import type { CommandResult, GlobalOptions } from '../types.js';
 
 /** Registers the `profile` command group for managing configuration profiles. */
@@ -37,7 +37,8 @@ export function registerProfileCommand(program: Command, globals: () => GlobalOp
   profile
     .command('show [name]')
     .description('Show a profile (defaults to the active profile).')
-    .action((name?: string) => {
+    .option('--show-secrets', 'Reveal secret values (RPC password, etc.) instead of redacting them.', false)
+    .action((name: string | undefined, opts: { showSecrets?: boolean }) => {
       const file = readConfigFile(path()) ?? {};
       const target = name ?? file.defaults?.profile;
       if (!target) {
@@ -47,7 +48,8 @@ export function registerProfileCommand(program: Command, globals: () => GlobalOp
       if (!data) {
         throw new CLIError(`Profile "${target}" not found.`, 'INVALID_ARGUMENT_ERROR', { profile: target });
       }
-      print({ action: 'profile-show', data: { profile: target, ...data } });
+      const payload = { profile: target, ...data };
+      print({ action: 'profile-show', data: opts.showSecrets ? payload : redactSecrets(payload) });
     });
 
   profile

package/src/commands/update.ts

@@ -1,6 +1,7 @@
+import type { PublishToCasMode } from '@did-btcr2/api';
 import { KeyManagerSigner } from '@did-btcr2/key-manager';
 import type { Command } from 'commander';
-import { deriveNetwork, type ApiFactory } from '../config.js';
+import { deriveNetwork, resolveBroadcastOptions, resolveSigningKeyRef, type ApiFactory } from '../config.js';
 import { CLIError } from '../error.js';
 import { resolveKeyRef } from '../keystore/resolve-key-ref.js';
 import { formatResult } from '../output.js';
@@ -37,12 +38,32 @@ export function registerUpdateCommand(
       'Beacon ID as a JSON string',
       parseJsonArg('--beacon-id'),
     )
+    .option(
+      '--publish-to-cas <mode>',
+      'Publish update artifacts to a writable CAS before broadcast: auto|always|never. '
+        + 'CAS publication is optional; the default distributes the returned artifacts via sidecar.',
+      parsePublishToCasMode,
+      'never',
+    )
+    .option(
+      '--fee-rate <satsPerVByte>',
+      'Fee rate in sats/vByte for the beacon transaction (default: 5). '
+        + 'Raise it under congestion so the transaction confirms.',
+    )
+    .option(
+      '--change-address <address>',
+      'Send transaction change to this address instead of the beacon address, '
+        + 'so a DID\'s announcements are not linked on-chain (ADR 044).',
+    )
     .action(async (options: {
       sourceDocument       : unknown;
       sourceVersionId      : string;
       patches              : unknown;
       verificationMethodId : string;
       beaconId             : unknown;
+      publishToCas         : PublishToCasMode;
+      feeRate?             : string;
+      changeAddress?       : string;
     }) => {
       if (!/^\d+$/.test(options.sourceVersionId)) {
         throw new CLIError(
@@ -68,11 +89,21 @@ export function registerUpdateCommand(
       }
       const network = deriveNetwork(did);
       const api = factory(network, globals());
-      const keyId = resolveKeyRef(api.kms.kms, globals().signingKey);
+      const keyId = resolveKeyRef(api.kms.kms, resolveSigningKeyRef(globals()));
       const signer = new KeyManagerSigner(api.kms.kms, keyId);
-      // The CLI's CAS is a read-only gateway (no writable CAS is configurable
-      // yet), so CAS publication is disabled explicitly. The returned artifacts
-      // (txid, announcement, proof) are printed for manual sidecar distribution.
+      // Resolve fee-rate/change-address through the flag -> env -> profile chain
+      // into beacon broadcast options. Undefined when neither is set, so the
+      // SDK defaults (5 sat/vB, change back to the beacon address) still apply.
+      const broadcastOptions = resolveBroadcastOptions(network, globals(), {
+        feeRate       : options.feeRate,
+        changeAddress : options.changeAddress,
+      });
+      // CAS publication is optional and never required: every beacon update can
+      // be completed and shared via sidecar alone. It is opt-in and defaults to
+      // 'never'; pass --publish-to-cas auto|always to publish the signed update
+      // (and, for CAS beacons, the announcement) to a writable CAS configured
+      // via --cas-rpc-url. The returned artifacts (txid, announcement, proof)
+      // are always printed for sidecar distribution regardless.
       const data = await api.btcr2.update({
         sourceDocument       : parsed.sourceDocument,
         patches              : parsed.patches,
@@ -80,12 +111,28 @@ export function registerUpdateCommand(
         verificationMethodId : parsed.verificationMethodId,
         beaconId             : parsed.beaconId,
         signer,
-        publishToCas         : 'never',
+        publishToCas         : options.publishToCas,
+        ...(broadcastOptions ? { broadcastOptions } : {}),
       });
       console.log(formatResult({ action: 'update', data }, globals()));
     });
 }
 
+/**
+ * Commander argParser for `--publish-to-cas`. Validates the value is one of the
+ * three {@link PublishToCasMode} policies, erroring at parse time otherwise.
+ */
+function parsePublishToCasMode(value: string): PublishToCasMode {
+  if (value !== 'auto' && value !== 'always' && value !== 'never') {
+    throw new CLIError(
+      '--publish-to-cas must be one of "auto", "always", or "never".',
+      'INVALID_ARGUMENT_ERROR',
+      { value },
+    );
+  }
+  return value;
+}
+
 /**
  * Returns a commander argParser that validates JSON.
  * Errors at parse time with a clear flag reference.