Skip to main content

DSRun CLI

info

Available from Version 6.0.3686

DSRun is a command line tool that runs Data Sync projects (.dsprj files) without opening the Data Sync Designer. It has no user interface: it runs one or more projects in order, writes its progress to the console, saves a log of the run and returns an exit code that tells the caller whether the run succeeded.

Use DSRun when you want to run your projects from something other than the Designer, for example:

  • A batch file or PowerShell script.
  • Windows Task Scheduler or SQL Server Agent.
  • A build or deployment pipeline, such as Azure DevOps, GitHub Actions or Jenkins.
  • Another program that needs to start a sync and check the result.

DSRun or the Run Tool?​

Data Sync also includes the Run Tool (Simego.DataSync.Run.exe), which can also be started from the command line.

DSRunRun Tool
What it runsData Sync projects (.dsprj) that you list on the command line.A Run Tool project (.dsrun) that you build in the Run Tool window.
StepsData Sync projects only.Data Sync projects plus other steps, such as copying files, running PowerShell or sending email.
InterfaceConsole only. Made for scripts and automation.A Windows application, which can also be started from the command line.
ResultsConsole output, a JSON log file, HTML or XML reports and an exit code.The Run Tool window, log files and email reports.
info

The name is similar, but DSRun does not run Run Tool (.dsrun) projects. To run a .dsrun file from the command line, see Run From the Command Line.

Choose DSRun when you only need to run Data Sync projects and want a simple command, a log file and an exit code. Choose the Run Tool when you need its other step types. For a central server that schedules and monitors your projects, see Ouvvi.

Where to Find DSRun​

DSRun is installed with Data Sync, in the same folder as the Designer:

C:\Program Files\Simego\Data Synchronisation Studio 6.0\DSRun.exe

The installer sets the DATASYNCINSTALLPATH60 environment variable to this folder, so in a script you can start DSRun with:

"%DATASYNCINSTALLPATH60%\DSRun.exe" run Northwind

The examples on this page use DSRun on its own. Either use the full path, or add the Data Sync folder to your PATH.

DSRun uses the same license, Connection Library and settings as the Data Sync Designer on the same machine.

Quick Start​

Run the project C:\DSProjects\Northwind.dsprj:

cd C:\DSProjects
DSRun run Northwind

Run three projects in order and save the log to a file you choose:

DSRun run Customers Orders Invoices -w C:\DSProjects -o C:\Logs\nightly.json

Turn the log into an HTML report:

DSRun report C:\Logs\nightly.json -o C:\Logs\nightly.html

Commands​

CommandWhat it does
runRuns one or more Data Sync projects.
reportTurns a JSON log file from run into an HTML or XML report.
versionWrites the DSRun version number.

To see the help for DSRun, or for one command, add --help (or -h, -?, /?):

DSRun --help
DSRun run --help

run​

Runs one or more Data Sync projects in the order you list them.

DSRun run <projects>... [options]

Projects​

List one or more project files, separated by spaces. Put a path in double quotes if it contains a space.

  • The .dsprj extension is optional. Northwind and Northwind.dsprj both run Northwind.dsprj.
  • A relative path is resolved from the working directory (see --working-directory).
  • You can use environment variables, such as %DSPROJECTS%\Northwind, and ~ for your user profile folder, such as ~\DSProjects\Northwind.
  • The file name without the extension is used as the step name in the console output and the log.

Options​

OptionShortDescription
--working-directory <path>-wThe folder used to resolve relative project and report paths. The default is the current folder. Environment variables and ~ are expanded.
--parameter <name=value>-pSets a project property for this run. Repeat the option for each property. See Parameters.
--continue-on-error-cKeeps running the remaining projects after a project fails. Without this option, DSRun stops at the first failure.
--retry-count <count>-rThe number of times to retry a project that fails. The default is 0, no retries.
--retry-interval <hh:mm:ss>-iHow long to wait before each retry, for example 00:00:30. The default is no wait.
--report <file>-oWhere to write the JSON log file. A relative path is resolved from the working directory. See Log File.
--connections <path>-lThe folder of the Connection Library to use. The default is the Connection Library used by the Designer. Use a full path.
warning

Always give --retry-interval as hh:mm:ss. A plain number is read as a number of days, so -i 30 waits 30 days, not 30 seconds.

Parameters​

Use --parameter (-p) to pass values into your projects. Each value sets a project property in every project in the run:

  • If the project has a property with the same name, its value is replaced. Names are not case-sensitive.
  • If the project doesn't have the property, it is added.
DSRun run Orders -p "FromDate=2026-01-01" -p "Region=North West"

Read the values in Dynamic Columns or Project Automation with Properties["Name"]. For example, to filter the source with the FromDate parameter:

public override void Start()
{
DataSourceA.CommandWhere = string.Format("OrderDate >= '{0}'", Properties["FromDate"]);
}

Write each parameter as name=value. Everything after the first = is the value, and spaces around the name and value are removed. Put the whole parameter in double quotes if the value contains a space. A parameter without =, such as -p Debug, sets the property to an empty value.

Automatic Properties​

DSRun also sets these properties before each project runs:

PropertyValue
Auto_StepNameThe name of the project being run, which is its file name without the extension.
Auto_StepIndexThe position of the project in the run, starting at 1.
Auto_RowsAffectedThe total number of rows added, updated and deleted by the projects that have already succeeded in this run.

Failures and Retries​

A project fails if it can't be opened or connected to, or if the sync reports an error. When a project fails:

  1. If --retry-count is more than 0, DSRun waits for the --retry-interval and runs the project again, up to that number of times. The project file is opened again for each attempt.
  2. If the project still fails, DSRun writes an error. Without --continue-on-error it stops and the remaining projects don't run. With --continue-on-error it moves on to the next project.

Whether a project fails on a row error during the sync is set by its SyncFailOnError property.

note

If a project file doesn't exist, DSRun stops the run straight away, even with --continue-on-error.

Console Output​

Each line of output starts with the name of the project it came from. When the run finishes, DSRun writes a summary line, which is shown in red if any project failed:

Customers.Processing [Project=Customers.dsprj]
...
Orders.Processing [Project=Orders.dsprj]
...

DSRun.Completed [Status=Success, Projects=2, Succeeded=2, Failed=0, Duration=00:00:12.4810000]

Exit Codes​

Exit codeMeaning
0Every project succeeded.
Not 0One or more projects failed, or DSRun couldn't run. With --continue-on-error the exit code is the number of projects that failed.

Check the exit code in your script to find out whether the run succeeded. See the examples below.

Log File​

DSRun always writes a JSON log file of the run, even when a project fails. If you don't set --report, the log is saved in a .ds folder in the working directory, named from the start time of the run:

<working directory>\.ds\20261117-020000.json

The folder is created if it doesn't exist. The log has a summary of the run, the results of each project and every message written during the run:

{
"Instance": {
"ID": "{3f2a1c4e-5b6d-4e7f-8a9b-0c1d2e3f4a5b}",
"ConnectionRegistry": "C:\\ProgramData\\Simego\\DataSyncStudio60\\Registry",
"StartTime": "2026-11-17T02:00:00.1234567+00:00",
"EndTime": "2026-11-17T02:00:12.6044567+00:00",
"Duration": "0:00:00:12.4810000",
"Result": "Success",
"Steps": [
{
"StepName": "Customers",
"Result": "Success",
"Duration": "0:00:00:05.2100000",
"SourceRows": 1250,
"TargetRows": 1248,
"Add": 2,
"Update": 14,
"Delete": 0
}
],
"Log": [
{
"DateTime": "2026-11-17T02:00:00.1300000+00:00",
"Severity": "Information",
"Name": "Customers",
"Message": "Processing [Project=Customers.dsprj]"
}
]
}
}
FieldDescription
Instance.ResultSuccess if every project succeeded, otherwise Failure.
Steps[].ResultThe result of each project: Success or Failure.
Steps[].SourceRows, TargetRowsThe number of rows read from the source and target.
Steps[].Add, Update, DeleteThe number of rows added, updated and deleted in the target.
Log[].SeverityInformation, Warning or Error.
Log[].TraceError details, included only when there are any.

The log is a stable format that other tools can read, for example to load run history into a database or to raise an alert.

tip

Old log files in the .ds folder are not removed. If you run DSRun on a schedule, either clean up the folder or use --report to write the log to a fixed file name that is replaced each run.

report​

Turns a JSON log file written by run into an HTML or XML report.

DSRun report <input> [options]
Argument or optionShortDescription
<input>The JSON log file to read.
--output <file>-oThe report file to write. The extension sets the format: .html or .xml.
--format <format>-fhtml or xml. Needed only when there is no --output, in which case the report is written to the console.

The HTML report is a single page with a summary of the run, a table of the results of each project and the full log. You can open it in a browser, save it with your other run history or send it by email.

DSRun report .ds\20261117-020000.json -o nightly.html
DSRun report nightly.json -f xml > nightly.xml

Examples​

Batch File​

Run the nightly projects, keep going if one fails, and create an HTML report:

@echo off
set DSRUN="%DATASYNCINSTALLPATH60%\DSRun.exe"
set LOGS=C:\DSProjects\Logs

%DSRUN% run Customers Orders Invoices -w C:\DSProjects -c -r 2 -i 00:01:00 -o %LOGS%\nightly.json
set RESULT=%ERRORLEVEL%

%DSRUN% report %LOGS%\nightly.json -o %LOGS%\nightly.html

if %RESULT% NEQ 0 (
echo %RESULT% project^(s^) failed.
exit /b %RESULT%
)

PowerShell​

Run a project with a parameter and read the results from the log:

$dsrun = Join-Path $env:DATASYNCINSTALLPATH60 'DSRun.exe'
$log = 'C:\DSProjects\Logs\orders.json'

& $dsrun run Orders -w C:\DSProjects -p "FromDate=$((Get-Date).AddDays(-1).ToString('yyyy-MM-dd'))" -o $log

if ($LASTEXITCODE -ne 0) {
$run = Get-Content $log -Raw | ConvertFrom-Json
$run.Instance.Steps | Where-Object Result -ne 'Success' | ForEach-Object {
Write-Error "$($_.StepName) failed"
}
exit $LASTEXITCODE
}

Windows Task Scheduler​

Create a task with a Start a program action:

SettingValue
Program/scriptC:\Program Files\Simego\Data Synchronisation Studio 6.0\DSRun.exe
Add argumentsrun Customers Orders -c -o C:\DSProjects\Logs\nightly.json
Start inC:\DSProjects

Start in becomes the working directory, so the project names are found in C:\DSProjects. For more on scheduled tasks, see Scheduling.

SQL Server Agent​

Add a job step of type Operating system (CmdExec) with the command:

"C:\Program Files\Simego\Data Synchronisation Studio 6.0\DSRun.exe" run Customers Orders -w C:\DSProjects -o C:\DSProjects\Logs\agent.json

SQL Server Agent fails the job step when DSRun returns an exit code other than 0.

info

DSRun runs as the user that starts it. When it is started by Task Scheduler, SQL Server Agent or a build agent, that account must have access to the project files, the Connection Library and every data source in your projects. A connection that uses Windows authentication connects as that account.