meshctl CLI Reference ===================== This page provides a reference for all commands and options provided by the `meshctl` CLI tool. Synopsis -------- .. code-block:: text meshctl [OPTIONS] Global Flags ^^^^^^^^^^^^ - ``-h, --help``: Print help information. - ``-V, --version``: Print version information. Commands -------- meshctl apply ^^^^^^^^^^^^^ Applies a declarative manifest with non-destructive hot-reconciliation against a running ``meshnode`` daemon or stages configuration to disk. .. code-block:: text meshctl apply [OPTIONS] --file Options: - ``-f, --file ``: Path to the manifest file or directory containing YAML manifests. - ``-d, --dir ``: Path to the node data directory (default: ``/var/lib/fleetmesh``). - ``-s, --socket ``: Explicit path to the ``meshnode-control/1`` Unix domain socket. - ``--dry-run``: Simulate reconciliation and output the planned operations without applying changes. Example: .. code-block:: sh # 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 meshctl diff ^^^^^^^^^^^^ Compares declarative manifest specifications against the active daemon runtime state, reporting added, modified, or deleted fields. .. code-block:: text meshctl diff [OPTIONS] --file Options: - ``-f, --file ``: Path to manifest file or directory. - ``-d, --dir ``: Path to node data directory. - ``-s, --socket ``: Path to control socket. Example: .. code-block:: sh meshctl diff -f manifests/peering.yaml meshctl export ^^^^^^^^^^^^^^ Compiles declarative Fleetmesh manifests into native container, orchestrator, or init system templates. .. code-block:: text meshctl export [OPTIONS] --file --target Options: - ``-f, --file ``: Path to input manifest. - ``--target ``: Target platform identifier. Supported targets: - ``k8s``: Kubernetes Deployment, Service, and ConfigMap resources. - ``quadlet``: Rootless Podman Quadlet ``.container`` units. - ``systemd``: Hardened systemd ``.service`` and ``.timer`` unit files. - ``compose``: Docker Compose v3 cluster specification. - ``-o, --output ``: Write rendered output to a file instead of stdout. Example: .. code-block:: sh # 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 meshctl status ^^^^^^^^^^^^^^ Queries the active ``meshnode`` daemon via its local Unix control socket and displays health metrics, active peer counts, uptime, and identity DIDs. .. code-block:: text meshctl status [OPTIONS] Options: - ``-d, --dir ``: Path to node data directory. - ``-s, --socket ``: Explicit path to control socket. Output Example: .. code-block:: text === Fleetmesh Node Status === Protocol : meshnode-control/1 Node DID : did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK Uptime : 43210s Active Peers : 14 Trouble / Refusals : 0 ============================= meshctl watch ^^^^^^^^^^^^^ Monitors the state of one or more Fleetmesh nodes across an entire fleet, reporting any errors, compartment faults, or protocol digest mismatches. .. code-block:: text meshctl watch [OPTIONS] Arguments: - ````: 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 ``: 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. meshctl linked ^^^^^^^^^^^^^^ Outputs the schema.org JSON-LD projection of node resources, matching the data served over HTTP at ``/.well-known/fleetmesh/``. .. code-block:: text meshctl linked [OPTIONS] Arguments: - ````: Projection type: ``service``, ``standing``, or ``blob``. Options: - ``--sha256 ``: SHA-256 hash of the blob (required when ```` is ``blob``). - ``-d, --dir ``: Path to node data directory. - ``-s, --socket ``: Explicit control socket path. Example: .. code-block:: sh meshctl linked service --dir /var/lib/fleetmesh | jq . meshctl linked blob --sha256 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 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. .. code-block:: sh python3 scripts/conform.py -- meshctl conform meshctl convert ^^^^^^^^^^^^^^^ Automates the migration of legacy ``meshstr.org/v1alpha1`` manifests to the normative ``fleetmesh.org/v1alpha1`` schema. .. code-block:: sh meshctl convert -f old-peering.yaml -o new-peering.yaml