Manage Modules

WDK CLI beta.6 installs its built-in wallet modules as normal dependencies and records their exact versions in its bundled catalog. Use wdk module to inspect those pins or to manage a custom package that a custom network needs.

Use this guide to Inspect Module Status, Override A Built-In Version, Enable Or Disable A Module, Add A Custom Module, Bind The Module To A Network, Repair A Missing Module, Remove A Custom Module, Operational Checklist.

Inspect Module Status

wdk module list

The output compares each catalog or user-configured pin with the package installed under the CLI:

Use JSON output for automation:

wdk --json module list

Built-in modules ship with the CLI. Beta.6 supports version overrides and availability toggles without editing the catalog.

Override A Built-In Version

Review the replacement package and its compatibility with the CLI before changing a built-in pin. Pass an explicit version different from the current configured version to wdk module add. For example, after reviewing Spark beta.27 against the CLI's bundled beta.25:

wdk module add --name @tetherto/wdk-wallet-spark@1.0.0-beta.27

The command installs the package and records the version override; module list also shows the catalog defaultVersion. It does not update the CLI's method schemas. Test the integration with a dedicated wallet before use.

Restore the catalog version by removing that override:

wdk module remove --name @tetherto/wdk-wallet-spark

Remove reinstalls the default package; it does not uninstall the built-in module. It rejects a built-in package without a version override. Add rejects the current configured version even if the package is missing, so reinstall the exact CLI to repair a missing default package.

Enable Or Disable A Module

Disable a package with wdk module disable to prevent its networks and providers from being used without uninstalling it:

wdk module disable --name @tetherto/wdk-wallet-spark

Re-enable it before using its networks or providers:

wdk module enable --name @tetherto/wdk-wallet-spark

Each command verifies the default wallet passphrase when a wallet exists and locks a running daemon. Unlock again to load the changed registry. JSON output reports enabled, stale, and walletsLocked. Enabling an orphaned override removes it; it does not install a missing package.

Add A Custom Module

Pass a literal version that you have already reviewed:

wdk module add --name @example/wdk-wallet-example@1.2.3

If you omit the version, beta.6 resolves npm's current version and pins the resolved value once:

wdk module add --name @example/wdk-wallet-example

The command shows the package and version, verifies the current default wallet's passphrase when a wallet exists, locks a running daemon, installs the package with npm, and then stores the supplied version string under customModules in config.json.

Bind The Module To A Network

Adding a package does not create a network. Reference its unversioned package name in a custom-network spec:

{
  "network": "example-chain",
  "module": "@example/wdk-wallet-example",
  "displayName": "Example Chain",
  "testnet": true,
  "config": {
    "provider": "https://rpc.example.invalid"
  }
}

wdk network create ./example-network.json
wdk network info --network example-chain

Review the provider, chain identifier, native-token metadata, and module-specific configuration before unlocking a wallet. See Custom Networks for the complete schema.

Repair A Missing Module

A later npm operation against the global CLI installation can prune a custom package because beta.6 installs custom modules with --no-save. If wdk module list reports not installed or version mismatch, run:

wdk module add --name @example/wdk-wallet-example

For an already registered module, the command reuses its stored version string. Supplying a different version is rejected. To change versions, remove the package, review the replacement artifact, and add the new exact literal version. If the stored value is a tag or range, remove and re-add it with a literal version instead of repeatedly attempting repair.

Remove A Custom Module

First delete or migrate every custom network that references the module. module remove does not remove those network records for you.

wdk network delete --name example-chain
wdk module remove --name @example/wdk-wallet-example

Removal verifies the default wallet's passphrase when a wallet exists, locks a running daemon, deletes the custom-module registration, and uninstalls the package. It cannot remove a built-in module.

Operational Checklist

• Pin and review an exact version before installation.
• Unset WDK_PASSPHRASE and unrelated wallet-secret environment variables before add or remove; use the hidden prompt.
• Lock valuable wallets and stop unrelated same-user processes.
• Treat npm install and uninstall lifecycle output as part of the review.
• Confirm wdk module list reports the expected installed version.
• Stop if status reports a mismatch; beta.6 still loads mismatched code after warning.
• Test the module and network with a dedicated wallet and limited funds.
• Delete dependent custom networks before removing their module.

Next Steps

• Custom Networks
• Call Module Methods
• Security Model
• API Reference

Need Help?