Skip to content
Docs
Contact Us

CLI Reference

CLI Reference

Section titled “CLI Reference”

Complete reference documentation for all MirthSync commands and options. MirthSync is a command-line tool for synchronizing Mirth Connect and Open Integration Engine (OIE) code between servers with built-in Git integration.

Overview

Section titled “Overview”

MirthSync has 3 core actions:

ActionDescription
pullDownload channels, code templates, and configurations from server to local files
pushUpload local files to server
git <subcommand>Perform git operations (init, status, add, commit, diff, log, branch, checkout, remote, pull, push, reset)

Basic Syntax:

Terminal window
./mirthsync.sh [options] action

Global Options

Section titled “Global Options”

These options apply to all MirthSync commands:

Server Connection

Section titled “Server Connection”
OptionDescription
-s, --server SERVER_URLFull HTTP(s) URL of the Mirth Connect server (required for pull/push)
-u, --username USERNAMEUsername for authentication (required for pull/push)
-p, --password PASSWORDPassword for authentication (can use MIRTHSYNC_PASSWORD env var)
-i, --ignore-cert-warningsIgnore SSL certificate warnings

Operation Control

Section titled “Operation Control”
OptionDescription
-t, --target TARGET_DIRBase directory for file operations (required)
-f, --forceOverwrite existing files during pull/push without regard for revisions
-vIncrease verbosity level (can specify multiple times: -vvv)
-I, --interactiveAllow console prompts for user input

Disk Mode

Section titled “Disk Mode”
OptionValuesDescription
-m, --disk-mode MODEcode (default)Most granular - extracts JavaScript, SQL to separate files
itemsIndividual XML files for channels and code templates
groupsChannel groups and code template library level
backupFull backup XML file (equivalent to Mirth Administrator backup)

Selective Sync

Section titled “Selective Sync”
OptionDescription
-r, --restrict-to-path PATHLimit scope to specific path within target directory
--include-configuration-mapInclude configuration map in pull/push (default: false)
--skip-disabledSkip disabled channels (default: false, requires Mirth 3.9+)

Channel Deployment

Section titled “Channel Deployment”
OptionDescription
-d, --deployDeploy each channel immediately after saving (individual deployment)
--deploy-allRecommended: Deploy all channels in bulk after push (much faster for multiple channels)

Git Integration

Section titled “Git Integration”
OptionDescription
--git-initInitialize git repository in target directory if not present
--auto-commitAutomatically commit changes after pull/push operations
--commit-message MESSAGECommit message for git operations (default: “mirthsync commit”)
--git-author NAMEGit author name for commits
--git-email EMAILGit author email for commits

Orphaned File Management

Section titled “Orphaned File Management”
OptionDescription
--delete-orphanedDelete orphaned local files during pull operations

Help

Section titled “Help”
OptionDescription
-h, --helpShow help information

Commands

Section titled “Commands”

pull - Download from Server

Section titled “pull - Download from Server”

Pull (download) channels, code templates, configurations, and global scripts from your Mirth Connect or Open Integration Engine server and save them as local files.

Syntax:

Terminal window
./mirthsync.sh -s SERVER_URL -u USERNAME -p PASSWORD -t TARGET_DIR pull [options]

Required Options:

  • -s, --server - Server API URL
  • -u, --username - Username
  • -p, --password - Password (or set MIRTHSYNC_PASSWORD env var)
  • -t, --target - Target directory

Common Options:

  • -f, --force - Overwrite local files without prompting
  • -i, --ignore-cert-warnings - Ignore SSL certificate warnings
  • -r, --restrict-to-path PATH - Pull only specific path
  • --include-configuration-map - Include configuration map
  • --skip-disabled - Skip disabled channels
  • --delete-orphaned - Delete orphaned local files
  • --auto-commit - Automatically commit changes after pull
  • --git-init - Initialize git repo if needed

Examples:

Terminal window
# Basic pull
./mirthsync.sh -s https://localhost:8443/api -u admin -p admin -t ./mirth-config pull


# Pull with force (overwrite local changes)
./mirthsync.sh -s https://localhost:8443/api -u admin -p admin -f -t ./mirth-config pull


# Pull and handle orphaned files
./mirthsync.sh -s https://localhost:8443/api -u admin -p admin --delete-orphaned -t ./mirth-config pull


# Pull with interactive orphan file deletion
./mirthsync.sh -s https://localhost:8443/api -u admin -p admin --delete-orphaned --interactive -t ./mirth-config pull


# Pull and auto-commit to git
./mirthsync.sh -s https://localhost:8443/api -u admin -p admin --git-init --auto-commit --commit-message "Pull from production" -t ./mirth-config pull


# Pull only configuration map
./mirthsync.sh -s https://localhost:8443/api -u admin -p admin --include-configuration-map -t ./mirth-config pull


# Pull only specific channel group
./mirthsync.sh -s https://localhost:8443/api -u admin -p admin -r "Channels/Production Group" -t ./mirth-config pull

What Gets Pulled:

  • Channels (with JavaScript extracted to separate files in default code mode)
  • Code Templates
  • Configuration Map (if --include-configuration-map specified)
  • Global Scripts
  • Channel Groups
  • Resources
  • Alerts

Output Example:

Connecting to Mirth Connect...
✓ Connected to https://localhost:8443
✓ Pulled 15 channels
✓ Pulled 8 code templates
✓ Pulled configuration map
✓ Files saved to ./mirth-config/

Environment Variables

Section titled “Environment Variables”

MirthSync respects these environment variables:

VariableDescriptionExample
MIRTHSYNC_PASSWORDAlternative to --password optionexport MIRTHSYNC_PASSWORD=your_password

Setting Environment Variables:

Terminal window
# In your shell profile (~/.bashrc, ~/.zshrc)
export MIRTHSYNC_PASSWORD=your_password


# For current session only
export MIRTHSYNC_PASSWORD=your_password

File Structure

Section titled “File Structure”

MirthSync creates an organized directory structure based on the --disk-mode setting:

code mode (default)

Section titled “code mode (default)”

Most granular - JavaScript and SQL extracted to separate files:

mirth-config/
├── Channels/
│   ├── Default Group/
│   │   └── ADT_Inbound/
│   │       ├── channel.xml
│   │       ├── sourceConnector.js
│   │       ├── destinationConnector_1.js
│   │       └── transformer.js
│   └── Production Group/
│       └── Lab_Results/
│           └── ...
├── CodeTemplates/
│   ├── Utilities/
│   │   ├── library.xml
│   │   └── parseHL7.js
│   └── ...
├── GlobalScripts/
│   └── ...
└── Resources/
    └── ...

items mode

Section titled “items mode”

Individual XML files for channels and code templates:

mirth-config/
├── Channels/
│   ├── Default Group/
│   │   └── ADT_Inbound.xml
│   └── Production Group/
│       └── Lab_Results.xml
└── CodeTemplates/
    ├── Utilities.xml
    └── ...

groups mode

Section titled “groups mode”

Channel groups and code template libraries:

mirth-config/
├── ChannelGroups/
│   ├── Default Group.xml
│   └── Production Group.xml
└── CodeTemplateLibraries/
    └── Utilities.xml

backup mode

Section titled “backup mode”

Full backup XML (equivalent to Mirth Administrator backup):

mirth-config/
└── backup.xml

Common Workflows

Section titled “Common Workflows”

Daily Development Workflow

Section titled “Daily Development Workflow”
Terminal window
# 1. Pull latest from server
./mirthsync.sh -s https://localhost:8443/api -u admin -p admin -t ./mirth-config pull


# 2. Work on channels in Admin Console or edit files directly


# 3. Pull changes to files
./mirthsync.sh -s https://localhost:8443/api -u admin -p admin -t ./mirth-config pull


# 4. Review changes with git
./mirthsync.sh -t ./mirth-config git diff


# 5. Commit to git
./mirthsync.sh -t ./mirth-config git add
./mirthsync.sh -t ./mirth-config --commit-message "Updated ADT channel" git commit
./mirthsync.sh -t ./mirth-config git push

Deployment to Production

Section titled “Deployment to Production”
Terminal window
# 1. Ensure you're on the correct branch
cd ./mirth-config && git checkout main && git pull && cd ..


# 2. Preview what would be pushed (manual verification)
ls -la ./mirth-config/Channels/


# 3. Push to production
./mirthsync.sh -s https://prod-server:8443/api -u admin -p $PROD_PASSWORD -f -t ./mirth-config push


# 4. Deploy all channels in bulk
./mirthsync.sh -s https://prod-server:8443/api -u admin -p $PROD_PASSWORD --deploy-all -t ./mirth-config push


# 5. Verify (check server manually)

Emergency Rollback

Section titled “Emergency Rollback”
Terminal window
# 1. Find the commit to rollback to
./mirthsync.sh -t ./mirth-config git log 10


# 2. Reset to previous commit (hard reset)
./mirthsync.sh -t ./mirth-config git reset --hard abc1234


# 3. Push reverted configuration to server
./mirthsync.sh -s https://prod-server:8443/api -u admin -p $PROD_PASSWORD -f -t ./mirth-config push

CI/CD Integration

Section titled “CI/CD Integration”
Terminal window
# In GitHub Actions or Jenkins pipeline


# Pull from dev server
./mirthsync.sh -s ${DEV_URL} -u ${DEV_USER} -p ${DEV_PASS} -i -t src pull


# Commit changes
./mirthsync.sh -t src git add
./mirthsync.sh -t src --commit-message "Automated pull from dev" git commit
./mirthsync.sh -t src git push


# On merge to main, deploy to staging
./mirthsync.sh -s ${STAGE_URL} -u ${STAGE_USER} -p ${STAGE_PASS} -t src --include-configuration-map -f push