Manager Command Line Options

Reference for the command line options of the EVerest manager binary, the process that spawns and supervises all module processes. See Manager Lifecycle State Machine for what the manager does with them, and EVerest Configuration Service for how configuration is stored and loaded.

Note

Option abbreviation is disabled: every option must be spelled in full. --conf is therefore not accepted as a prefix of --config — it is a separate, deprecated option (see below).

Some options are marked experimental. Those are part of the public surface but exempt from the EVerest stability guarantees and the deprecation period: they may change incompatibly or be removed in any release. See Experimental Components for what that means, and Experimental Feature Index for the current list. The manager emits a warning at startup naming any experimental option it was given.

General

--version

Print version and exit.

--help, -h

Produce the help message.

--check

Validate the YAML config given via --config and exit. Exit code 0 means success. Requires --config: without it the manager exits with an error instead of validating the default config. The check needs no MQTT broker and neither reads nor seeds the configuration database.

--prefix <path>

Prefix path of the EVerest installation.

Configuration and Storage

--config <path>

Full path to a config file. If the file does not exist and has no extension, it is looked up in the default config directory. Optional: defaults to the default config file in the default config directory. Without --db, the config is loaded from YAML on every start and runtime configuration changes are persisted to the user-config file (see --user-config). Only YAML is accepted; configuration files in JSON format are not loaded. The settings: block of the config file is deprecated, use --settings instead.

--conf <path>

Deprecated. Same as --config. Do not use both — passing both is rejected as ambiguous, and using --conf logs a deprecation warning.

--user-config <path>

Full path to the user-config file. It is merged into the config file when the config is loaded and, without --db, receives the runtime configuration changes. Optional: defaults to user-config/<config-name>.yaml in the directory of the config file. The file may be absent and is then created on the first runtime change; its directory must exist. Requires --config. With --db, the user-config is merged only when the database boot slot is seeded from the YAML config.

--settings <path>

Full path to a manager settings file: installation paths, MQTT broker and prefixes, telemetry, schema validation and exception forwarding. Optional: without it, the deprecated settings: block of the config file applies, with built-in defaults for what it does not set. Works with and without --config and --db. When given, the settings: block of the config file is ignored and the manager logs a warning. The file is validated against schemas/settings.yaml; unknown and deprecated keys are rejected. Example files are installed as etc/everest/settings-*.yaml. See Manager Settings.

--db <path>

Full path to the configuration database file. Optional: without --db an in-memory database is used and the YAML config is authoritative on every start. With --db and --config, the database wins when its boot slot holds at least one module; a missing or module-less boot slot is seeded from the YAML config. An invalid YAML seeds an empty placeholder slot whose description records the error.

The database holds module configurations only, never manager settings. Pass --settings alongside --db whenever the deployment relies on non-default settings; without it, --db alone runs on the compiled-in defaults.

--reset-from-yaml

Experimental. Replace the contents of the boot slot with the YAML config file, even if it holds modules; aborts without touching the database if the YAML is invalid. Intended for development use when you want to reset to a known YAML state. Requires --config.

--db-init

Deprecated, no effect. Seeding the database from YAML when its boot slot holds no modules is now the default. Ignored unless both --config and --db are given. Use --reset-from-yaml to force re-seeding.

Management APIs

Both options start a management API inside the manager process, so it stays reachable while no modules are running. Each takes an optional value: ro (the default when the option is given without a value) or rw, as in --configuration-api=rw. Any other value is rejected and the manager exits with an error.

--configuration-api[=ro|rw]

Experimental. Start the configuration_API. In ro mode only queries are served; rw also enables managing configuration slots, loading YAML and changing configuration parameters.

--lifecycle-api[=ro|rw]

Experimental. Start the lifecycle_API. In ro mode only the module status and version queries are served; rw also enables requests to start and stop the modules.

Module Lifecycle

--standalone <module-id>..., -s <module-id>...

Module ID(s) to not automatically start child processes for. Those must be started manually to make the framework start. Accepts multiple values.

--ignore <module-id>...

Module ID(s) to ignore: do not automatically start child processes and do not require that they are started. Accepts multiple values.

--into-idle

Experimental. Boot into idle state — no modules are started. Also enters Idle instead of exiting when the configuration is invalid, missing or contains no modules.

--idle-on-failure

Experimental. When there is nothing startable — the boot configuration is invalid or contains no modules, crash recovery is exhausted with --recover-module-crashes, or a configuration reload fails during a module restart — keep the manager alive in Idle so the configuration API stays available. Default: exit with an error.

--recover-module-crashes

Experimental. After an unexpected module exit, reload the config and restart the modules, bounded by an internal retry limit. Default: shut down all modules and exit the manager.

--graceful-shutdown

Experimental. On shutdown, restart or crash, publish the shutdown signal via MQTT so modules can run their shutdown handlers, and force-terminate stragglers only after a timeout. Default: terminate module processes immediately with SIGTERM, escalating to SIGKILL.

Diagnostics and Debugging

--dump <dir>

Dump the validated and augmented main config and all used module manifests into the given directory.

--dumpmanifests <dir>

Dump the manifests of all modules into the given directory — including modules not used in the config — and exit.

--dontvalidateschema

Do not validate the JSON schema on every message.

--status-fifo <path>

Path to a named pipe that shall be used for status updates from the manager. Defaults to empty, which disables it. See Manager Lifecycle State Machine for the messages written to it.

--retain-topics

Retain the configuration MQTT topics set up by the manager, for inspection. By default these are cleared after startup.

--mqtt_everest_prefix <prefix>

Override the MQTT everest prefix. Useful for running multiple instances in parallel.