epx

epx is a command-line client for the Emporix Commerce APIs. It helps you read, script, and change the data of an Emporix tenant right from the terminal.

Documentation: commerce-cloud-integrations.github.io/emporix-cli covers installation, authentication, every command, and the Emporix API coverage.

With epx, you can:

• Read products, categories, catalogs, prices, availability, customers, orders, and nearly every other Emporix resource as a table, CSV, JSON, YAML, or JSON Lines.
• Filter, sort, and page through any list without writing paging code.
• Change data safely: every write shows its exact request with --dry-run and asks before it sends.
• Call any Emporix API endpoint with epx api, using only the OAuth scopes you name.
• Script reliably with stable output and exit codes that tell a missing item from a missing scope.

epx is an unofficial project. It isn't affiliated with or endorsed by Emporix.

Installation

epx is a single binary for macOS, Linux, and Windows, on x64 (amd64) and arm64.

Install script

On macOS or Linux:

curl -fsSL https://github.com/commerce-cloud-integrations/emporix-cli/releases/latest/download/install.sh | sh

On Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://github.com/commerce-cloud-integrations/emporix-cli/releases/latest/download/install.ps1 | iex"

The script downloads the latest release for your platform, checks it against the release's checksums and installs epx into ~/.local/bin (on Windows %LOCALAPPDATA%\Programs\epx\bin) without sudo, adding that directory to your PATH if needed. On macOS and Linux, it installs the man pages into ~/.local/share/man/man1. Set EPX_VERSION (such as v0.3.0) to pin a release, EPX_INSTALL_DIR to choose the directory, or EPX_NO_MODIFY_PATH=1 to leave your shell profile alone.

Homebrew

On macOS or Linux:

brew install commerce-cloud-integrations/tap/epx

Homebrew installs the binary, the man pages and shell completion for bash, zsh and fish.

Scoop

On Windows, in PowerShell:

scoop bucket add commerce-cloud-integrations https://github.com/commerce-cloud-integrations/scoop-bucket
scoop install commerce-cloud-integrations/epx

npm

With Node.js 18 or later:

npm install --global @commercecloudintegrations/epx-cli

npm installs only the binary of your platform. Nothing is compiled and no install script runs. To run epx once without installing it:

npx @commercecloudintegrations/epx-cli version

Release archive

Each release holds an archive per platform and a checksums file. For example, on Linux x64:

version=v0.3.0
base=https://github.com/commerce-cloud-integrations/emporix-cli/releases/download/$version
curl -fsSLO "$base/epx_${version}_linux_amd64.tar.gz" &&
  curl -fsSLO "$base/epx_${version}_checksums.txt" &&
  sha256sum --check --ignore-missing "epx_${version}_checksums.txt" &&
  tar -xzf "epx_${version}_linux_amd64.tar.gz" &&
  sudo install "epx_${version}_linux_amd64/epx" /usr/local/bin/epx

On macOS, use shasum -a 256 --check --ignore-missing instead of sha256sum.

Go

With Go 1.27.3 or later:

go install github.com/commerce-cloud-integrations/emporix-cli/cmd/epx@latest

From source

git clone https://github.com/commerce-cloud-integrations/emporix-cli.git
cd emporix-cli
go build -o bin/epx ./cmd/epx

Upgrading

Uninstalling

1. If you use profiles, remove each one with epx profile remove NAME, which also deletes its client secret from the OS keychain.
2. Remove epx: brew uninstall epx, scoop uninstall epx or npm uninstall --global @commercecloudintegrations/epx-cli, or delete the epx binary you installed.
3. Delete the epx folder from your configuration directory: ~/.config on Linux, ~/Library/Application Support on macOS, %AppData% on Windows.

Getting started

epx authenticates with an Emporix API key. Create a key with only the scopes of the commands you run, then give it to epx through the environment:

export EMPORIX_TENANT=acme1
export EMPORIX_CLIENT_ID=...
export EMPORIX_CLIENT_SECRET=...

Or keep it in a profile, whose client secret goes to the OS keychain:

epx profile add dev --tenant acme1 --client-id ... --site AcmeStore_NL   # asks for the secret

Then make your first reads:

epx auth status --scope product.product_read_unpublished    # check the key and its scopes
epx sites list
epx products list --query published:false --sort code:desc --limit 20
epx products get 100200 -o json
epx api get '/catalog/{tenant}/catalogs'                     # any endpoint

And preview a write before you send it:

epx units create --file gram.json --dry-run    # print the exact request
epx units create --file gram.json              # send it after you confirm

Usage

epx [command]

# Run `--help` for detailed information about a command, its flags, and its scopes
epx [command] --help

# Or read the manual: epx, and each top-level command (installed by Homebrew, the script and npm)
man epx
man epx-products

Commands

Every command's help names the OAuth scopes it requests. The CLI reference documents every command and flag.

Safety

• Reads change nothing, including those that Emporix serves as POST or PUT, such as searches and shipping quotes.
• Writes are explicit. Every write shows its exact request with --dry-run, asks before it sends (a delete only once you type what it deletes), needs --yes in scripts, and is never sent again once it may have reached Emporix.
• Least privilege. Every command requests a token with only the scopes it needs, and fails with exit code 3 when your API key lacks one, instead of silently returning less data. Reads that need a write-capable scope run only with --allow-write-scope.
• Credentials stay private. epx reads its API key from the environment or a profile, never from flags, and never prints its token or client secret.
• One host, HTTPS only. Requests go only to the configured API host, over HTTPS (plain HTTP only to a loopback address, such as a local test server), and redirects are never followed.

-o json and -o yaml print responses as Emporix sends them, secrets included. See the security model.

Exit codes

Documentation

The epx documentation covers installation, authentication, output formats, lists, writes, scripting, and the Emporix API coverage of every command. COMPATIBILITY.md lists the Emporix API operations epx sends, per reference version.

Development

epx is written in Go with Cobra.

go build -o bin/epx ./cmd/epx
go test ./...    # API calls go to local fake servers; no credentials needed

Besides Cobra, epx depends on go-keyring for the client secrets of profiles in the OS keychain (no cgo), and on x/term and x/sys to read a secret without showing it and to lock the configuration file on Windows.

See CONTRIBUTING.md to report a bug or send a change, SECURITY.md to report a vulnerability, and CHANGELOG.md for the changes in each release.

License

Licensed under the Apache License 2.0.

epx is maintained by Commerce Cloud Integrations.