14. Daemon CLI & Entrypoint (fleetmesh_node.meshnode)

The fleetmesh_node.meshnode module is the primary entrypoint for the daemon, handling CLI arguments, command execution, and host lifecycle management.

14.1. Daemon Reference

meshnode: the operator’s command.

<!– commands:begin –>

meshnode init DIR generate keys, write config, mine and publish the descriptor meshnode run DIR start the node and tick until SIGTERM meshnode status DIR what the running node last wrote, and its trouble meshnode health DIR every error plane: relays, drops, rejections, failures meshnode whoami DIR the node’s identity: DID, npub, keys, descriptor meshnode enrol DIR TOKEN join a fleet with an fmenrol1 token minted for this node’s pubkey meshnode network DIR ACTION NETWORK ask an approved private network to admit this node meshnode visibility DIR show or set the node default public/private and per-app or per-protocol overrides meshnode check DIR is this directory a node that can run? exits 1 if not meshnode tick DIR one tick now, and what it did (needs the node running) meshnode api DIR the control socket described by itself: protocol, commands, arguments, replies meshnode peers DIR every peer: tiers, pending grant, last window, standing meshnode grant DIR PEER both grants with a peer, their history, and what waits for the boundary meshnode windows DIR PEER the windows this node priced for a peer meshnode account DIR ACTION everything billable, from the node’s own stores: budget, settlement, sidecar sessions, storage meshnode peer DIR PEER add a peer and shard to pull from meshnode unpeer DIR PEER stop pulling from a peer; the grants stay live meshnode trust DIR PEER inspect or set a peer’s tier, which nothing else can raise meshnode terminate DIR PEER end a peering: zero both grants and tell the peer (needs the node running) meshnode retire DIR leave the mesh in order: hand over every asserted shard, withdraw the claims, stop meshnode withdraw DIR PEER WINDOW withdraw a finding this node made about one window (needs the node running) meshnode standing DIR PEER TARGET ask a peer what it knows about a third node (needs the node running) meshnode reports DIR TARGET the kind 30802s about a node, weighed by this one (needs the node running) meshnode strain DIR what this node has survived, by direction, and the reserves it sets meshnode subsystems DIR every compartment of this node, and what each has refused meshnode refusals DIR every no this node said, across every compartment meshnode events DIR the node’s recent bus events, from memory meshnode subscribe DIR follow the node’s bus live, one line per event meshnode capacity DIR this node’s own ceiling, the pressure on it, and what it is shedding meshnode scheduled DIR every scheduled pull, throttles and holds meshnode coverage DIR ACTION SHARD the shards this node claims to hold, as kind 30803 meshnode descriptor DIR the kind 11801 this node published meshnode pull DIR PEER SHARD pull a shard from a peer now (needs the node running) meshnode bridge DIR ACTION interact with the Universal Nostr Relay Bridge meshnode compute DIR ACTION (experimental) inspect or interact with the compute market and order book meshnode dvm DIR ACTION (experimental) interact with the NIP-90 Data Vending Machine Gateway meshnode settle DIR ACTION (experimental) inspect settlement rails, escrows, and execute live payments meshnode gossip DIR ACTION (experimental) gossip/1.0 group topics: create and publish rosters, flood sealed wraps meshnode enclave DIR ACTION (experimental) inspect and interact with hardware enclaves and passkeys meshnode iroh DIR ACTION (experimental) iroh P2P QUIC transport diagnostics and control meshnode fips DIR ACTION (experimental) FIPS Native Datagram API transport diagnostics and control meshnode cluster DIR CLUSTER_ACTION manage a local multi-node testnet cluster meshnode nsite DIR ACTION (experimental) host static sites (NIP-5A): publish this node’s site, manage custom domains meshnode sidecars DIR ACTION fronted sidecars (grasp, ncontainer, magpie, …): self-test results, or run the tests now meshnode sidecar-manifest FILE write, lint or try a sidecar manifest with no node (for sidecar authors) meshnode plugin-check REF hold a plugin class to the rules the node applies at startup, with no node (for plugin authors)

<!– commands:end –>

Two kinds of command. The ones that read state read the node directory, so they work whether the node is running or not. The ones that change what the node is told to do - peer, unpeer, trust, coverage - write config.json and nothing else; a running node re-reads it every tick. The ones that need the daemon itself - pull, terminate, withdraw, standing, reports, tick, republish - go over the control socket in the directory, and say so when no node is running.

PEER may be a pubkey, a did:nostr, an npub, or an unambiguous prefix of a peer this node holds a grant with.

trust is the only thing that raises a peer’s tier. The severity ladder lowers one and never raises it, because standing is bought with observed time rather than granted by arithmetic; seeding a tier for a node you know out of band is a human decision, recorded as a signed grant and reversible. A peer left alone opens at probation, whose reporter weight is zero.

DIR holds keys.json (0600), config.json, descriptor.json, events.sqlite, grants.sqlite, accounts.sqlite, status.json and, while the node runs, the control socket.

The command table above sits between marker comments and is regenerated from the parser by scripts/check-cli.py –write; the checker fails when it drifts. The commands themselves live in fleetmesh_node/commands/*.py, one module per group; this file only assembles the parser and is the meshnode entrypoint.

fleetmesh_node.meshnode.build_parser(argv=None)[source]

The whole operator CLI. Separate from main() so a checker can walk it.

argv lets the plugins a node directory declares add their verbs (fleetmesh_node/commands register_plugin_cli); without it the parser is the core CLI alone, which is what the documentation checker reads.

Parameters:

argv (Sequence[str] | None)

Return type:

ArgumentParser

fleetmesh_node.meshnode.main(argv=None)[source]
Parameters:

argv (Sequence[str] | None)

Return type:

None