Wallets

Create a wallet

$ beam wallets create [name]

Creates a new wallet and (when no name is passed) prompts for one — Beam suggests the next available wallet-N alias and accepts it on Enter. The CLI also prompts for a keystore password. Press Enter for no password; whitespace-only passwords are rejected.

The first wallet created becomes the default sender. Override with --from <name|address|ens> on any command, or change the default with beam wallets use.

Import an existing wallet

$ beam wallets import [--name <name>]
$ beam wallets import --private-key-stdin --name alice
$ beam wallets import --private-key-fd 3 --name alice 3< /path/to/key

By default the private key is read from a hidden prompt. For pipelines, use --private-key-stdin. For redirected file descriptors, use --private-key-fd <fd>.

When --name is omitted, Beam uses a verified ENS reverse record as the default alias (when one resolves back to the imported address); otherwise it falls back to the next wallet-N.

Export a private key

$ beam wallets export-private-key [wallet]
$ beam --format compact wallets export-private-key alice
$ beam --format json wallets export-private-key alice

Exports the stored wallet's raw primary EVM private key after prompting for the keystore password. When [wallet] is omitted, Beam exports the active wallet: the configured default unless --from overrides it.

Important: The exported private key gives full control over that wallet. Do not paste it into command arguments, shell variables, issue trackers, chat, screenshots, or logs. This is the primary EVM private key stored by Beam.

Export a recovery phrase

$ beam wallets export-recovery-phrase [wallet]

Exports a 24-word BIP39 recovery phrase for the selected stored wallet. When [wallet] is omitted, Beam exports the active wallet: the configured default unless --from overrides it.

This phrase is an entropy backup for one wallet: Beam maps the 32-byte EVM private key directly to a 24-word BIP39 phrase. It is not a MetaMask or HD-wallet seed phrase, and Beam does not use a derivation path, account index, or seed expansion.

Treat the phrase exactly like the private key. Avoid plaintext files, command arguments, and shell variables because shell history can persist those values.

Import a recovery phrase

$ beam wallets import-recovery-phrase [--name <name>]
$ beam wallets import-recovery-phrase --expected-address 0x1111111111111111111111111111111111111111 --name alice
$ beam wallets import-recovery-phrase --phrase-stdin --name alice
$ beam wallets import-recovery-phrase --phrase-fd 3 --name alice 3< <(pass show beam/alice/recovery-phrase)

By default the phrase is read from a hidden prompt. For pipelines, use --phrase-stdin. For already-open file descriptors, use --phrase-fd <fd>; the file-descriptor form is mainly for secret-manager streams and tests, not plaintext phrase files.

Importing a recovery phrase prints the derived EVM wallet address before asking for the new wallet password. Use --expected-address <address> to fail before persistence if the phrase derives a different address than expected.

In the Beam REPL, wallets import-recovery-phrase commands are not written to history.txt. wallets export-recovery-phrase may be recorded, but the phrase itself is never part of the command line.

Importing the phrase restores the same EVM address and the same private address. It does not restore local Beam config, privacy scan state, REPL history, custom RPCs, token labels, or pending claim artifacts.

List wallets

$ beam wallets list

Lists every stored wallet with its alias and address.

Change a wallet password

$ beam wallets change-password [wallet]

Re-encrypts the selected wallet with a new password. Beam first asks for the current password, then asks for the new password and confirmation. Press Enter at the current password prompt for a wallet that was created with no password.

Use this before creating a profile for an existing empty-password wallet. Profiles require a non-empty wallet password.

Show an address

$ beam wallets address [--private-key-stdin | --private-key-fd <fd>]

Prints the address derived from a private key without storing the wallet. Same prompt rules as import.

Rename a wallet

$ beam wallets rename <name|address|ens> <new-name>

Renames the wallet matched by the first argument. Names can't start with 0x (reserved for raw addresses), and ENS names must resolve back to the wallet's address before Beam accepts them.

Switch the default

$ beam wallets use <name|address|ens>

Sets the default --from for subsequent commands. Persisted to ~/.beam/config.json.

Selectors

Wallet/address selectors accept:

• A stored wallet name (e.g. alice)
• A raw 0x... address (40 hex chars after the prefix)
• An ENS name like alice.eth (resolved via the configured Ethereum RPC, which must report chain id 1)

For signing commands, the selector must still resolve to a wallet in the local keystore — passing a raw address or ENS for --from only works when that address is in wallets.json.

Notes on the keystore

• Private keys are encrypted before they are written to disk. Each wallet record carries its KDF metadata so future Beam releases can keep decrypting older wallets after Argon2 tuning changes.
• Recovery phrases are as sensitive as private keys because they encode the same 32-byte wallet secret.
• Commands that need to sign re-prompt for the keystore password.
• Before signing, Beam re-derives the decrypted wallet address and rejects any entry whose key does not match the stored address.
• If wallets.json contains invalid JSON, Beam fails closed and won't rewrite the file until you repair or restore it.
• Wallet names are trimmed and stripped of terminal control characters; aliases that become empty after normalization are rejected.

Future: hardware wallets

The signing flow is built on a Signer abstraction so hardware-wallet implementations can be added later without changing command handlers.