EDI Converter Command-Line Tool Installation

Choose the installation method for your platform:

• Windows installer (recommended): Installs the desktop application and CLI for the current user, bundles Java, and adds ediconvert to the user PATH.
• Homebrew on macOS (recommended): Installs the CLI and its Java dependency.
• ZIP distribution: Available for Windows, Linux, and macOS. This option requires Java 17 or later and manual launcher setup.

All installation methods require a license. Request a trial license if you do not already have one.

Windows Installer (Recommended)

1. Download the Windows installer and run it.
2. Open EDI Converter from the desktop shortcut.
3. Select Help > Manage License…, choose your edi-license.txt file, and save it.
4. Open a new Command Prompt window and run:

ediconvert -V

The installer includes its own Java runtime, adds ediconvert to your user PATH, and does not require administrator privileges. Open a new Command Prompt after installation so it picks up the updated PATH.

The installer is digitally signed by MyArch Data Security Inc. Because it has not yet built a sufficient Microsoft SmartScreen reputation, Microsoft Edge or Microsoft Defender SmartScreen may still warn that the file is not commonly downloaded or that Windows protected your PC.

To download the installer using Microsoft Edge, select “More Info” (three dots) and “Keep”, then, if prompted, select “Keep anyway” using the dropdown menu next to the “Delete” button.

In all other browsers, select “More info > Run anyway” when prompted by the Microsoft Defender.

macOS Installation with Homebrew (Recommended)

If Homebrew is not installed, follow the Homebrew installation instructions. Then run:

brew install healthcare-data-insight/tap/ediconvert

Save edi-license.txt as ~/.ediconvert/edi-license.txt, then verify the installation:

ediconvert -V

Manual ZIP Installation

Use the ZIP distribution on Linux or when you prefer a portable installation on Windows or macOS. It contains both the ediconvert CLI launcher and the ediconvert-ui desktop launcher, but it does not include Java.

Install Java

Install Java 17 or later from the Oracle website, OpenJDK, or your operating system’s package manager. We recommend Java 25. Verify the active version:

java -version

If JAVA_HOME is defined, make sure it points to Java 17 or later. Windows users should also confirm that the command does not resolve to a previously installed Java 8 runtime.

Download the EDI Converter ZIP file and extract it. The extracted directory is named ediconvert.

Windows ZIP Setup

1. Move the extracted directory to a stable location, such as C:\Tools\ediconvert.
2. Add C:\Tools\ediconvert\bin to your user Path under Advanced system settings > Environment Variables.
3. Save your license as C:\Users\<username>\.ediconvert\edi-license.txt.
4. Open a new Command Prompt and run ediconvert -V.

Without the Path entry, run the CLI as C:\Tools\ediconvert\bin\ediconvert.

Linux and macOS ZIP Setup

Move the extracted directory to /opt, then create a launcher symlink in /usr/local/bin:

sudo mkdir -p /opt /usr/local/bin
sudo mv ediconvert /opt/ediconvert
sudo ln -s /opt/ediconvert/bin/ediconvert /usr/local/bin/ediconvert

Save your license as ~/.ediconvert/edi-license.txt, then verify the installation:

ediconvert -V

The installation directory must remain at /opt/ediconvert so the symlink stays valid. If /usr/local/bin is not in your PATH, add it to your shell startup file. If you cannot create the symlink, run /opt/ediconvert/bin/ediconvert directly or add /opt/ediconvert/bin to your PATH.

License Configuration

The recommended license location is:

• Windows: C:\Users\<username>\.ediconvert\edi-license.txt
• Linux and macOS: ~/.ediconvert/edi-license.txt

The Windows application’s Help > Manage License… command copies the selected license to this location automatically. The converter also checks its installation directory, which can be useful for portable ZIP installations.

To store the license file elsewhere, set the EDI_LICENSE_FILE environment variable to the file’s absolute path.

On Linux or macOS, add the variable to your shell startup file, such as ~/.bashrc or ~/.zshrc:

export EDI_LICENSE_FILE="/absolute/path/to/edi-license.txt"

On Windows, create an EDI_LICENSE_FILE user environment variable under Advanced system settings > Environment Variables.

You can also set your license key with the EDI_LICENSE_KEY environment variable. Copy the entire contents of edi-license.txt into the variable. In this case, you don’t need to save the license file.

Run ediconvert -V to view the license information and the location of the license file.

Logs

The converter writes informational and diagnostic messages to ~/.ediconvert/logs on Linux and macOS or C:\Users\<username>\.ediconvert\logs on Windows. It writes log files even when --quiet is used, which keeps diagnostic output separate when converted data is sent to standard output.

To use another directory, set the ediconvert_logs_dir environment variable. For example:

export ediconvert_logs_dir=ediconverter_logs

Environment Variables

You can set the following environment variables to configure the converter:

Shell Autocompletion

Autocompletion is available for Bash and Zsh. Download the completion script, save it in a location of your choice, and source it from your shell startup file, such as ~/.bashrc or ~/.zshrc. If bash_completion is installed, you can place the script in the appropriate location, such as /etc/bash_completion.d. For more information, see the picocli autocompletion documentation.