Installation

Installing MirthSync CLI

MirthSync installs in minutes on Windows, macOS, and Linux. The CLI includes embedded Git, so you can start version controlling your Mirth Connect or OIE configurations immediately—no separate installations or complex setup required.

Prerequisites

Before you install MirthSync, make sure you have:

• Java JRE or JDK version 8 or higher (Java 8, 11, 17, 21, and other LTS versions are supported)

Additionally:

• Mirth Connect 4.x or Open Integration Engine (OIE) 3.x/4.x - The integration platform you want to version control
  • ✅ Recommended: Open Integration Engine (OIE) - the community-driven open-source fork
  • ✅ Legacy open-source Mirth Connect 4.x
  • ⚠️ Commercial Mirth Connect versions - compatibility not guaranteed

Embedded Git Included

MirthSync includes an embedded Git binary. You don’t need to install Git separately—all Git functionality is built into the CLI.

macOS Additional Requirements

When using MirthSync on macOS, you’ll also need:

• coreutils - brew install coreutils
• gnu-sed - brew install gnu-sed

After installing, add to your PATH in ~/.zshrc or ~/.bash_profile:

export PATH="/opt/homebrew/opt/coreutils/libexec/gnubin:$PATH"
export PATH="/opt/homebrew/opt/gnu-sed/libexec/gnubin:$PATH"

Installation

Download the latest MirthSync release from the GitHub Releases page:

1. Go to the releases page
2. Download the latest mirthsync-X.X.X-standalone.jar file
3. Place it in a convenient location (e.g., /opt/mirthsync/ or C:\mirthsync\)

Verify the installation by viewing help:

java -jar mirthsync.jar -h

Create an Alias

For convenience, create an alias in your shell profile:

# Add to ~/.bashrc, ~/.zshrc, or equivalent
alias mirthsync="java -jar /path/to/mirthsync.jar"

Then you can run commands as simply mirthsync pull instead of java -jar mirthsync.jar pull.

Install from Source

Use this method if you:

• Want to contribute to MirthSync development
• Need unreleased features from the main branch
• Want to customize MirthSync for your environment

Prerequisites for source installation:

• Git
• Leiningen (Clojure build tool)
• Java JDK 8 or higher

# Clone the repository
git clone https://github.com/SagaHealthcareIT/mirthsync.git
cd mirthsync

# Build the standalone JAR
lein uberjar

# The JAR will be in target/uberjar/mirthsync-X.X.X-standalone.jar
java -jar target/uberjar/mirthsync-*-standalone.jar -h

Configuration

MirthSync needs connection details for your Mirth Connect or OIE server. Connection parameters are passed via command-line flags:

Flag	Description
-s	Server URL (e.g., https://mirth.example.com:8443/api)
-u	Username
-p	Password (or use MIRTHSYNC_PASSWORD environment variable)
-t	Target directory for configuration files
-i	Ignore certificate errors (for self-signed certs)

Example pull command:

# Using password flag
java -jar mirthsync.jar -s https://mirth.example.com:8443/api -u admin -p yourpassword -t ./mirth-config pull

# Using environment variable for password (recommended)
export MIRTHSYNC_PASSWORD=yourpassword
java -jar mirthsync.jar -s https://mirth.example.com:8443/api -u admin -t ./mirth-config pull

OIE Users

OIE uses the same API endpoints as Mirth Connect. Configuration is identical - just point to your OIE server URL.

Verify Installation

Test that MirthSync can connect to your server by pulling configurations:

export MIRTHSYNC_PASSWORD=admin
java -jar mirthsync.jar -s https://mirth.example.com:8443/api -u admin -t ./mirth-config -i pull

If successful, you’ll see output showing channels and code templates being downloaded to your target directory.

Troubleshooting

If you see connection errors, check the Troubleshooting section below.

---

Troubleshooting

Java not found

If you get java: command not found:

1. Install Java JRE or JDK 8 or higher
2. Verify installation: java -version
3. Ensure Java is in your PATH

Connection errors

If you can’t connect to Mirth Connect:

• Verify the server URL includes the /api path
• Check that Mirth Connect is running
• Ensure the API port (usually 8443) is accessible
• Verify your username and password
• Try adding the -i flag to ignore certificate errors

SSL Certificate Errors

If you see SSL/TLS certificate errors:

Self-signed certificates:

# Use the -i flag to ignore certificate validation
java -jar mirthsync.jar -s https://mirth.example.com:8443/api -u admin -t ./mirth-config -i pull

Proper solution for production:

• Install your organization’s root CA certificate
• Use a properly signed certificate for Mirth Connect/OIE

Firewall or Network Issues

If the connection times out:

• Check server is running: Open Admin Console to verify Mirth/OIE is up
• Verify API port: Default is 8443, confirm in your server settings
• Test network access: curl https://mirth.example.com:8443/api should respond
• Check firewall: Ensure port 8443 is open between your machine and the server
• VPN required? Some organizations require VPN to access Mirth servers

---

Next Steps

Continue to Setup Guide

Now that MirthSync is installed, the Setup Guide will walk you through:

• Pulling configurations from your Mirth Connect or OIE server
• Initializing Git version control
• Making your first commit

→ Continue to Setup Guide