8. Command Dispatcher & CLI (fleetmesh_node.commands)
The fleetmesh_node.commands package implements the execution layer for commands invoked
via the control socket (meshctl) or daemon CLI. Every command is governed by
declarative permission requirements, parameter schemas, and UCAN authorization tokens.
8.1. Command Base Interface
Common helpers and base structures for meshnode CLI command providers.
- fleetmesh_node.commands.base.fail(msg, code=2)[source]
Say why on stderr and stop with code. The one way a command gives up.
- fleetmesh_node.commands.base.emit(a, payload, human=None, indent=2)[source]
Print payload as JSON under –json, otherwise hand it to human.
The JSON side is the contract scripts read, so it is produced here and nowhere else: json.dumps(payload, indent=indent) on one line of stdout per call. A command whose human rendering is long may pass no human, test a.json itself and return emit(a, payload) from the JSON branch.
- fleetmesh_node.commands.base.load_json_arg(value, what='argument', on_error=None)[source]
A JSON argument given inline or as @path to a file holding it.
A value that is not JSON fails the command naming what, unless on_error is given, in which case it decides what the raw text means.
- fleetmesh_node.commands.base.get_grants_store(directory)[source]
- Parameters:
directory (str)
- Return type:
- fleetmesh_node.commands.base.resolve_peer_arg(directory, arg)[source]
A peer, from a pubkey, a DID, an npub, or an unambiguous prefix of a known one.
- fleetmesh_node.commands.base.resolve_peer_or_raw(a, arg)[source]
resolve_peer_arg when the command has a node directory to ask, else the argument as given. For transport commands, which also run without a node.
- fleetmesh_node.commands.base.set_daemon_caller(caller)[source]
Set custom daemon caller implementation for testing without monkeypatching.
- fleetmesh_node.commands.base.reset_daemon_caller()[source]
Clear custom daemon caller implementation.
- Return type:
None
- fleetmesh_node.commands.base.override_daemon(caller)[source]
Context manager to cleanly override daemon calls for tests.
- fleetmesh_node.commands.base.ask_daemon(directory, cmd, **args)[source]
One call over the control socket, or exit with the daemon’s complaint.
Can be cleanly intercepted in tests via override_daemon(fake) or set_daemon_caller(fake).
- fleetmesh_node.commands.base.try_ask(directory, cmd, **args)[source]
One call over the control socket, or None when the node is not there or declined. For best-effort fan-out, where one silent node must not stop the command.
- fleetmesh_node.commands.base.read_status_file(directory)[source]
- Parameters:
directory (str)
- Return type:
- fleetmesh_node.commands.base.status_health(directory)[source]
The health block of the last status.json, or {} when it has none.
- Parameters:
directory (str)
- Return type:
8.2. Core Command Handler
Core node lifecycle, health, identity, and operator diagnostics.
- class fleetmesh_node.commands.core.EnrolCli[source]
Bases:
EnrolResultWhat meshnode enrol prints: the daemon’s reply, or the file-based one.
- class fleetmesh_node.commands.core.WhoamiReport
Bases:
TypedDict- descriptor: WhoamiDescriptorSummary | None
- endpoints: list[EndpointDict]
- fleetmesh_node.commands.core.cmd_check(a)[source]
Everything that would stop run, named at once. Exits 1 when it cannot.
- fleetmesh_node.commands.core.cmd_enrol(a)[source]
Join a fleet with an fmenrol1 token minted for THIS node (plan D18/D19). With the node running the daemon does it (verify, config, descriptor, heartbeat go out at once); otherwise the same decision runs here against the files, and the next run mines the descriptor with the new operator. meshnode whoami shows the pubkey the operator mints for.
- fleetmesh_node.commands.core.cmd_network(a)[source]
Ask an approved private network to admit this node (plan D26/H4).
The running node fetches the current definition from the relays it knows, refuses locally if the policy is not approved or the roster already names this node, then publishes a sealed join-request to the definition’s own relays. The ask is tracked: meshnode status shows it pending until a definition naming the node appears, or a join-decline arrives.
- fleetmesh_node.commands.core.cmd_visibility(a)[source]
Show, or set, this node’s public/private default and its per-unit overrides (plan D2).
With no arguments it reads: a running node’s status, else config.json and the descriptor it last mined. –default sets the node default, –set ID=public|private adds one override (repeatable) and –clear ID removes one. Setting reaches a running node over its socket - which rebuilds and republishes at once, or retracts the public descriptor when the node goes fully private - and writes config.json when no node is up, so the next run publishes the new descriptor.
8.3. Command Adapter
CLI Adapter: bridge declarative Compartment Commands to the operator CLI.
Converts declarative Command and Parameter definitions into argparse subcommands and arguments, and provides table-driven action dispatching.
- fleetmesh_node.commands.adapter.add_parameter_argument(parser, param, help_prefix='', require_flag=False)[source]
Register a Parameter on an ArgumentParser.
Uses cli_name, short, and positional if specified, otherwise derives long option as –<param.key_with_dashes>. Skips if param.cli is False or if the flag is already registered on the parser.
- Parameters:
parser (ArgumentParser)
help_prefix (str)
require_flag (bool)
- Return type:
None
- class fleetmesh_node.commands.adapter.ActionDef[source]
Bases:
objectDefinition of one action in a multi-action command group.
- __init__(name, command=None, human=None, timeout=10.0, handler=None, arg_map=<factory>, parameters=())
- class fleetmesh_node.commands.adapter.CommandDispatcher[source]
Bases:
objectTable-driven multi-action dispatcher and argument builder for CLI subcommands.
- add_command(action_name, command, human=None, timeout=10.0, arg_map=None, extra_parameters=())[source]
Register an action backed directly by a compartment Command.
- add_custom(action_name, handler, parameters=())[source]
Register an action with custom client-side handling logic.
- register_arguments(parser, action_choices=None, action_dest=None)[source]
Register the action positional argument and all action parameters.
- Parameters:
parser (ArgumentParser)
action_dest (str | None)
- Return type:
None
8.4. Transport Commands
Transport CLI subcommands: FIPS native, Iroh QUIC, and Hardware Enclave.
8.5. Peering Commands
Peering management, bilateral grants, accounting windows, and trust tiers.
- fleetmesh_node.commands.peering.cmd_trust(a)[source]
The one decision that raises a tier, and it is a person’s.
8.6. Compute Commands
Compute market, order book, DVM gateway, and settlement rails.
8.7. Gossip Mesh Commands
Gossip topics: create and publish rosters, admit another admin’s, leave, and flood a sealed wrap into a mesh. Every verb is the running daemon’s (it holds the keys and the mesh); this module is the operator’s words for them.
8.8. Sidecar Commands
Sidecars: what the node fronts (GRASP git, ncontainer OCI, magpie files, or anything an operator brings a manifest for), whether each has passed its self-tests, and a way to run those tests now. The daemon owns the answer - it is the one that declared or withheld the capability on the descriptor.
sidecar-manifest is the offline half: write a starting manifest, lint one, or run its checks against an endpoint with no node at all - what a developer does before an operator ever configures it.
8.9. Sync Commands
Sync scheduling, shard coverage claims, capacity metering, and strain telemetry.
- fleetmesh_node.commands.sync.cmd_strain(a)[source]
What this node has survived, and what it holds because of it.
- fleetmesh_node.commands.sync.cmd_subsystems(a)[source]
Every compartment of this node, side by side.
- fleetmesh_node.commands.sync.cmd_events(a)[source]
What the node’s bus carried lately, from memory; needs the daemon.
- fleetmesh_node.commands.sync.cmd_subscribe(a)[source]
Follow the node’s bus live: one line per event until interrupted.
- fleetmesh_node.commands.sync.cmd_capacity(a)[source]
The node’s own ceiling: what it promised its peers against what the machine was told it can do.
8.10. Cluster Commands
The cluster subcommand: a local multi-node testnet on one machine.
Owns the command body and its place in the operator’s parser, like every other module under fleetmesh_node/commands. The body used to sit at the bottom of fleetmesh_node/testnet/cluster.py; the cluster engine now knows nothing about argparse or how its status is printed.
- class fleetmesh_node.commands.cluster_cmds.ClusterStatusSummary[source]
Bases:
TypedDict- fips: ClusterFipsStatus
- nodes: list[ClusterNodeSummary]
8.11. nsite Commands
nsite: publish this node’s static site and watch the gateway.
publish is the only command that moves bytes: it walks a directory, PUTs each file to the node’s own Blossom face (signed with the node key, over loopback, so the face’s auth switch does not matter), then asks the daemon to sign and publish the manifest from the resulting hashes. The control socket never carries file bodies.
8.12. Plugin Commands
plugin-check REF: the conformance check a plugin author runs before an operator ever lists the plugin in a config. No node, no keys: the module is imported and the class is held to exactly the rules fleetmesh_node/app/core.py applies at startup (load_plugins, the PIURI origin rule, plugin_sidecars) and fleetmesh_node/commands applies to its verbs - the same functions, not a copy of them, so the check cannot drift from the node. Exit 0 when every rule holds, 1 when one does not (each failure on its own line), 2 when REF cannot be imported at all.
- fleetmesh_node.commands.plugin_cmds.check_plugin(ref)[source]
Every rule, as {‘ref’, ‘ok’, ‘name’, ‘findings’: [..], ‘declares’: {…}}. Raises ValueError when the ref does not import (nothing else to say).