CLI Reference

Subcommands

Invoking ferrum-edge with no arguments uses the existing environment-variable-only startup path, keeping every existing deployment (Docker, systemd, CI) working unchanged.

run

Start the gateway in the foreground. This is the primary command for both development and production use.

ferrum-edge run [OPTIONS]

Options

Examples

# Zero-config start (uses ./ferrum.conf and ./resources.yaml if present)
ferrum-edge run

# Explicit settings and spec paths
ferrum-edge run --settings /etc/ferrum/ferrum.conf --spec /etc/ferrum/resources.yaml

# Short flags
ferrum-edge run -s ferrum.conf -c resources.yaml

# Override mode and enable debug logging
ferrum-edge run --spec resources.yaml --mode file -vv

# Database mode with verbose logging
ferrum-edge run --settings ferrum.conf --mode database -v

validate

Parse and validate configuration files without starting the gateway. Exits with code 0 on success, 1 on failure. Ideal for CI/CD pre-deploy checks.

ferrum-edge validate [OPTIONS]

Options

What is validated

• Settings (ferrum.conf) — all 90+ environment variables are parsed and validated (ports, paths, TLS configuration, pool sizes, etc.)
• Spec (resources YAML/JSON, file mode only):
  • YAML/JSON syntax and deserialization
  • Field-level validation on all proxies, consumers, upstreams, and plugin configs
  • Regex listen_path compilation and uniqueness enforcement
  • Stream proxy port conflict detection against gateway reserved ports
  • Plugin config validation (each plugin is instantiated to verify its config)
  • TLS certificate path existence checks
  • Upstream reference validation

Examples

# Validate a spec file
ferrum-edge validate --spec resources.yaml

# Validate with explicit settings
ferrum-edge validate --settings /etc/ferrum/ferrum.conf --spec /etc/ferrum/resources.yaml

# Use in CI/CD pipeline
ferrum-edge validate --spec resources.yaml || exit 1

Sample Output

Settings (ferrum.conf): OK
  Mode: File
Spec (/etc/ferrum/resources.yaml): OK
  Proxies: 12
  Consumers: 5
  Upstreams: 3
  Plugin configs: 18

Validation passed.

Settings (ferrum.conf): OK
  Mode: File
Error: Spec validation failed: Configuration file not found: /nonexistent.yaml

reload

Send SIGHUP to a running gateway instance to trigger a hot config reload. Only supported on Unix platforms (Linux, macOS, BSDs). In file mode, SIGHUP causes the gateway to re-parse the spec file and atomically swap the config without dropping connections.

ferrum-edge reload [OPTIONS]

Options

Examples

# Auto-detect PID and reload
ferrum-edge reload

# Explicit PID
ferrum-edge reload --pid 42195

version

Print version and build target information.

ferrum-edge version [OPTIONS]

Options

$ ferrum-edge version
ferrum-edge x.y.z (aarch64-apple-darwin)

$ ferrum-edge version --json
{"version":"x.y.z","target":"aarch64-apple-darwin"}

Configuration Precedence

When using CLI subcommands, the configuration resolution order is (highest precedence first):

1. CLI flag — --settings, --spec, --mode, --verbose
2. Environment variable — FERRUM_CONF_PATH, FERRUM_FILE_CONFIG_PATH, FERRUM_MODE, FERRUM_LOG_LEVEL
3. Conf file value — ferrum.conf
4. Smart path defaults — well-known file locations (see below)
5. Hardcoded defaults

Smart Path Defaults

When --settings or --spec are omitted and the corresponding env var is not set, the CLI searches well-known locations in order:

Settings (ferrum.conf)

Spec (resources file)

The first file that exists is used. Absolute paths are used as-is; relative paths are resolved from the current working directory.

Backwards Compatibility

The CLI is fully backwards compatible with existing deployments. Docker, systemd, and CI/CD scripts that set env vars and invoke ferrum-edge with no arguments continue to work without modification.