init | Lifecycle | Generates node keys, creates config.json, mines PoW, and publishes the initial descriptor. Supports --manifest and --peering. |
run | Lifecycle | Starts the node daemon, binds the relay face, opens control.sock, and ticks on cadence. |
retire [--revoke] | Lifecycle | Leaves the mesh in order: hands over asserted shards, withdraws claims, stops, and optionally publishes kind 11802 key revocation. |
status [--json] | Inspection | Identity, face port, stored events, active grants, pending changes, and last evaluated windows. |
health [--json] | Diagnostics | Relay connection status, drop counts, refused sessions, handler exceptions, and active throttles. |
capacity [--json] | Diagnostics | Configured aggregate ceilings, current pressure, engaged load-shedding rungs, and historical peak. |
subsystems [--json] | Diagnostics | Per-compartment status across all 23 core compartments and whichever of the 9 optional ones (p2p, gossip, compute, compute_wire, bridge, dvm, nsite, video, updates) the config enables, including compartment refusals. |
refusals [--last N] | Diagnostics | Structured log of every refused request and transaction, with specific failure reasons. |
events [--since N] [--topics ...] [--last N] | Diagnostics | The most recent event-bus envelopes the daemon still holds in memory (windows evaluated and repriced, sessions completed, grants issued, peers connected, reports read), with sequence numbers to resume from. |
subscribe [--since N] [--topics ...] | Diagnostics | Hold the control socket open and print one line per bus event as it happens; --since replays what the ring still holds first, and a slow reader is told how many envelopes it missed. The surface an out-of-process plugin follows. |
strain [--json] | Diagnostics | Survived environmental anomalies by direction, reserve multiples, and dominant share flag-tree warnings. |
whoami [--json] | Inspection | DID, pubkey, npub, encryption keys, declared endpoints, and descriptor PoW status. |
enrol TOKEN [--force] [--json] | Lifecycle | Join a fleet with an fmenrol1… token the operator minted for this node's pubkey (whoami shows it). Verifies the fleet/enrol grant against the node's own key and the clock, writes the operator into config.json and the kind 11801, republishes descriptor and heartbeat. Already under that operator: a no-op. Under another: refused already_enrolled unless --force. |
network DIR join NETWORK [--note TEXT] [--json] | Networks | Asks an approved private network to admit this node (plan D26/H4): the running node fetches the current kind 30830 from its known relays, refuses locally if the policy is not approved or the roster already names it, then publishes a sealed network/1.0 join-request to the definition's own relays. meshnode status shows the ask pending until a definition naming the node appears (then it is a member) or a join-decline arrives (then declined). |
visibility DIR [--default public|private] [--set URI=public|private]... [--clear URI]... [--json] | Networks | Shows or sets this node's public/private default and one override per protocol or app (plan D2, the kind 11801 visibility and expose tags). With no arguments it reads the resolved state - the default, each override, and which protocols and capabilities are public - from the running node or from config.json. Setting reaches a running node over its socket, which rebuilds the descriptor and republishes the public copy, or retracts the last one with a NIP-09 kind 5 when the node goes fully private; with no node running it writes config.json. A private unit is refused at its own door too, not merely hidden: a private relay requires NIP-42 AUTH and admits only a key a private network this node shares admits, and a private blossom requires a BUD kind 24242 authorization from such a member. A private relay's read-only HTTP surfaces are gated the same way: /metrics and /gossip answer 401 while the relay is private, and NIP-11 is still served so a client can read limitation.auth_required and learn authentication is needed. A private blossom also requires a BUD list authorization on GET /list/<pubkey>, so a stranger cannot enumerate what one account uploaded. A fully private node's heartbeat and retiring announce keep going out - to its network relays, never a public one - so its owner and the members of its private networks still see it is alive, while its telemetry and NIP-66 discovery and coverage stay suppressed. |
check [--json] | Verification | Validates directory permissions (0600), config schema, descriptor digest, and SQLite database integrity. |
peers [--json] | Peering | All peered nodes, active tiers in both directions, clean window streaks, and shard pulls. |
grant <peer> [--json] | Accounting | Inspects bilateral grants with a specific peer: limits, cadence, scope, and envelope history. |
windows <peer> [--last N] | Accounting | Evaluated windows for a peer: measured vs. claimed counters, receipts sent/received, and severity rating. |
account export [--json] [--since N] | Accounting | Everything billable, read from the node's own stores: metered budget and receipts, settlement escrows and ecash ledgers, sidecar sessions, and storage served. Keyed by the node's pubkey so several nodes' exports merge; secrets never leave. |
scheduled [--json] | Inspection | Displays every scheduled pull, when it last ran, active throttles, capacity holds, and declines. |
descriptor [--republish] | Inspection | Displays the local node kind 11801 descriptor event; --republish resends it. |
peer <peer> --shard NAME --filter JSON | Config | Adds a shard pull from a peer to config.json, on the operator's cadence. The daemon reconciles state on the next tick. |
unpeer <peer> [--shard NAME] | Config | Removes the pull from config.json. The grants stay live; terminate ends the peering. |
trust [peer] [--tier] | Config / Inspection | Inspects active trust decisions across peers, or seeds an operator trust tier in config.json. |
coverage list|add|remove | Config | Manages shard coverage claims published across the mesh as kind 30803 events. |
pull <peer> <shard> | Action | Triggers an immediate Negentropy synchronization cycle with a designated peer. |
terminate <peer> | Action | Cleanly terminates an active peering: zeroes both grants and notifies the peer. |
withdraw <peer> <window> | Action | Withdraws an adverse finding or report about a specific window epoch on the complaint thread. |
standing <peer> <target> | Action | Queries the peer local standing ledger about a third node over standing/1.0. |
reports <target> | Action | Fetches kind 30802 dispute reports about a node from relays, weighted by the local node ledger. |
tick [--json] | Action | Forces an immediate scheduler evaluation and housekeeping tick. |
api [--json] | Inspection | Introspects the control socket protocol, available commands, and dispatch schema. |
bridge [action] [--relay URL] [--event JSON] [--filter JSON] | Bridge | Interacts with the Universal Nostr Relay Bridge: status, publish, add-relay, remove-relay, sync, and range-bounded reconcile backfill. |
gossip [action] [--name N] [--member PK]... [--ttl S] [--topic ID] [--event JSON|@file] | Gossip | Experimental. gossip/1.0 group topics: status, topics, create (signs and publishes a kind 30804 roster for <node pk>:<name>; --no-relay keeps it local), admit another admin's roster that names this node (a roster published to the relays by a peer this node holds a grant with is admitted on its own; admit is for one handed over by other means), leave, and publish a sealed NIP-59 wrap into a topic mesh. GET /gossip on the relay face is the read-only view of the same rosters, and answers 401 while the relay is private (like /metrics; NIP-11 stays served). |
compute [action] [--engine] [--rate] [--ask] | Compute | Experimental. Inspects or interacts with the compute market and order book: status, show, book, offer, match, and receipts. |
dvm [action] [--request JSON] | Compute | Experimental. Interacts with the NIP-90 Data Vending Machine Gateway: status, show telemetry, process, and delegate compute requests. |
sidecars DIR [status|test] [--name N] [--json] | Diagnostics | Shows each configured sidecar (manifest, endpoint, last self-test result, declared capability) or re-runs a sidecar's self-tests on demand; a capability is advertised on the descriptor only while its checks pass. |
sidecar-manifest FILE [--init NAME] [--endpoint URL] [--json] | Diagnostics | Author's offline tool: --init writes a template manifest, a plain run lints one (exit 2 if it is not a manifest), --endpoint runs its self-tests against a live URL without a node (exit 1 on a failed check). |
plugin-check REF [--json] | Diagnostics | Plugin author's conformance check, no node: imports package.module:Class and holds it to the rules the node applies at startup - the subsystem/1 declaration, dialects and sidecar manifests on their own origin, no CLI verb that collides. Exit 1 on a finding, 2 if the ref will not import. |
nsite [action] [--path DIR] [--site D] [--snapshot] [--domain-claim X] [--domain X] | Sites | Experimental. Hosts static sites per NIP-5A: publish uploads a directory to the node's Blossom face and signs the kind-15128/35128 manifest (--snapshot adds an immutable kind-5128 copy), domains, verify and forget manage custom-domain bindings proven by a _nsite TXT record plus a manifest domain tag, status shows cache and quota totals. |
cluster [action] [--nodes N] [--topology T] | Cluster | Manages a local multi-node testnet cluster: start, status, stop, and sync across mesh, star, ring, or line topologies. |
settle [action] [--ask ID] [--amount N] [--rail R] | Settlement | Experimental. Inspects settlement rails and escrows: status, create, hold, settle, nwc-pay, cashu-swap, and cashu-melt. |
enclave [action] [--type p256|secp256k1] [--message M] [--sig S] [--pub P] | Transport | Experimental. Hardware enclaves and passkeys: status, generate a key, sign a message, verify a signature against a multikey. Exits 1 on a verification that fails. |
iroh [action] [--host H] [--port P] [--ticket T] [--to PK] [--message M] | Transport | Experimental. iroh QUIC transport diagnostics: status, probe and punch a remote endpoint, send a payload to a ticket or pubkey. |
fips [action] [--sock PATH] [--port P] [--peer PK] [--message M] | Transport | Experimental. FIPS Native Datagram API control: status, probe the control socket, listen on an FSP port, connect a flow to a peer, send a framed datagram, and list flows. |