merod CLI Reference

merod is the node daemon. Every invocation takes two global arguments, then a subcommand.

Global arguments

Flag	Type	Default	Notes
--home <PATH>	path	platform node directory	Directory for config and data. Env: CALIMERO_HOME.
-n, --node <NAME>	name	— (required)	Name of the node; its home is <home>/<NAME>.

merod --home data/ --node node1 <subcommand>

Subcommands: init, config, run (alias up), kms.

init

Initialize node configuration: creates the home directory, generates an ed25519 identity keypair, writes config.toml, and opens the datastore.

Flag	Type / values	Default	Purpose
--boot-nodes <ADDR>	multiaddr (repeatable)	—	Explicit bootstrap node multiaddrs.
--boot-network <NETWORK>	calimero-dev, ipfs	calimero-dev	Use a known network’s bootstrap nodes.
--swarm-host <HOST>	IP list	0.0.0.0,::	Hosts to listen on for the libp2p swarm.
--swarm-port <PORT>	u16	2428	Swarm (peer-to-peer) port.
--server-host <HOST>	IP list	127.0.0.1,::1	Hosts to listen on for the RPC server.
--server-port <PORT>	u16	2528	RPC / admin / JSON-RPC / WS / SSE port.
--auth-mode <MODE>	proxy, embedded	proxy	Authentication mode for server endpoints.
--auth-storage <KIND>	persistent, memory	persistent	Embedded-auth storage backend (only with --auth-mode embedded).
--auth-storage-path <PATH>	path	auth	Embedded-auth storage path (persistent storage only).
--mdns	bool	true	Enable mDNS local discovery.
--advertise-address	bool	false	Advertise the node’s observed address.
--external-address <MULTIADDR>	multiaddr (repeatable)	—	Static external multiaddrs to advertise. Pair with --advertise-address for them to be advertised.
--rendezvous-registrations-limit <N>	usize	3	Max rendezvous registrations.
--relay-registrations-limit <N>	usize	3	Max relay registrations.
--autonat-probe-interval <SECS>	u64	10	Interval between AutoNAT probes, in seconds.
--autonat-max-candidates <N>	usize	5	Max untested address candidates to probe with AutoNAT.
--force	bool	false	Wipe and re-initialize even if the directory already exists.
--mode <MODE>	standard, read-only	standard	Node operation mode (read-only disables JSON-RPC execution).

# Initialize with the default network and ports
merod --node node1 init

# Initialize with custom ports
merod --node node1 init --server-port 2528 --swarm-port 2428

Note

--server-host defaults to loopback (127.0.0.1,::1), so the RPC server is not reachable off-host until you widen it. The swarm host defaults to all interfaces (0.0.0.0,::).

config

Update keys in the node’s config.toml. Arguments are key=value pairs where the key is a dotted TOML path. The change is validated by reloading the resulting config before it is written.

# Quote the argument so your shell does not glob the brackets
merod --node node1 config "server.listen=['/ip4/127.0.0.2/tcp/3000', '/ip6/::1/tcp/3000']"

There are no flags — only positional key=value arguments (repeatable).

run

Run the node: loads and validates config.toml, then starts the swarm and RPC server. Foreground process. Alias: up.

Flag	Type / values	Default	Purpose
--auth-mode <MODE>	proxy, embedded	—	Override the authentication mode from config.toml for this run.
--mock-tee	bool	false	DEV/TEST ONLY. Produce/accept mock TEE attestation quotes. Env: MEROD_MOCK_TEE.

merod --node node1 run
merod --node node1 up --auth-mode embedded

--mock-tee is insecure

--mock-tee bypasses real TDX attestation and is for development and testing only. The node refuses to start with --mock-tee if a real KMS attestation is configured.

Startup release check (outbound network call)

On roughly 10% of startups (sampled at random), merod makes a best-effort background call to https://api.github.com/repos/calimero-network/core/releases/latest to see whether a newer release exists, printing a notice if so. There is no opt-out flag, and any failure is silently ignored, so it never blocks startup. Operators in air-gapped, egress-restricted, or privacy-sensitive environments should be aware of this occasional outbound request to GitHub.

kms

KMS (key management service) operations for TEE-enabled nodes.

kms probe

Probe the KMS attestation and storage-key fetch flow against the node’s configured TEE/KMS settings.

Flag	Type	Default	Purpose
--kms-url <URL>	URL	—	Override the configured KMS URL for this probe.
--json	bool	false	Emit the probe result as machine-readable JSON.

merod --node node1 kms probe
merod --node node1 kms probe --json

Caution

kms probe requires a node whose config has a tee.kms.phala section; it errors if TEE/KMS is not configured.

Example: a long-lived node

A hosted node that should rejoin the network across restarts is initialized once with a persistent home, has its config.toml adjusted for the deployment, then runs as a foreground service (under your process supervisor).

1. Initialize under a stable home directory. Keep the RPC server on loopback so it is only reachable through a local reverse proxy:

   merod --home /var/lib/calimero --node node1 init \
     --server-port 2528 --swarm-port 2428

2. Edit config.toml for a datacenter deployment — turn off LAN discovery, dial known peers on startup, and advertise a stable public swarm address instead of relying on AutoNAT. These keys live in the file init wrote (<home>/node1/config.toml):

   [bootstrap]
   nodes = [
       "/ip4/198.51.100.7/tcp/2428/p2p/12D3KooW…<peer-id>",
   ]
   
   [discovery]
   mdns = false
   advertise_address = true
   external_address = ["/ip4/203.0.113.10/tcp/2428"]

   You can apply individual keys without hand-editing using the config subcommand, which validates the result before writing:

   merod --home /var/lib/calimero --node node1 config "discovery.mdns=false"

3. Run the node. It reloads and validates config.toml, then stays in the foreground:

   merod --home /var/lib/calimero --node node1 run

Note

init seeds the swarm on all interfaces (0.0.0.0,::) but the RPC server on loopback only. Widen server.listen only if something off-host must reach the API directly; otherwise terminate TLS and authenticate at a reverse proxy in front of the loopback port.

Next steps

Configuration referenceEvery config.toml section the init flags seed and run reads back.

meroctl referenceThe operator CLI that talks to the node you just ran.

Production deploymentRun merod as a long-lived service behind a reverse proxy.