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.

Parameters:
Return type:

NoReturn

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.

Parameters:
Return type:

int

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.

Parameters:
Return type:

Any

fleetmesh_node.commands.base.load_doc(path)[source]
Parameters:

path (str)

Return type:

Any

fleetmesh_node.commands.base.render_table(headers, rows)[source]
Parameters:
Return type:

None

fleetmesh_node.commands.base.format_when(epoch, window=3600)[source]
Parameters:
Return type:

str

fleetmesh_node.commands.base.short_pk(pk)[source]
Parameters:

pk (str | None)

Return type:

str

fleetmesh_node.commands.base.get_grants_store(directory)[source]
Parameters:

directory (str)

Return type:

GrantStore

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.

Parameters:
Return type:

str

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.

Parameters:
Return type:

str

fleetmesh_node.commands.base.set_daemon_caller(caller)[source]

Set custom daemon caller implementation for testing without monkeypatching.

Parameters:

caller (Callable[[...], Any] | None)

Return type:

None

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.

Parameters:

caller (Callable[[...], Any])

Return type:

Any

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).

Parameters:
Return type:

Any

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.

Parameters:
Return type:

Any

fleetmesh_node.commands.base.read_status_file(directory)[source]
Parameters:

directory (str)

Return type:

NodeStatusDict

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:

HealthStatusDict

fleetmesh_node.commands.base.extract_trouble(health)[source]
Parameters:

health (HealthStatusDict | Mapping[str, Any] | None)

Return type:

list[str]

fleetmesh_node.commands.base.add_command(sub, name, fn, help, peer=False, js=False, experimental=False)[source]

A subcommand taking DIR. experimental marks it in meshnode –help and says what that means in its own –help (ALPHA.md lists what is experimental).

Parameters:
Return type:

ArgumentParser

8.2. Core Command Handler

Core node lifecycle, health, identity, and operator diagnostics.

class fleetmesh_node.commands.core.EnrolCli[source]

Bases: EnrolResult

What meshnode enrol prints: the daemon’s reply, or the file-based one.

live: bool
class fleetmesh_node.commands.core.WhoamiDescriptorSummary[source]

Bases: TypedDict

id: str
pow_bits: int
expires: int | None
protocol: str | None
implements: list[str]
class fleetmesh_node.commands.core.FaceDict[source]

Bases: TypedDict

host: str
port: int
class fleetmesh_node.commands.core.EndpointDict[source]

Bases: TypedDict

transport: str
address: str
ticket: str
priority: int
class fleetmesh_node.commands.core.WhoamiReport

Bases: TypedDict

did: str
pubkey: str
npub: str
agreement: str
transport: str
config_error: str | None
descriptor: WhoamiDescriptorSummary | None
running: bool
class: str | None
name: str | None
operator: str | None
relays: list[str]
face: FaceDict
endpoints: list[EndpointDict]
fleetmesh_node.commands.core.cmd_init(a)[source]
Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.core.cmd_run(a)[source]
Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.core.cmd_status(a)[source]
Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.core.cmd_health(a)[source]
Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.core.cmd_whoami(a)[source]
Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.core.cmd_check(a)[source]

Everything that would stop run, named at once. Exits 1 when it cannot.

Parameters:

a (Namespace)

Return type:

int

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.

Parameters:

a (Namespace)

Return type:

int

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.

Parameters:

a (Namespace)

Return type:

int

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.

Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.core.cmd_tick(a)[source]
Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.core.cmd_api(a)[source]

The control socket described by itself.

Parameters:

a (Namespace)

Return type:

int

class fleetmesh_node.commands.core.CoreCommandProvider[source]

Bases: object

Registers core lifecycle, health, identity, and operator commands.

classmethod register(sub)[source]
Parameters:

sub (_SubParsersAction)

Return type:

None

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:
Return type:

None

class fleetmesh_node.commands.adapter.ActionDef[source]

Bases: object

Definition of one action in a multi-action command group.

name: str
command: Command | None = None
human: Callable[[...], None] | None = None
timeout: float = 10.0
handler: Callable[[Namespace], int] | None = None
arg_map: dict[str, str]
parameters: tuple[Parameter[Any], ...] = ()
__init__(name, command=None, human=None, timeout=10.0, handler=None, arg_map=<factory>, parameters=())
Parameters:
Return type:

None

class fleetmesh_node.commands.adapter.CommandDispatcher[source]

Bases: object

Table-driven multi-action dispatcher and argument builder for CLI subcommands.

__init__(subsystem, default_action='status', action_dest='action')[source]
Parameters:
  • subsystem (str)

  • default_action (str)

  • action_dest (str)

Return type:

None

actions: dict[str, ActionDef]
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.

Parameters:
Return type:

ActionDef

add_custom(action_name, handler, parameters=())[source]

Register an action with custom client-side handling logic.

Parameters:
Return type:

ActionDef

register_arguments(parser, action_choices=None, action_dest=None)[source]

Register the action positional argument and all action parameters.

Parameters:
Return type:

None

dispatch(a)[source]

Execute the requested action from parsed namespace.

Parameters:

a (Namespace)

Return type:

int

8.4. Transport Commands

Transport CLI subcommands: FIPS native, Iroh QUIC, and Hardware Enclave.

class fleetmesh_node.commands.transport_cmds.FipsFlowInfo[source]

Bases: TypedDict

flow: str
fileno: int
status: str
fleetmesh_node.commands.transport_cmds.cmd_enclave(a)[source]
Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.transport_cmds.cmd_iroh(a)[source]
Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.transport_cmds.cmd_fips(a)[source]
Parameters:

a (Namespace)

Return type:

int

class fleetmesh_node.commands.transport_cmds.TransportCommandProvider[source]

Bases: object

Registers transport diagnostic and control commands.

classmethod register(sub)[source]
Parameters:

sub (_SubParsersAction)

Return type:

None

8.5. Peering Commands

Peering management, bilateral grants, accounting windows, and trust tiers.

fleetmesh_node.commands.peering.cmd_peers(a)[source]
Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.peering.cmd_grant(a)[source]
Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.peering.cmd_windows(a)[source]
Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.peering.cmd_peer(a)[source]
Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.peering.cmd_unpeer(a)[source]
Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.peering.cmd_trust(a)[source]

The one decision that raises a tier, and it is a person’s.

Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.peering.cmd_terminate(a)[source]
Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.peering.cmd_retire(a)[source]

Leave the mesh in order. Not what a restart does.

Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.peering.cmd_withdraw(a)[source]
Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.peering.cmd_standing(a)[source]
Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.peering.cmd_reports(a)[source]
Parameters:

a (Namespace)

Return type:

int

class fleetmesh_node.commands.peering.PeeringCommandProvider[source]

Bases: object

Registers peer management, trust tier, bilateral grant, and report commands.

classmethod register(sub)[source]
Parameters:

sub (_SubParsersAction)

Return type:

None

8.6. Compute Commands

Compute market, order book, DVM gateway, and settlement rails.

fleetmesh_node.commands.compute_cmds.cmd_bridge(a)[source]
Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.compute_cmds.cmd_compute(a)[source]
Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.compute_cmds.cmd_dvm(a)[source]
Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.compute_cmds.cmd_settle(a)[source]
Parameters:

a (Namespace)

Return type:

int

class fleetmesh_node.commands.compute_cmds.ComputeCommandProvider[source]

Bases: object

Registers compute market, order book, DVM, settlement, and bridge commands.

classmethod register(sub)[source]
Parameters:

sub (_SubParsersAction)

Return type:

None

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.

fleetmesh_node.commands.gossip_cmds.cmd_gossip(a)[source]
Parameters:

a (Namespace)

Return type:

int

class fleetmesh_node.commands.gossip_cmds.GossipCommandProvider[source]

Bases: object

Registers the gossip topic commands.

classmethod register(sub)[source]
Parameters:

sub (_SubParsersAction)

Return type:

None

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.

fleetmesh_node.commands.sidecar_cmds.cmd_sidecars(a)[source]
Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.sidecar_cmds.cmd_manifest(a)[source]
Parameters:

a (Namespace)

Return type:

int

class fleetmesh_node.commands.sidecar_cmds.SidecarsCommandProvider[source]

Bases: object

Registers the sidecars commands.

classmethod register(sub)[source]
Parameters:

sub (_SubParsersAction)

Return type:

None

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.

Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.sync.cmd_subsystems(a)[source]

Every compartment of this node, side by side.

Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.sync.cmd_events(a)[source]

What the node’s bus carried lately, from memory; needs the daemon.

Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.sync.cmd_subscribe(a)[source]

Follow the node’s bus live: one line per event until interrupted.

Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.sync.cmd_refusals(a)[source]

Every no this node said, in one place.

Parameters:

a (Namespace)

Return type:

int

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.

Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.sync.cmd_scheduled(a)[source]

Every scheduled pull, when it last ran, and what is holding it back.

Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.sync.cmd_coverage(a)[source]
Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.sync.cmd_descriptor(a)[source]
Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.sync.cmd_pull(a)[source]
Parameters:

a (Namespace)

Return type:

int

class fleetmesh_node.commands.sync.SyncCommandProvider[source]

Bases: object

Registers sync, shard coverage, capacity, strain, and pull commands.

classmethod register(sub)[source]
Parameters:

sub (_SubParsersAction)

Return type:

None

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.ClusterFipsStatus[source]

Bases: TypedDict

active: bool
listeners: int
class fleetmesh_node.commands.cluster_cmds.ClusterNodeSummary[source]

Bases: TypedDict

index: int
name: str
pubkey: str
peers: list[Any]
event_count: int
face: str
class fleetmesh_node.commands.cluster_cmds.ClusterMeta[source]

Bases: TypedDict

node_count: int
topology: str
cluster_dir: str
running: bool
enable_fips: bool
relays: list[str]
class fleetmesh_node.commands.cluster_cmds.ClusterStatusSummary[source]

Bases: TypedDict

node_count: int
topology: str
cluster_dir: str
running: bool
active_peering_edges: int
relays: list[str]
fips: ClusterFipsStatus
nodes: list[ClusterNodeSummary]
fleetmesh_node.commands.cluster_cmds.cmd_cluster(args)[source]
Parameters:

args (Namespace)

Return type:

int

class fleetmesh_node.commands.cluster_cmds.ClusterCommandProvider[source]

Bases: object

Registers the local testnet cluster command.

classmethod register(sub)[source]
Parameters:

sub (_SubParsersAction)

Return type:

None

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.

class fleetmesh_node.commands.nsite_cmds.DomainsResponse[source]

Bases: TypedDict

domains: list[DomainBinding]
fleetmesh_node.commands.nsite_cmds.cmd_publish(a)[source]
Parameters:

a (Namespace)

Return type:

int

fleetmesh_node.commands.nsite_cmds.cmd_nsite(a)[source]
Parameters:

a (Namespace)

Return type:

int

class fleetmesh_node.commands.nsite_cmds.NsiteCommandProvider[source]

Bases: object

Registers the nsite (NIP-5A static site) commands.

classmethod register(sub)[source]
Parameters:

sub (_SubParsersAction)

Return type:

None

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.

class fleetmesh_node.commands.plugin_cmds.Declares[source]

Bases: TypedDict

builtin: bool
after: str
piuris: list[str]
sidecars: list[SidecarDict]
cli: list[str]
class fleetmesh_node.commands.plugin_cmds.Report[source]

Bases: TypedDict

ref: str
name: str | None
ok: bool
findings: list[str]
declares: Declares
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).

Parameters:

ref (str)

Return type:

Report

fleetmesh_node.commands.plugin_cmds.cmd_plugin_check(a)[source]
Parameters:

a (Namespace)

Return type:

int

class fleetmesh_node.commands.plugin_cmds.PluginCommandProvider[source]

Bases: object

Registers plugin-check.

classmethod register(sub)[source]
Parameters:

sub (_SubParsersAction)

Return type:

None