​

Prerequisites

• Have a Heex CLI
• Have a USER_SECRET_KEY. Should be accessible in your personnal space on the heex cloud platform.

​

Usage

./heex system SUBCOMMAND [--help]

​

How to add a system’s secret key to the credentials file

Usage:

./heex system add-credentials --api-key <USER_SECRET_KEY> --system-id <SYSTEM_ID>

This command will fetch the system secret key and add it to the credentials file. The credentials file is required for the Kernel to work properly. This is required in case you create a new system via the Cloud Platform. If you create a new system via the CLI or the heex-installer, you can skip this step.

Available flags are:

• --api-key: The api secret key, it is required only if --system-key is not defined.
• --system-key: The system’s secret key, it is required only if --api-key is not defined.
• --system-id: The system id to fetch the secret key for, it is required only if --systemconf-file is not defined.
• --systemconf-file: The path to the system configuration file, it is required only if --system-id is not defined.

​

How to create a new system

2 different ways to create a new system on the cloud, both using the command new:

• [Recommended]: create a system only by name and some optional flags:
  • --name: Must be unique on your cloud workspace.
  • --description: Description for your system.
  • --middleware: System middleware. Check help for available middleware.
  • --system-category: System category. Check help for available templates.

Usage:

./heex system new --api-key <USER_SECRET_KEY> --name "Jane's system" --description "Optional description" --middleware 1 --system-category 1

This will create the new system on the Heex Cloud. You can later access this created system via the cloud platform and modify it there (i.e add implementations)

• [Advanced]: Another way to create a system is to use a configuration file that contains all the data you want to generate. This is still a beta feature under progress, so it is not recommended, but if you want to use it:
  • you can generate a template file using the ./heex system create-template-file command, and then fill the given file as you need.
  • Once it is filled, use the create subcommand with the --input-file input pointing to the filled file

Usage:

./heex system new --api-key <USER_SECRET_KEY> --input-file /path/to/your/filledConfigFile.json

​

How to get system details

You can retrieve the system details using the command get, which will retrieve system details for a given system ID in the specified output format. The system ID can be found on the web platform. Flags available are:

• --output-file: Provide a path if you want the conf to be saved in a file (add filename.json in your path). The conf will also always be provided in terminal..
• --system-id: The id of the system to retrieve.

Usage:

./heex system get --api-key <USER_SECRET_KEY> --system-id <SYSTEM_ID> --output-file path/to/your/filledConfigFile.json

⚠️ Warning:

system name or description with special characters If your system name or description contains special characters (i.e ’ or space), please use double quotes before and after your names.

For example, for a system called Jane’s system, provide that as —name “Jane’s system”.

​

How to get system status

You can retrieve the status of a system using the command status. This command will retrieve the status of a given system ID in the specified output format. Information that will be provided is:

• Agent version
• Last OTA update
• System status
• Implementation status

Usage:

./heex system status --api-key <USER_SECRET_KEY> --system-id <SYSTEM_ID> --output-file path/to/your/filledConfigFile.json

​

Getting Help

./heex system --help
./heex add-credentials --help
./heex system get --help
./heex system new --help
./heex system status --help
./heex system create-template-file --help