Configuration

Files

Path	Purpose
~/.beam/config.json	Global defaults: default chain, default wallet, known tokens, tracked tokens, per-chain RPC config
~/.beam/chains.json	Custom chain metadata (built-in chains are baked into the binary)
~/.beam/wallets.json	Encrypted keystore
~/.beam/privacy-state.json	Resume cache for private-transfer scan progress, owned-note checkpoints, pending operations
~/.beam/history.txt	REPL history (sanitized — sensitive commands are excluded)
~/.beam/update-status.json	Cached GitHub release check for the background update notice

Relocating state

Set BEAM_HOME to use a different directory:

$ BEAM_HOME=/tmp/beam beam wallets list

All Beam state — wallets, chains, tokens, privacy resume cache, REPL history — moves under that root.

config.json fields

• default_chain — chain selector used when --chain is not passed.
• default_wallet — wallet selector used when --from is not passed.
• known_tokens — preloaded ERC20 metadata (label → address + decimals).
• tracked_tokens — per-chain list shown by beam balance and beam tokens.
• rpc_configs — per-chain RPC URLs plus the active default for each chain.

Output formats

Most commands accept --format <mode>:

• default — human-friendly text with color and spinners (default in TTYs).
• json — structured payload for scripting.
• yaml — same data as json, YAML-encoded.
• markdown — Markdown table output for some commands.
• compact — single-line, minimal text.
• quiet — print only the essential value (e.g. just a tx hash).

$ beam --format json balance
$ beam --format quiet transfer alice.eth 0.01

Non-interactive update notices are only printed in default output mode and use the cached release status instead of hitting GitHub before the command runs.

Color

$ beam --color auto    # default
$ beam --color always
$ beam --color never

Beam writes color codes when the destination is a terminal. Override the heuristic with --color.

Validation

Beam validates RPC URLs before running a command, so malformed values from --rpc, config.json, or beam chains add fail with a normal CLI error instead of crashing. It also rejects decimal precisions above 77 when converting human-readable amounts into on-chain integer units, so hostile token metadata or oversized manual --decimals input never produces a runtime panic.