CLI Reference

Run, validate, reload, and probe Ferrum Edge v0.9.17. A subcommand is required.

Subcommands

Command	Purpose
`run`	Start the gateway
`validate`	Validate config and startup security without serving traffic
`reload`	Send SIGHUP to a gateway (Unix)
`health`	Probe readiness; add --live for liveness
`version`	Print version and build target
`ambient-udp-preflight`	One-shot privileged Ambient UDP node cleanup preflight, normally invoked by the mesh chart

Invoking ferrum-edge with no arguments prints usage and exits nonzero. Environment-based Docker, systemd, and shell startup must invoke ferrum-edge run.

run

Flag	Meaning
`--settings PATH` / `-s`	Operational settings (`ferrum.conf`)
`--spec PATH` / `-c`	Gateway resources YAML/JSON; a localized mesh document for file-protocol mesh validation
`--mode MODE` / `-m`	database, file, cp, dp, mesh, injector, node_agent, migrate
`--verbose` / `-v`	Repeat for info, debug, or trace
`--fips-mode MODE`	`off` or `enforce`; enforcement requires a FIPS build

bash

ferrum-edge run
ferrum-edge run --settings /etc/ferrum/ferrum.conf --spec /etc/ferrum/resources.yaml
ferrum-edge run --spec resources.yaml --mode file -vv
FERRUM_MODE=database ferrum-edge run

--spec supplies a path. File mode is inferred only when no CLI flag, environment variable, external secret source, or settings file selects a mode.

validate

Flag	Meaning
`--settings PATH` / `-s`	Operational settings (`ferrum.conf`)
`--spec PATH` / `-c`	Gateway resources YAML/JSON; a localized mesh document for file-protocol mesh validation
`--mode MODE` / `-m`	database, file, cp, dp, mesh, injector, node_agent, migrate
`--verbose` / `-v`	Repeat for info, debug, or trace
`--fips-mode MODE`	`off` or `enforce`; enforcement requires a FIPS build
`--allow-empty-namespace`	Allow namespaced resources to be entirely removed by the active namespace filter

Validation checks settings, external secrets, schema version, resource and plugin fields, route uniqueness, references, namespace filtering, and startup security. File-protocol mesh documents are supported with -m mesh. Exit status is 0 on success and 1 on failure.

bash

ferrum-edge validate --mode file --spec resources.yaml
ferrum-edge validate --settings ferrum.conf --spec resources.yaml
FERRUM_MESH_CONFIG_PROTOCOL=file ferrum-edge validate --mode mesh --spec mesh.yaml

Full gateway resource files require version: "1". Validation uses the same admission rules as runtime; it does not apply configuration.

reload

bash

ferrum-edge reload
ferrum-edge reload --pid 42195

Auto-detection selects one other ferrum-edge process; with multiple instances, supply --pid. SIGHUP reloads file mode and mesh with local file/xDS config. Other modes log and ignore it; use DB polling, CP push, or a restart.

health

bash

ferrum-edge health          # readiness: GET /health
ferrum-edge health --live   # liveness: GET /live
ferrum-edge health --settings /etc/ferrum/ferrum.conf
ferrum-edge health --host 127.0.0.1 --port 9000
ferrum-edge health --tls

Host and port are inferred from environment/settings unless overridden. TLS is selected automatically when plaintext admin is disabled. Exit status is 0 for HTTP 200 and 1 for an unsuccessful probe. Use readiness to remove unready nodes from service; liveness checks whether the process is alive.

yaml

livenessProbe:
  exec:
    command: ["/app/ferrum-edge", "health", "--live"]
readinessProbe:
  exec:
    command: ["/app/ferrum-edge", "health"]

The binary probe works with loopback-bound admin listeners and distroless images.

version

bash

ferrum-edge version
# ferrum-edge 0.9.17 (aarch64-apple-darwin)
ferrum-edge version --json
# {"version":"0.9.17","target":"aarch64-apple-darwin"}

ambient-udp-preflight

The mesh chart invokes this privileged init-container command before the Ambient proxy starts. Options include --settings, --timeout-seconds (default 300), --host-proc-root, and --verbose. Follow the preflight contract for host mounts and permissions.

Configuration Precedence

CLI flags
Environment variables, including resolved external-secret sources
Selected ferrum.conf
Smart path discovery
Built-in defaults

Settings discovery checks ./ferrum.conf, ./config/ferrum.conf, and /etc/ferrum/ferrum.conf. Resource discovery checks ./resources.yaml, ./resources.json, their ./config/ equivalents, then /etc/ferrum/config.yaml and /etc/ferrum/config.json.

Full v0.9.17 CLI reference · Running modes