everest-management-api-cli¶

everest-management-api-cli is a command line client for the management APIs of the EVerest manager: the lifecycle API (start and stop the modules, observe the module status) and the configuration API (manage configuration slots and parameters).

It is a small Python package living in applications/utils/everest-management-api-cli. Its client modules are also what the integration tests in tests/management_api_tests use to drive the APIs, so the tests cover the same code path as the command line. It offers an interactive shell that also prints status updates and configuration notices as they arrive, and every command can be run one-shot as well, which makes it usable from scripts.

For a hands-on walkthrough see the management APIs tutorial.

Install¶

Building EVerest with testing enabled (-DBUILD_TESTING=ON, see the Quick Start Guide) installs the client into the Python venv of the build directory, next to everest-testing:

cd build/
source ./venv/bin/activate
everest-management-api-cli --help

To install it into any other Python environment:

pip install -e applications/utils/everest-management-api-cli

The only dependencies are paho-mqtt and pyyaml.

Usage¶

The quickest way to explore the APIs is the interactive shell:

$ everest-management-api-cli shell
EVerest management API shell. Type 'help' for commands, 'quit' to leave.
Connected to 127.0.0.1:1883; watching everest_api/1/lifecycle/e2m/status,
everest_api/1/configuration/e2m/active_slot and everest_api/1/configuration/e2m/config_updates.
Status updates and notices are printed as they arrive.
everest-api> active
{
  "active_slot_id": 0,
  "next_boot_slot_id": 0
}
everest-api> mark 1
[active_slot] {"active_slot_id": 0, "next_boot_slot_id": 1, "status": "Running", "tstamp": "2026-09-02T17:24:10.937Z"}
{
  "result": "Success"
}

The shell keeps one connection open. Besides answering the commands typed at the prompt it prints lifecycle status updates and the active_slot / config_updates notices of the configuration API as [status], [active_slot] and [config_updates] lines the moment they arrive. Since the notices are not retained by the broker, start the shell before the manager to see the ones published at boot. help [COMMAND] shows the commands and their options, timeout [SECONDS] shows or sets the reply timeout, quit leaves the shell.

For scripts every command is also available as a one-shot invocation that connects, sends one request, prints the reply and exits:

everest-management-api-cli [--host HOST] [--port PORT] [--timeout SECONDS] [--compact] COMMAND ...

The broker defaults to 127.0.0.1:1883 or, if set, to the MQTT_SERVER_ADDRESS and MQTT_SERVER_PORT environment variables the manager itself uses. Replies are printed as JSON; --compact prints one line per reply, which is convenient for jq. The commands are the same in both modes:

Command	API request
`status [--all]`	Latest lifecycle status (the topic is retained, so this works whenever a manager has published one)
`version`	`get_everest_version`
`start` / `stop`	`start_modules` / `stop_modules`
`slots` / `active`	`list_all_slots` / `get_active_slot`
`mark SLOT` / `delete SLOT`	`mark_active_slot` / `delete_slot`
`dup SLOT [-d DESCRIPTION]`	`duplicate_slot`
`desc SLOT TEXT...`	`set_description`
`load FILE [-d DESCRIPTION] [--slot SLOT]`	`load_from_yaml` (a full config file is reduced to its `active_modules`)
`config SLOT [--db]`	`get_configuration`
`getp SLOT MODULE PARAMETER [--impl IMPL] [--db]`	`get_config_parameters` for one parameter
`getp SLOT --file FILE [--db]`	`get_config_parameters` for every parameter listed in the file
`setp SLOT MODULE PARAMETER VALUE [--impl IMPL]`	`set_config_parameters` for one parameter
`setp SLOT --file FILE`	`set_config_parameters` for every parameter in the file
`watch [--duration SECONDS]`	Print status updates and configuration notices as they arrive (the one-shot counterpart of the shell’s live output)
`raw API COMMAND [JSON]`	Send an arbitrary request, e.g. to test malformed payloads
`clear-retained-status`	Remove the retained last-will status of a killed manager from the broker

One-shot exit codes are 0 when a reply was received (a reply such as Rejected is a valid API answer), 1 on a timeout, connection failure or invalid local input, and 2 on usage errors.

Parameter files¶

setp --file and getp --file take a YAML file in the layout of a module configuration, reduced to the parameters of interest. getp ignores the values:

active_modules:
  example:                  # module id
    config_module:          # module-level parameters
      log_interval: 3
    config_implementation:
      example:              # implementation id
        current: 40