​
Prerequisites

  • Have a Heex CLI
  • Have a USER_SECRET_KEY. Should be accessible in your personnal space on the heex cloud platform. If you already logged-in you don’t need to add the Api-Key in your command line.

​
Usage

SubcommandDescription
add-credentialsAdd a system’s secret key to the credentials file.
connectivityChange the connectivity mode of a system.
createCreate a new system on the cloud.
create-template-fileAdvanced usage: creates a template file for system creation configuration.
getRetrieve system details for a given ID.
get-sys-confRetrieve system configuration for a given ID.
listList all systems.
statusProvides the status of the system.
todo-listProvides systems todo list for a given workspace.
updateUpdate a system on the cloud.
deleteDelete a system with a given ID.
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 --config-path is not defined.
  • --config-path: The path to the system configuration file (.json format), it is required only if --system-id is not defined.

​
How to change connectivity mode of a system

To change connectivity mode of the system, you can use the following command: Usage: 
./heex system connectivity --api-key <USER_SECRET_KEY> --system-id <SYSTEM_ID> --mode <MODE>
All options provided in the example are mandatory. Check help to see possible values for the --mode.

​
How to create a new system

2 different ways to create a new system on the cloud, both using the command create:
  • Create a system only by name and some optional flags:
    • --name: Must be unique on your cloud workspace.
    • --description: Description for your system.
    • --system-middleware: System middleware. Check help for available middleware.
    • --system-category: System category. Check help for available templates.
    • --operating_system: Operating system. Defaults to the OS of user executing the command. Check help for available templates.
Usage: 
./heex system create --api-key <USER_SECRET_KEY> --name "Jane's system" --description "Optional description" --system-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)
  • Another way to create a system is to use a configuration file that contains all the data you want to generate. 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
    • Note that fields name and type are required, everything else can be removed.
  • Note that whichever way you chose to create your system, you can add the option --output-file which will save the created data info into a file. You’ll have to provide a filepath with a json extension: /path/to/file.json
  • If you provide --json-output, it will disable all logging (except errors), and your command shall only output the result in a json format. Be aware that it is not compatible with ‘—output-file’ option.
Usage: 
./heex system create --api-key <USER_SECRET_KEY> --input-file /path/to/your/createSystemFilled.json --output-file /path/to/createdSystem.json

​
How to update a system

You can update a system by using a json file. Flags to update a system are --input-file and --system-id which are both required. You can generate a template file using the command below: Usage: 
./heex system create-template-file --type update --folder-path <FOLDER_PATH>
Here’s an example of the template file that shows which values can be updated, you can fill it as you need and remove what you don’t need: 
{
  "systems": [
    {
      "operating_system": "UBUNTU_22_04_LTS_X86_64",
      "__comment_operating_system": "Possible values: ['UBUNTU_20_04_LTS_X86_64', 'UBUNTU_20_04_LTS_ARM', 'UBUNTU_22_04_LTS_X86_64', 'UBUNTU_22_04_LTS_ARM', 'UBUNTU_24_04_LTS_X86_64', 'UBUNTU_24_04_LTS_ARM']",
      "labels": [
        {
          "source": "SYSTEM",
          "key": "",
          "value": ""
        }
      ],
      "triggers": [
        {
          "trigger_id": ""
        }
      ],
      "signals": [
        {
          "signal_id": "",
          "implementation_id": ""
        }
      ],
      "name": "",
      "description": "",
      "middleware": "MIDDLEWARE_TYPE_UNSPECIFIED",
      "__comment_middleware": "Possible values: ['MIDDLEWARE_TYPE_UNSPECIFIED', 'ROS2', 'OTHER']",
      "type": "SYSTEM_TYPE_UNSPECIFIED",
      "__comment_type": "Possible values: ['AUTONOMOUS_MOBILITY_ROBOTS', 'OPEN_ROAD_ADAS_AD', 'SEA', 'AERIAL', 'RAIL', 'LINEAR_INFRASTRUCTURE', 'BUILDINGS_FIXED_STRUCTURES', 'CLOUD_ON_PREMISE_DEVICES', 'DEV_STATION']"
    }
  ]
}
Usage: 
./heex system update --api-key <USER_SECRET_KEY>  --system-id <SYSTEM_ID> --input-file /path/to/updateSystemFilled.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 or by using command ./heex system list --api-key <USER_SECRET_KEY> [OPTIONAL-FILTERS]. Flags available are:
  • --output-file: Provide a path if you want system details to be saved in a file (add filename.json in your path).
  • --json-output: Disables all logging (except errors), and your command shall only output the result in a json format. It is not compatible with ‘—output-file’ option.
  • --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/systemDetails.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 configuration

You can retrieve the system configuration using the command get-sys-conf, which will retrieve system configuration for a given system ID in the specified output format. Options are the same as get command. See the usage example below: Usage: 
./heex system get-sys-conf --api-key <USER_SECRET_KEY> --system-id <SYSTEM_ID> --output-file path/to/your/sysConf.json

​
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
  • Signal details
Usage: 
./heex system status --api-key <USER_SECRET_KEY> --system-id <SYSTEM_ID> --output-file path/to/your/filledConfigFile.json

​
How to get system to-do list for a given ID

You can retrieve the to-do list of systems for a given workspace with the corresponding status using the command todo-list. You can filter the result by providing a system ID and/or system status. If a system status is given, for example , --system-status TO_CODE, only systems with the given status will be returned and you’ll be able to see the list of systems that need to be coded yet. Available flags are:
  • --api-key: The api secret key: USER_SECRET_KEY.
  • --system-id: ID of the involved system. Multiple can be provided, example: —system-id sysId1 —system-id sysId2
  • --system-status: The status of the system to retrieve. Check help for available status.
  • --details: Show details of each system implementations status included.
  • --output-file: Provide a path if you want the output to be saved in a file.
  • --json-output: Disables all logging (except errors), and your command shall only output the result in a json format. It is not compatible with ‘—output-file’ option.
If --details is provided, the output will be a list of systems including their signal details. Otherwise, it will display only system id, status and agent version when available. Usage: 
./heex system todo-list --api-key <USER_SECRET_KEY> --system-id <SYSTEM_ID>  --system-status <SYSTEM_STATUS> --output-file path/to/your/systemsToDoList.json

​
How to get list of systems with details for a given workspace

You can retrieve the list of systems for a given workspace with the corresponding status using the command list. Same as for todo-list, you can filter the result by providing a system ID and/or system status. The result will be a list of systems with details. Available flags are:
  • --api-key: The api secret key: USER_SECRET_KEY.
  • --system-id: ID of the involved system. Multiple can be provided, example: —system-id sysId1 —system-id sysId2
  • --system-status: The status of the system to retrieve. Check help for available status.
  • --output-file: Provide a path if you want the output to be saved in a file.
  • --json-output: Disables all logging (except errors), and your command shall only output the result in a json format. It is not compatible with ‘—output-file’ option.
Usage: 
./heex system list --api-key <USER_SECRET_KEY> --system-id <SYSTEM_ID>  --system-status <SYSTEM_STATUS> --output-file path/to/your/systemsList.json

​
How to delete a system

To be able to delete a system you need to provide a system-id and use the command below: Usage: 
./heex systems delete --api-key <USER_SECRET_KEY> --system-id <SYSTEM_ID>

## Getting Help

```bash
./heex system --help
./heex add-credentials --help
./heex connectivity --help
./heex create --help
./heex create-template-file  --help
./heex system get --help
./heex system get-sys-conf --help
./heex system list --help
./heex system status --help
./heex system todo-list --help
./heex system update --help
./heex system delete --help