Payroll Console

The Payroll Console is the primary CLI tool for Automators. It exposes Client Services functionality as console commands and supports batch execution via .pecmd command files.

Typical use cases include data import and export, automated testing in CI/CD pipelines, and load testing against a live backend.

Running the Console

Local

Prerequisites: .NET 10 Runtime

Download the latest release binary from GitHub Releases or install via NuGet:

dotnet tool install --global PayrollEngine.PayrollConsole

Configure the backend connection in appsettings.json:

{
  "PayrollApiConnection": {
    "BaseUrl": "http://localhost",
    "Port": 5001
  }
}

Run a command:

PayrollConsole PayrollImport MyRegulation.json

Docker

The console is available as a pre-built Linux image:

docker run --rm --network payroll-engine_default \
  -e PayrollApiConnection="BaseUrl=http://backend-api:8080; Port=8080;" \
  ghcr.io/payroll-engine/payrollengine.payrollconsole:latest \
  PayrollImport MyRegulation.json

The container must share the same Docker network as the backend. See Container Setup for the full stack setup.

Command Files

For batch execution, commands can be chained in .pecmd files. Sub-command files can be invoked from within a command file.

# Setup.All.pecmd
PayrollImport Tenant.json
PayrollImport Regulation.json
PayrollImport Employees.json

Run a command file:

PayrollConsole Setup.All.pecmd

Do not add /wait to test commands in bulk command files — commands are designed to pause only on failure.

File Type Registration

The release package includes setup scripts that register the .pecmd extension with the operating system. Once registered, .pecmd files can be opened directly from the shell or file manager.

Registration is scoped to the current user and does not require administrator privileges.

Windows

.\Register-PecmdExtension.ps1

To unregister:

.\Register-PecmdExtension.ps1 -Unregister

If the console binary is not in the same directory as the script, specify the path explicitly:

.\Register-PecmdExtension.ps1 -ConsolePath "C:\Tools\PayrollEngine.PayrollConsole.exe"

Linux / macOS

./register-pecmd.sh

To unregister:

./register-pecmd.sh --unregister

If the console binary is not in the same directory as the script, specify the path explicitly:

./register-pecmd.sh --console-path /opt/payrollengine/PayrollEngine.PayrollConsole

On Linux, the script additionally registers a MIME type and a desktop entry, enabling file manager integration. On macOS, the script creates a shell wrapper; double-click support requires a .app bundle (see the script comments).

In containerized environments, file type registration is not needed. Pass the .pecmd file directly as an argument to docker run.

Command Reference

The Payroll Console provides 30+ commands across 13 groups. Full parameter documentation is available on GitHub.

Payroll

Command	Description
PayrollImport	Import regulations and payroll data (JSON/YAML, supports file masks and zip archives)
PayrollExport	Export regulations and payroll data (JSON/YAML, selective)
PayrollConvert	Convert payroll files between JSON and YAML (supports file masks and recursive conversion)
CaseChangeExcelImport	Import case changes from Excel
RegulationExcelImport	Import a regulation from Excel or convert it to JSON

Payrun

Command	Description
PayrunTest	Import payroll, execute payrun, validate results, clean up
PayrunEmployeeTest	Run test on a copy of an existing employee
PayrunEmployeePreviewTest	Run test via preview API — no persistence, no cleanup needed
PayrunLoadTest	Execute payrun with warmup and measured repetitions; produces a CSV timing report

Report

Command	Description
`Report`	Generate a report in XML, Excel, or PDF format
`DataReport`	Generate a data report in JSON format
`ReportTest`	Test report parameters and output

Case

Command	Description
`CaseTest`	Test case input, validation, and computed values

Script

Command	Description
`ScriptImport`	Import regulation scripts from source files
`ScriptExport`	Export regulation scripts to source files
`ScriptRebuild`	Rebuild all compiled regulation scripts

Load Test

Command	Description
`LoadTestGenerate`	Generate a scaled exchange file from a regulation template
`LoadTestSetup`	Bulk-import employees via the bulk creation API
`LoadTestSetupCases`	Bulk-import case changes

See Performance for the complete load test workflow.

Tenant / User

Command	Description
`TenantDelete`	Delete a tenant and all its data
`UserList`	List all users for a tenant

Http / Diagnostics

Command	Description
`HttpGet`	Ad-hoc GET request against any backend endpoint
`PayrollLog`	Query the payroll audit log trail

App

Command	Description
`Write`	Write a message to the console output (useful in `.pecmd` files)

Custom Commands

The console supports a plug-in mechanism for domain-specific commands. Drop a C# class library into the extensions subfolder to add custom commands without modifying the console itself.

See Automation Extension for setup, implementation, and examples.