Skip to content

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 unless --token is used)
-p, --password PASSWORDPassword for authentication (can use MIRTHSYNC_PASSWORD env var)
--token TOKENAuthenticate with an existing HTTP session token instead of username/password (mutually exclusive with them; MirthSync 3.5.2+)
-i, --ignore-cert-warningsIgnore SSL certificate warnings

Operation Control

Section titled “Operation Control”
OptionDescription
-t, --target TARGET_DIRBase directory for file operations (required)
-f, --forceOn pull, overwrite existing local files. On push, overwrite server items without regard for revisions. Without -f, code templates, code template libraries and channel groups whose revision on the server differs from your copy are refused and the push exits non-zero; channels are overwritten either way
-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-allDeploy all pushed channels in one bulk call after the push (much faster for multiple channels). A failed deploy is logged but the exit code stays 0 (through 3.8.0), so in scripts and CI prefer --deploy-changed --deploy-new, which exits non-zero when a deploy fails
--deploy-changedAfter push, deploy every deployed channel the server reports as changed, whether or not this push saved it: a non-zero deployedRevisionDelta, or codeTemplatesChanged when this push saved code templates (MirthSync 3.7.0+)
--deploy-newUse with --deploy-changed: also deploy pushed channels that are not currently deployed (MirthSync 3.7.0+)

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

Stable Ordering

Section titled “Stable Ordering”
OptionDescription
--[no-]sort-unorderedSort collections that Mirth stores in no fixed order during a pull (default: on; MirthSync 3.8.0+)

Mirth stores some collections in no fixed order, so pulling unchanged code could show them reordered in Git. A pull now sorts them: code template context types, library and alert channel IDs, alert connectors and error event types, channel dependency and tag IDs, connector plugin and attachment handler properties, the configuration map and global scripts. In a backup mode server configuration it also sorts the alert list, channel tags, channel dependencies and plugin properties. Lists whose order matters, such as destination connectors and transformer steps, are left untouched, and no values are changed. Pushes are unaffected.

Help

Section titled “Help”
OptionDescription
-h, --helpShow help information
-V, --versionPrint the installed MirthSync version and exit (no server or credentials required; MirthSync 3.6.0+)

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
  • --no-sort-unordered - Keep the server’s order for unordered collections (sorted by default)
  • --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