Manage Wallets

WDK CLI stores independent named wallets and keeps only explicitly unlocked wallets in the daemon. This guide covers the complete wallet lifecycle.

Wallet names

Wallet names may contain letters, numbers, hyphens, and underscores. Other characters are rejected.

Examples in this guide use a wallet named dev:

wdk wallet list

Create a wallet

Create a 12-word wallet:

wdk wallet create --name dev

Create a 24-word wallet:

wdk wallet create --name dev --words 24

The CLI asks for a passphrase twice, writes the encrypted mnemonic to wallets/dev/seed.enc, and displays the generated phrase once. Record both the mnemonic and passphrase in separate recoverable locations before continuing.

The first wallet becomes the default automatically. You do not need to run wdk wallet default after creating the first wallet.

Import a wallet

Import an existing 12- or 24-word BIP-39 phrase:

wdk wallet import --name recovered

The CLI prompts for the phrase and then for a new local encryption passphrase. The seed-phrase input is interactive but is not masked, so import only in a private terminal.

Import creates another encrypted local copy. It does not remove or change the source wallet or any existing backup.

List wallets and sessions

Show stored wallets, the default wallet, lock status, and TTL remaining:

wdk wallet list

When a wallet is unlocked, the table reports either the approximate remaining time or unlimited for a --ttl 0 session.

In JSON mode, an unlocked entry includes ttlMs and ttlRemaining in milliseconds:

wdk --json wallet list

Select the default wallet

Commands use the default wallet when their --wallet option is omitted.

wdk wallet default --name dev

If a default wallet already exists, changing it requires that wallet's passphrase. This prevents an unconfirmed configuration change, but it does not unlock either wallet.

To target another wallet for one supported operation without changing the default, pass its command-level option:

wdk get balance --network ethereum --wallet recovered

Unlock a wallet

Unlock with the default five-minute TTL:

wdk wallet unlock --name dev

Specify an absolute TTL in minutes:

wdk wallet unlock --name dev --ttl 15

Unlock starts the daemon if needed. The CLI verifies the passphrase, then the daemon decrypts the wallet, creates its WDK instance, and starts the timer.

Control the unlock lifetime

TTL is per wallet and starts at unlock:

--ttl 0 accepts the risk of a session that remains unlocked until explicit lock, daemon shutdown, process failure, or machine restart:

wdk wallet unlock --name dev --ttl 0

Use it only for a controlled local workflow. Normal wallet operations do not refresh any TTL, so a finite session can expire during a long task.

Lock wallets

Lock one wallet:

wdk wallet lock --name dev

Lock every wallet:

wdk wallet lock --all

Locking disposes the wallet's WDK instance and removes the session from the daemon. The daemon exits after the last wallet locks.

Verify the result:

wdk wallet list

Cleanup is best effort. The CLI zeroes retained mutable key and seed buffers on normal disposal, but JavaScript strings, dependency-internal copies, swap, core dumps, and abrupt termination cannot be guaranteed to be erased. See the security model.

Export a seed phrase

Export a wallet:

wdk wallet export --name dev

The CLI asks for the wallet passphrase and prints the phrase. --json also includes the phrase in stdout; JSON does not make secret output safe to log.

Use export to create or verify an offline recovery backup. If WDK CLI itself is unavailable, use the standalone version 1 manual-recovery procedure.

Rename a wallet

Rename a stored wallet:

wdk wallet rename --name dev --new-name development

The command verifies the old wallet's passphrase, locks that wallet if it is unlocked, and moves its storage directory. If it was the default, the new name becomes the default. Unlock it again under the new name before using it:

wdk wallet unlock --name development

Renaming does not decrypt or re-encrypt seed.enc.

Delete a wallet

Delete a wallet:

wdk wallet delete --name development

The command:

1. verifies the wallet passphrase
2. attempts to lock an active session
3. recursively removes the wallet directory
4. chooses another stored wallet as the default when necessary

Deletion is ordinary filesystem removal, not secure erase. Copies can remain in backups, snapshots, journals, swap, or recoverable storage blocks.

Passphrases in automation

Commands that prompt for a passphrase read a non-empty WDK_PASSPHRASE value when it is set:

WDK_PASSPHRASE='YOUR_PASSPHRASE' wdk --json wallet unlock --name dev --ttl 5

Environment variables can leak through process inspection, child-process inheritance, command tracing, crash reports, or automation logs. Prefer the hidden interactive prompt. If automation is necessary:

• inject the value from a secret manager for one process
• disable command tracing and output capture
• do not commit the value to a script or configuration file
• lock the wallet and remove the environment variable immediately after use

Never pass the passphrase or mnemonic as a CLI argument.

Related pages

• API reference
• Architecture
• Storage format and manual recovery
• Security model