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 and rejects empty or whitespace-only values.

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.

List wallets

$ beam wallets list

Lists every stored wallet with its alias and address.

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.
• 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.