2. meshctl CLI Reference
This page provides a reference for all commands and options provided by the meshctl CLI tool.
2.1. Synopsis
meshctl [OPTIONS] <COMMAND>
2.1.1. Global Flags
-h, --help: Print help information.-V, --version: Print version information.
2.2. Commands
2.2.1. meshctl apply
Applies a declarative manifest with non-destructive hot-reconciliation against a running meshnode daemon or stages configuration to disk.
meshctl apply [OPTIONS] --file <PATH>
Options:
- -f, --file <PATH>: Path to the manifest file or directory containing YAML manifests.
- -d, --dir <PATH>: Path to the node data directory (default: /var/lib/fleetmesh).
- -s, --socket <PATH>: Explicit path to the meshnode-control/1 Unix domain socket.
- --dry-run: Simulate reconciliation and output the planned operations without applying changes.
Example:
# Apply a peering manifest with hot-reconciliation
meshctl apply -f manifests/peering-bristol.yaml
# Dry-run validation
meshctl apply -f manifests/peering-bristol.yaml --dry-run
2.2.2. meshctl diff
Compares declarative manifest specifications against the active daemon runtime state, reporting added, modified, or deleted fields.
meshctl diff [OPTIONS] --file <PATH>
Options:
- -f, --file <PATH>: Path to manifest file or directory.
- -d, --dir <PATH>: Path to node data directory.
- -s, --socket <PATH>: Path to control socket.
Example:
meshctl diff -f manifests/peering.yaml
2.2.3. meshctl export
Compiles declarative Fleetmesh manifests into native container, orchestrator, or init system templates.
meshctl export [OPTIONS] --file <PATH> --target <TARGET>
Options:
- -f, --file <PATH>: Path to input manifest.
- --target <TARGET>: Target platform identifier. Supported targets:
k8s: Kubernetes Deployment, Service, and ConfigMap resources.
quadlet: Rootless Podman Quadlet.containerunits.
systemd: Hardened systemd.serviceand.timerunit files.
compose: Docker Compose v3 cluster specification.
-o, --output <PATH>: Write rendered output to a file instead of stdout.
Example:
# Generate Kubernetes deployment bundle
meshctl export -f manifests/meshnode.yaml --target k8s -o k8s-meshnode.yaml
# Generate Podman Quadlet definition
meshctl export -f manifests/meshnode.yaml --target quadlet -o ~/.config/containers/systemd/node.container
2.2.4. meshctl status
Queries the active meshnode daemon via its local Unix control socket and displays health metrics, active peer counts, uptime, and identity DIDs.
meshctl status [OPTIONS]
Options:
- -d, --dir <PATH>: Path to node data directory.
- -s, --socket <PATH>: Explicit path to control socket.
Output Example:
=== Fleetmesh Node Status ===
Protocol : meshnode-control/1
Node DID : did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK
Uptime : 43210s
Active Peers : 14
Trouble / Refusals : 0
=============================
2.2.5. meshctl watch
Monitors the state of one or more Fleetmesh nodes across an entire fleet, reporting any errors, compartment faults, or protocol digest mismatches.
meshctl watch [OPTIONS] <NODE...>
Arguments:
- <NODE...>: One or more target nodes specified as local paths (e.g. /var/lib/fleetmesh) or remote SSH destinations (e.g. root@node-a.fleet:/var/lib/meshnode).
Options:
- --every <SECONDS>: Recurring check interval for daemon mode.
- --quiet: Suppress output when all nodes are healthy.
- --json: Emit structured JSON output suitable for automated alerting and ingestion.
Exit Codes:
- 0: All nodes healthy; no issues detected.
- 1: One or more nodes reported a fault, broken receipt, or protocol digest mismatch.
- 2: Node could not be reached via network or SSH.
2.2.6. meshctl linked
Outputs the schema.org JSON-LD projection of node resources, matching the data served over HTTP at /.well-known/fleetmesh/.
meshctl linked [OPTIONS] <WHAT>
Arguments:
- <WHAT>: Projection type: service, standing, or blob.
Options:
- --sha256 <HEX>: SHA-256 hash of the blob (required when <WHAT> is blob).
- -d, --dir <PATH>: Path to node data directory.
- -s, --socket <PATH>: Explicit control socket path.
Example:
meshctl linked service --dir /var/lib/fleetmesh | jq .
meshctl linked blob --sha256 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
2.2.7. meshctl conform
Speaks the Fleetmesh conformance wire protocol over standard I/O (JSON lines in, JSON lines out) to validate store mechanisms against canonical test vectors.
python3 scripts/conform.py -- meshctl conform
2.2.8. meshctl convert
Automates the migration of legacy meshstr.org/v1alpha1 manifests to the normative fleetmesh.org/v1alpha1 schema.
meshctl convert -f old-peering.yaml -o new-peering.yaml