Skip to main content

ewx-cli

In this article, we will explain three example usecases of the ewx-cli:

A. You want to transfer configurations from one namespace to the other (e.g., from develop to test)
B. You want download configurations to store them, for example, on a git repository, or upload them.
C. Transferring dashboards from one namespace to the other, or one user to the other.

There are also other functionalities in ewx-cli. Read the readme, or use the help function in the program to learn more about them.

First-time usage​

Accessing the package from Artifact Registry

The package is hosted in our Artifact Registry, where we store our sharable packages. To access it, you will need a Google Account with access to our Registry. Ask Service Desk to be given those permissions. Once the permissions are granted you can download the ewx-cli package following the instructions below.

Configure your environment and install the package:

Follow these instructions carefully to set up your local environment and install the ewx-cli plugin:

mkdir my_ewx_cli  
cd my_ewx_cli  
python3.13 -m venv .venv_my_ewx_cli  
source .venv_my_ewx_cli/bin/activate  
pip install keyring keyrings.google-artifactregistry-auth  
pip install --index-url https://europe-west1-python.pkg.dev/ewx-global/python-shared/simple/ --extra-index-url https://pypi.org/simple/ ewx-cli==2.11.0

Note that the version of the plugin at the time of writing is 2.11.0, please contact the Service Desk asking for the latest version available. ewx-cli is currently compatible for python versions between 3.10 and 3.14.

Authentication with the platform​

Upon using the CLI against a specific project for the first time, you will be prompted to set up OAuth2 credentials. The CLI will provide a URL and instruct you to open it in your browser.

  1. Open the provided URL. This will take you to the User Settings page in the Console.
  2. Generate new API credentials on that page.
  3. Copy the Client ID and Client Secret.
  4. Paste them back into the CLI when prompted.

The CLI will then complete authentication and store the credentials. It will automatically handle token refreshes until the credentials expire, at which point you will be prompted to repeat this process.

To check if an environment has been authenticated or still needs authentication, run ewx-cli check-project <platform-prefix>/<project-id>. Where <platform-prefix> is the part of your platform website that precedes .energyworx.net (e.g., company-prd if your URL is company-prd.energyworx.net).

Please make sure you have the needed permissions, like permissions for CRUD (Copy, Read, Update, Delete) operations on all the different configs.

Transferring configurations from one namespace to the other​

  1. Identify the namespace ID's you want to transfer between. For example, from “enrx_org_001” (develop) to “enrx_org_002” (test).
  2. Identify your project ID (it's the same as the subdomain for your energyworx console). For example, “company-prd”.
  3. In a command line interface, execute $ ewx-cli config transfer company-prd/enrx_org_001 company-prd/enrx_org_002
  4. Review the configurations that are found and if you want to continue, type y
  5. If you only want to transfer some configurations, you need to specify them. For example, with
    $ ewx-cli config transfer company-prd/enrx_org_001 company-prd/enrx_org_002 --transformation-configuration 6444763028914176 --channel-classifier POWER_INT15T we only transfer one specific transformation configuration and channel classifier, including any configuration dependencies.

Downloading and uploading configurations​

  1. Identify the namespace ID's you want to transfer between. For example, from “enrx_org_001” (develop) to “enrx_org_002” (test).
  2. Identify your project ID (it's the same as the subdomain for your energyworx console). For example, “company-prd”.
  3. In a command line interface, execute $ ewx-cli config download company-prd/enrx_org_001 company-prd/enrx_org_002 local_folder to download into a new directory called local_folder, from which the configurations can be stored anywhere, including a git repository.
  4. Like in A, you can select the specific configurations to download. You can also upload from a directory with $ ewx-cli config upload company-prd/enrx_org_001 local_folder company-prd/enrx_org_002. Making a selection while uploading is not possible, so remove any configurations from the folder if you do not want to upload them.

Transferring dashboards from one namespace to the other, or from one user to another​

The config dashboards command allows for dashboards to be transferred between users on either the same namespace or separate namespaces. As dashboards are stored per user, not per namespace, this functionality has its own command instead of being covered. Type ewx-cli config dashboards --help for more information about this command.

One or multiple dashboards (given by their names with the DASHBOARD_NAMES argument) can be transferred from a single user to all users on a namespace (no options given); to all users with the email addresses given in a file (--user_file); or to specific email addresses (e.g., user@energyworx.org) given on the command-line (--user). So, for example, you can use the following line to transfer two specific dashboards to all other users on the same namespace:

$ ewx-cli config dashboards demo/enrx_org_001 user@energyworx.org "Dashboard_1" "Dashboard_2"

If a target user already has a dashboard with the same name, you will be asked if it is okay to update that dashboard. It is also possible that a user has no dashboards at all (or no user properties). In such cases, this command will also take care of setting up their user properties in such a way that dashboards can be added.

The user needs to refresh the dashboard page (or logout/login again).

EWX-CLI help command​

The EWX-CLI is quite helpful when it comes down to usage. If you are in doubt on how to use the ewx-cli, you can execute ewx-cli --help to get some more documentation, including commands and arguments. This also works on commands. For example, if you want to get more info about upload, execute ewx-cli config upload --help