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 .container units.

  • systemd: Hardened systemd .service and .timer unit 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