Edge Xpert Command Line Interface Tool

Edge Xpert provides a command line interface (CLI) tool, named edgexpert, which simplifies the management of the microservices.

The license associated with your download defines what microservices are available for use. For more information on licensing, see Licensing.

Using the edgexpert CLI Tool

The tool can be used by following this format:

edgexpert [–version | -v] <command> [<args>]


The commands used by edgexpert are described below, for information on the available Edge Xpert services, see Edge Xpert Services:

Parameter Arguments Description
--help or -h   Displays help on the edgexpert command
--version or -v   Displays the version, the repository and the Git-Sha of the installed Edge Xpert
pull [<options>] [<services>] Download the latest Edge Xpert images. Specifying no options pulls the core service images only. Specifying the --all option pulls updates for all images. Specifying one or more services pulls updates for the specified services only
up [<options>], [<services>] Creates and starts the Edge Xpert services. Starts core services by default. Specifying the --no-core option runs the up command without starting the core. Specifying the --no-consul option runs the up command without starting Consul. The services to create and start must be specified
start [<services>] Starts the stopped services. If no services are specified, starts all created services
restart [<services>] Restart the specified Edge Xpert services. If no services are specified, restarts all running services
run [<service>] [<args>] Creates and runs a one-off service with custom arguments
clean --force or -f Stops and deletes the running Edge Xpert services and removes all Edge Xpert volumes except the license volume
stop [<services>] Stops the Edge Xpert services. If no services are specified, stops all running services
down [<services>] Stops and deletes the running Edge Xpert containers. If no services are specified, stops and deletes all created services
rm [<services>] Deletes the stopped Edge Xpert services
status   Displays the current status of the created and/or running Edge Xpert services
ip   Displays the internet protocol (IP) addresses of the running Edge Xpert services
logs [<services>] -o <output_directory> Exports the logs from created and/or running Edge Xpert services to the specified directory. If no services are specified, outputs all logs to the specified directory
config [<options>] Specifying the validate option validates the current docker-compose configuration. Specifying the view option displays the current docker-compose configuration
license [<options>] Specifying the install option installs the specified licenses to the license volume. Specifying the uninstall option uninstalls the specified license. Specifying the view option lists all currently installed licenses. Specifying the check option validates all installed licenses. Specifying the clean option deletes the license volume; the license volume must not be mounted. For more information on licensing, see Licensing
images [<options>] Displays the versions or Git SHA from which each service was built. Specifying the version option displays the version information for each service. Specifying the sha option displays the SHA information for each service
docs [<options>] Starts, stops or updates the Edge Xpert docs container, or displays the status of the docs container. Specifying the up option starts the Edge Xpert documentation on localhost:8888. Specifying the down option stops and deletes the docs container. Specifying the update option pulls the latest docs container. Specifying status displays the current status of the edgexpert docs container

Edge Xpert Services

The following table describes the available services:

Services Description
--core-consul The default registry service, Consul. Consul provides health checks and service configuration options
--core-data The centralized persistence facility for data readings collected by devices and sensors
--core-metadata Stores and manages information about Device Services
--core-command Exposes the commands in a common, normalized way to simplify communications with the devices
--sys-mgmt The system management service. Currently not supported
--support-logging The logging service. Receives logs from all microservices with remote logging enabled
--support-scheduler The scheduling service. Allows for the creation of schedules to be run at regular intervals
--support-notifications The notification service. Allows for the creation of notifications and subscriptions
--export-distro The export distribution service. Attempts to send the encrypted JSON-formatted event or reading data to the client
--export-client The export client registration service. Registers clients as recipients of data coming from Core Data
--portainer Provides a detailed overview of your Docker environments and allows you to manage your containers, images, networks and volumes
--vault Provides secure, storage and control access to tokens, passwords, certificates and encryption keys for protecting secrets and other sensitive data using a UI, CLI, or HTTP API
--kong KONG is an open-source microservice API gateway and platform. Edge Xpert uses KONG as a component of the API gateway. See also --edgex-proxy
--edgex-proxy Initializes KONG , configures proxy routes, applies certificates to routes and enables authentication and Access Control List (ACL) features. For further information on the edgex-proxy options, see Kong
--xpert-manager The Edge Xpert Manager. Starts the Edge Xpert Manager, a user interface provided to support management and provisioning
--redis The Redis database
--influxdb The InfluxDB service runs an Influx database (DB) server. This can be used as an export target to power Grafana
--grafana Runs an instance of Grafana, a data visualization and monitoring platform
--nodered Runs an instance of Node-RED, a flow-based programming platform
--mqtt-broker An MQTT broker (Mosquitto) for use with Edge Xpert
--bacnet-server Runs an example BACnet server. This server is intended as an example target for the device-bacnet service
--gps-daemon Runs the GPS Daemon
--device-mqtt Runs the MQTT Device Service
--device-opc-ua Runs the OPC-UA Device Service
--device-bacnet Runs the configured BACnet Device Service, by default this is the BACnet/IP Device Service
--device-modbus Runs the Modbus Device Service
--device-virtual Runs the Virtual Device Service. This service is a source of random data and is set up to feed random data to Edge Xpert. This service is ideal for demonstration and testing
--device-grove Runs the Grove Device Service
--device-file Runs the File Device Service
--device-ethercat Runs the EtherCAT Device Service
--device-profinet Runs the PROFINET Device Service
--device-ble Runs the BLE Device Service
--device-gps Runs the GPS Device Service
--device-mems Runs the MEMS Device Service
--device-zigbee Runs the Zigbee Device Service


When the command acts on active containers, the -- is not required. For example, to restart the Alerts and Notifications container, use edgexpert restart support-notifications; but to create and start the Alerts and Notifications service, use edgexpert up --support-notifications.

Using the Tool

The edgexpert tool can be used to control Edge Xpert. The following topics describe common use cases.

Before you start using the commands, you must have the latest version of the Edge Xpert microservice images provided by IOTech. To get the latest version, open a terminal and enter the following command:

edgexpert pull --all

The output is similar to the following:

Pulling core-consul           ... done
Pulling redis                 ... done
Pulling sys-mgmt              ... done
Pulling support-logging       ... done
Pulling core-data             ... done
Pulling export-distro         ... done
Pulling export-client         ... done
Pulling core-metadata         ... done
Pulling support-scheduler     ... done
Pulling support-notifications ... done
Pulling core-command          ... done
Pulling xpert-manager         ... done
Pulling device-opc-ua         ... done
Pulling device-bacnet         ... done
Pulling device-virtual        ... done
Pulling device-modbus         ... done
Pulling device-grove          ... done
Pulling portainer             ... done
Pulling influxdb              ... done
Pulling grafana               ... done
Pulling nodered               ... done
Pulling mqtt-broker           ... done
Pulling device-mqtt           ... done
Pulling bacnet-server         ... done

You can also pull updates for a single image, for example:

edgexpert pull --device-virtual
Pulling device-virtual ... done


If you are updating the Edge Xpert Manager, you might need to clear the cache in your web browser and refresh the browser after the edgexpert pull --xpert-manager command to ensure that the latest version displays correctly.

Creating and Starting the Microservices

To create and start the microservices, use the up command.

The following example shows the output when creating and starting the services using the up command with the --xpert-manager and --device-virtual parameters:

edgexpert up --xpert-manager --device-virtual
Creating network "edgexpert_edgex-network" with driver "bridge"
Creating volume "edgexpert_db-data" with default driver
Creating volume "edgexpert_consul-data" with default driver
Creating volume "edgexpert_grafana-data" with default driver
Creating volume "edgexpert_nodered-data" with default driver
Creating volume "edgexpert_export-data" with default driver
Creating volume "edgexpert_portainer-data" with default driver
Creating edgex-redis       ... done
Creating edgex-core-consul   ... done
Creating edgex-core-metadata ... done
Creating edgex-core-data     ... done
Creating edgex-export-distro ... done
Creating edgex-core-command  ... done
Creating edgex-export-client  ... done
Creating edgex-device-virtual ... done
Creating xpert-manager        ... done

Creating and Starting a Single Microservice

The --no-core option starts only specified microservices.

The following example shows the output when creating and starting only the --nodered microservice:

edgexpert up --no-core --nodered
Creating edgex-nodered ... done

Verifying that the Microservices are Running

To verify that the microservices are running, use the status command.

The following example shows the terminal content when using the status command:

edgexpert status
      Name                      Command               State                                                                 Ports
edgex-core-command     /core-command --registry=t ...   Up>48082/tcp
edgex-core-consul      docker-entrypoint.sh agent ...   Up      8300/tcp, 8301/tcp, 8301/udp, 8302/tcp, 8302/udp,>8400/tcp,>8500/tcp,>8600/tcp, 8600/udp
edgex-core-data        /core-data --registry=true ...   Up>48080/tcp,>5563/tcp
edgex-core-metadata    /core-metadata --registry= ...   Up>48081/tcp
edgex-device-virtual   /device-virtual --profile= ...   Up>49990/tcp
edgex-export-client    /export-client --registry= ...   Up>48071/tcp
edgex-export-distro    /export-distro --registry= ...   Up>48070/tcp
edgex-redis            redis-server /etc/redis/re ...   Up>6379/tcp
xpert-manager          /root/go-ui-server               Up>8080/tcp

Stopping the Microservices

There are three key commands that can be used to stop, delete and clean an instance of Edge Xpert.

  • The stop command stops all the running Edge Xpert microservices. All containers remain

  • The down command stops all the running Edge Xpert microservices and deletes all containers

  • The clean command stops all the running Edge Xpert microservices, deletes all containers and deletes any volumes or networks used by Edge Xpert


    Deleting the volumes can cause a loss of configuration data, proceed carefully!

The following example shows the terminal content when using the clean command:

edgexpert clean
clean: delete all Edge Xpert data (y/n)? y
Stopping xpert-manager        ... done
Stopping edgex-device-virtual ... done
Stopping edgex-export-client  ... done
Stopping edgex-core-command   ... done
Stopping edgex-export-distro  ... done
Stopping edgex-core-data      ... done
Stopping edgex-core-metadata  ... done
Stopping edgex-core-consul    ... done
Stopping edgex-redis          ... done
Removing xpert-manager        ... done
Removing edgex-device-virtual ... done
Removing edgex-export-client  ... done
Removing edgex-core-command   ... done
Removing edgex-export-distro  ... done
Removing edgex-core-data      ... done
Removing edgex-core-metadata  ... done
Removing edgex-core-consul    ... done
Removing edgex-redis          ... done
Removing network edgexpert_edgex-network
Deleting Volumes:

Using a Custom docker-compose File

The edgexpert tool is driven by a docker-compose file located at /etc/edgexpert/docker-compose.yml.

If you want to make changes to this configuration, it is best practice to copy this file to a local directory. The local copy is used when running the edgexpert tool in a directory with a docker-compose.yml file. A message displays to indicate that a local file is being used, as shown in the following output:

Using local docker-compose

Command Line Help

In addition to this documentation, a summary of the options provided by the edgexpert tool can be shown by using the -h or --help parameters:

edgexpert --help
usage: edgexpert [--version | -v] <command> [<args>]

Edge Xpert Commands:

Manage and Update Services:
  pull     Download the latest Edge Xpert images
  up       Create and start Edge Xpert services
  down     Stop and delete running Edge Xpert services
  clean    Stop and delete running Edge Xpert services and remove volumes
  start    Start Edge Xpert services
  stop     Stop Edge Xpert services
  restart  Restart Edge Xpert services
  rm       Delete stopped Edge Xpert services

Monitor and Inspect Running Services:
  status   View the status of any created/running Edge Xpert services
  ip       View the ip addresses of the running Edge Xpert services
  logs     Export the logs from created/running Edge Xpert services

Manage Configuration and Licensing:
  config   View and validate the docker-compose configuration
  license  Validate license files and manage their use in Edge Xpert
  images   View information about the docker images
  docs     Access and update the Edge Xpert documentation

Further help is avaiable, 'edgexpert <command> -h' (or --help).

Help is also available for the individual parameters. For example, the following command displays the help for the license parameter:

edgexpert license -h
usage: edgexpert license [<options>] <path/file> [--force | -f]
  Manage your Edge Xpert licenses. Edge Xpert provides license files to its services via a docker volume

  install     install the specified license/s to the license volume
  uninstall   uninstall the specified license
  view        view all currently installed licenses
  check       check the validity all installed licenses
  clean       delete the license volume (volume must not be mounted)

Further help is avaiable, 'edgexpert <command> -h' (or --help).

Using Docker Commands

The EdgeX Foundry documentation describes the docker and docker-compose commands required to manage the services.

For further information on Docker, refer to the Docker documentation.

Using Edge Xpert

Once running, there are several ways in which you can configure and interact with Edge Xpert. For example, you can use a REST client to send and receive requests to and from the services. You can use either command line clients, such as cURL, or graphical client tools, such as Postman, to achieve this.

IOTech also provide a graphical tool, called Edge Xpert Manager, to support you further. Where possible, IOTech recommends that you use the Edge Xpert Manager tool. For more information on Edge Xpert Manager, see the Edge Xpert Manager topic.