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 shareable 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==26.2.0

Pin ewx-cli to the version that matches the platform release you are working against — for platform release YY.MM the package version is YY.M.0. See Versioning for details. The example above targets platform release 26.02; replace the version to match your target release.

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 permissions needed for the configurations you intend to manage. The CLI checks your permissions before making any changes and only requires the permissions relevant to what you request — see Required permissions below.

Transient errors and retries​

API requests occasionally fail because of transient server-side issues — for example a gateway returning 502/503/504, or a connection being reset or timing out before the request reaches the backend. The CLI automatically retries these with an exponential backoff before giving up, so a brief hiccup on the platform side does not cause your command to fail. Non-transient errors such as 403 (permission denied) or 404 are reported immediately without retrying.

Identifying a namespace​

Most commands take a namespace in the form project/<value>. The <value> can be either:

  • the namespace ID (e.g. enrx_org_001), or
  • the namespace display name as shown in the console (e.g. automated_testing.dev).

For example, company-prd/enrx_org_001 and company-prd/automated_testing.dev refer to the same namespace if automated_testing.dev is the display name of enrx_org_001. The CLI resolves the name against the namespaces visible to your authenticated user. If two namespaces share a display name, the CLI prompts you to pick one (or, in non-interactive runs like CI, errors out and lists the candidate IDs).

You can also save commonly used namespaces under a short alias with ewx-cli namespace-alias set, see the readme for details.

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.

Uploading without dependencies​

Both config upload and config transfer accept a --no-deps (--no-dependencies) flag. With it, the CLI acts on only the configurations you explicitly request, without resolving their full dependency tree. This is useful during development when you want to push a single changed configuration without dragging in every related change.

How it behaves:

  • The CLI still reads the direct dependencies of the requested configurations on the destination so that references embedded in those configurations (for example, a market adapter's transformation configuration ID) can be remapped correctly. It does not walk the full dependency graph.
  • A configuration can be created (not just updated) with --no-deps, but only when all of its direct dependencies already exist on the destination — or are uploaded alongside it in the same command. If a direct dependency is missing on the destination, the reference could not be remapped, so the CLI aborts and lists the configurations whose dependencies are missing. For example, a market adapter can be created on a namespace that already has its transformation configuration, but not on one where that transformation configuration is absent.
  • Because dependencies are not created or updated, --no-deps needs far fewer permissions than a full upload (see Required permissions).

Required permissions​

Before making any changes, the CLI verifies that your user has the permissions required for the requested operation, and only asks for the permissions relevant to what you requested:

  • Read vs. write: read-only operations (download, verify, and reading the source of a transfer) require viewer; operations that write configurations (upload, and the destination of a transfer) require owner, because creating a configuration requires owner-level access.
  • Only the resources you request: when you request specific configurations (via the per-resource options or --resource-file), only the permissions for those resource types — and, in the default with-dependencies mode, their dependencies — are required. Requesting a whole namespace still requires the full set of configuration-management permissions.
  • With --no-deps: only the resources you explicitly request are checked, since their dependencies are neither created nor updated.

If a required permission is missing, the CLI stops before touching the destination and tells you which resource and permission level you need.

Upload labels: New, Update, Unchanged​

After a config upload or config transfer, the CLI prints an overview that marks each configuration with one of three labels:

  • (New) — the configuration did not exist on the destination and was created.
  • (Update) — the configuration already existed on the destination and was updated.
  • (Unchanged) — the configuration already existed on the destination and matched what you were uploading, so no API call was made.

The (Unchanged) label is only emitted for rules (both --rule and --transform-rule) today, where the CLI compares four fields between your local copy and the destination: displayName, description, codeBlob, and params. If all four match, the rule is reported as unchanged and skipped. Differences in any other field — for example, server-managed metadata like updatedAt — are ignored for the comparison.

Other resource types do not perform this comparison and are always reported as (New) or (Update).

Merge-aware namespace properties (market_adapters)​

A small number of namespace properties hold a JSON dictionary as their value. The market_adapters namespace property is one such case: its value maps each declared market adapter alias to its ID. When you config upload or config transfer such a property, the CLI merges the source value with whatever already exists on the destination instead of overwriting it:

  • New keys in your local config are added to the destination dict.
  • Keys already present on the destination are kept unless your local config also defines them.
  • If the source and destination both define the same key with a different value, the CLI prompts you to confirm before overwriting; declining aborts the upload, leaving the destination unchanged.

This protects against accidentally wiping market adapter mappings that other users or environments depend on.

If you actually want to replace the whole property — dropping any keys that exist on the destination but are not in your local config — pass --replace-namespace-property. This bypasses the merge and prompt and writes the source value verbatim:

$ ewx-cli config upload --namespace-property market_adapters --replace-namespace-property local_folder company-prd/enrx_org_001 $ ewx-cli config transfer --namespace-property market_adapters --replace-namespace-property company-prd/enrx_org_001 company-prd/enrx_org_002

The flag has no effect on namespace properties that are not merge-aware; those continue to use plain overwrite semantics.

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); to specific email addresses (e.g., user@energyworx.org) given on the command-line (--user); or to every user in a permission group on the destination namespace (--group). 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"

To transfer the same two dashboards to every member of the field_techs permission group on demo/enrx_org_001:

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

The --group option accepts either the group's name or its ID. The group is resolved on the destination namespace; user IDs that don't match an eligible user (e.g., service accounts or stale references) are skipped with a warning, and the command aborts if the group is missing, ambiguous, or has no eligible users. --group cannot be combined with --user or --user-file.

The same --group option is also available on ewx-cli config upload_dashboards for uploading a dashboard JSON file to every member of a permission group.

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