Authentication, projects and namespaces
Authentication
The first time you run a command against a project, the CLI asks you to set up client credentials:
- Open the URL the CLI prints. It leads to Settings → Automated access in the console.
- Create a new credentials pair with a recognizable display name.
- Copy the client ID and client secret and paste them into the CLI when prompted.
The CLI stores the credentials and refreshes tokens automatically until the pair expires, then asks again. Credentials are per project, not per namespace. See Automated API Access for what the pair can do and how to bind it to a service account.
To see whether a project is already authenticated:
ewx-cli check-project company-prd
company-prd is the project prefix: the part of your console URL before .energyworx.net.
The CLI checks your permissions before it changes anything and only asks for the permissions the requested operation needs, see Required permissions.
Identifying a namespace
Most commands take a namespace as project/<value>, where <value> is either the namespace ID (enrx_org_001) or the display name shown in the console (automated_testing.dev). Both of these address the same namespace if that is its display name:
company-prd/enrx_org_001
company-prd/automated_testing.dev
The CLI resolves names against the namespaces your user can see. Raw IDs pass through unchanged. If two namespaces share a display name it prompts you to pick one, or in a non-interactive run such as CI errors out and lists the candidates. Display names containing whitespace are not accepted. A value that matches neither an ID nor a name is forwarded as is, so administrators and service accounts can reach namespaces that are not listed for them.
Aliases
Long namespace strings and nested commands can be shortened.
Namespace aliases work everywhere a namespace is expected:
ewx-cli namespace-alias set prd company-prd/enrx_org_001
ewx-cli config download prd ./configs
ewx-cli namespace-alias list
Project aliases do the same for a project prefix (ewx-cli project-alias set), and command aliases shorten a command path, defined from the root command:
ewx-cli command-alias set up "config upload"
ewx-cli up ./configs prd
Each alias group has set, get, list, delete and delete-all, plus get-namespace, get-project or get-command to look up the aliases of a value.
Configuration file
Settings live in configuration.ini, created with defaults on first use:
| OS | Location |
|---|---|
| Linux, macOS | ~/.config/ewx-cli/configuration.ini |
| Windows | %APPDATA%\ewx-cli\configuration.ini |
By default the CLI derives the API host from the project prefix (https://ah.ewx-<project>.ewxapis.com). Projects with a different host get an entry in the [project_urls] section:
[project_urls]
my-project = https://ah.ewx-my-project-production.ewxapis.com
Logging and retries
The default log level is WARNING. Pass -v to see progress, which is useful during long config operations.
Transient API errors such as 502, 503, 504, connection resets and timeouts are retried with exponential backoff before the command fails. Non-transient errors such as 403 (permission denied) and 404 are reported immediately.
Shell completion
Completion scripts for bash, zsh and fish ship in the package's completions/ directory. For bash, add this line to ~/.bashrc, adjusting the path to where the package is installed:
. <path-to-ewx-cli>/completions/_ewx-cli.bash
Scripting with the CLI
For one-off requests without a dedicated command, ewx-cli ipython opens an IPython session with create_client() for any project and the Manager class that powers ewx-cli config. The Manager caches API results, so long interactive sessions are faster than repeated commands. Namespace aliases work here too.