Payroll Engine Console Application

Part of the Payroll Engine open-source payroll automation framework. Full documentation at payrollengine.org.

The Payroll Console application provides API-like commands. See the Payroll Engine samples and tests for examples of how to use this tool. For a better understanding of the working concepts, it is recommended to read the Payroll Engine Whitepaper.

The application is controlled by two types of command line arguments:

• Command: a single command
• Command file: a file containing several commands.

---

Prerequisites

Requirement	Minimum
.NET	10.0
Payroll Engine Backend	running and accessible

---

Commands

The Payroll Console provides the following commands, grouped by area. For detailed descriptions including arguments, toggles and examples, see the Command Reference.

Payroll

Command	Description
PayrollImport	Import any payroll data from JSON/YAML/zip file
PayrollExport	Export any payroll data to JSON/YAML file
PayrollConvert	Convert payroll files between JSON and YAML (supports file masks, recursive)
PayrollMerge	Merge multiple payroll files into one file
PayrollResults	Report payroll data to screen and/or file
CaseChangeExcelImport	Import payroll case changes from Excel file
RegulationExcelImport	Transfer Excel regulation to file or backend

Payrun

Command	Description
PayrunTest	Execute payrun and test the results
PayrunEmployeeTest	Execute employee payrun on a copy and test the results
PayrunEmployeePreviewTest	Execute employee payrun preview (no persistence) and test the results
PayrunJobDelete	Delete a payrun job with payroll results
PayrunRebuild	Rebuild payrun
PayrunStatistics	Display payrun statistics

Report

Command	Description
Report	Report to file 1)
DataReport	Report data to JSON file
ReportTest	Test report output data

Case

Command	Description
CaseTest	Test case availability, build data and user input validation

Script

Command	Description
ScriptExport	Export regulation scripts to folder
ScriptPublish	Publish scripts from C# file

Regulation

Command	Description
LookupTextImport	Import lookup data from text file
RegulationRebuild	Rebuild the regulation objects
RegulationShare	Manage regulation shares

Load Test

Command	Description
LoadTestGenerate	Generate scaled exchange files from a regulation template
LoadTestSetupEmployees	Bulk-import employees for load testing
LoadTestSetupCases	Bulk-import case changes for load testing
PayrunLoadTest	Execute payrun and measure performance (CSV timing report)
LoadTestCleanup	Delete load test employees from a tenant

Tenant / User

Command	Description
TenantDelete	Delete tenant
ChangePassword	Change a user password
UserVariable	View and change the environment user variable

Http / Diagnostics

Command	Description
HttpGet / HttpPost / HttpPut / HttpDelete	Execute HTTP GET, POST, PUT or DELETE request
LogTrail	Trace the tenant log 2)
Stopwatch	Stopwatch based on environment user variable
ActionReport	Report custom actions from an assembly

App

Command	Description
Write	Write to the console and/or log file
Help	Show the command reference

¹⁾ Based on FastReports.
²⁾ Tenant logs are generated by the regulations and should not be confused with the application log.

The required command parameters and options/toggles are passed after the command name. An example of how to bulk import a payroll from a JSON file:

PayrollConsole PayrollImport MyPayroll.json /bulk

The Help command describes the commands and their parameters:

PayrollConsole Help PayrollImport

---

Command Files

The command file is a file with the extension .pecmd that contains a series of instructions to the Payroll Engine Console. The lines of the file are executed sequentially and contain the following line types

• Comment starting with #
• Command instruction
• Start another command file

Example command file Delete.pecmd with a comment and a command statement:

# delete my tenant
TenantDelete MyTenant /trydelete

The following example uses the Delete.pecmd command file and then runs the command to test the payrun:

# cleanup and execute test
Delete.pecmd
PayrunTest *.pt.json

Command files access path

If the called command file is in a different folder, it will be activated before execution:

Test1/Test.pecmd
Test2/Test.pecmd

This is necessary if the called command file is to be defined with local references. The keeppath option prevents directories from being changed:

Tools/Import1.pecmd /keeppath
Tools/Import2.pecmd /keeppath

In the example above, both import command files are run in the startup folder.

Command file parameters

Command files can also be controlled by parameters. Such parameters are used with the placeholder $Name$ in the commands. In the following example, the command file OwnerTest.pecmd has the parameter Owner:

# payrun employee test
# argument owner: job owner
PayrunEmployeeTest fileMask:*.et.json owner:$owner$ /wait

Calling this command file with the Owner parameter looks like this:

OwnerTest.pecmd owner:Test01

File Type Registration

The release package includes setup scripts that register the .pecmd extension with the operating system. Registration is scoped to the current user and does not require administrator privileges.

Windows:

.\Register-PecmdExtension.ps1

To unregister:

.\Register-PecmdExtension.ps1 -Unregister

Linux / macOS:

./register-pecmd.sh

To unregister:

./register-pecmd.sh --unregister

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

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

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

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

Global Toggles

The following toggles apply to all Payroll Console commands:

Name	Description	Values	Command file
Display level	Command information level	full 1), compact, silent	Preset for executing commands
Error mode	Show failed tests and errors	errors1), noerrors	Preset for executing commands
Wait mode	Wait at the program end	waiterror1), wait, nowait	Final application wait mode
Path mode	Path change mode	changepath1), keeppath	Only for command files

¹⁾ Default value.

---

Application Extensions

The Payroll Console provides a plug-in mechanism for integrating custom commands:

• Command parameters with names and options
• Access to the Payroll REST API via the Payroll HTTP client
• Control output to console and logger
• Program exit code definition

To develop a Payroll Console extension, do the following

1. Develop the extension library in C# (example PayrollEngine.Client.Tutorials).
2. Copy the output DLL of the library into the extensions subfolder of the application.
3. Display the command help PayrollEngine Help MyCommandName.
4. Run the command with PayrollEngine MyCommandName.

---

Application Configuration

The Payroll Console configuration appsettings.json contains the following settings:

Setting	Description	Type	Default
StartupCulture	The payroll console process culture	string	System culture
FullErrorLog	Show full error details in log	bool	false
AllowInsecureSsl	Skip backend SSL certificate validation (dev only)	bool	false
ApiSettings	The backend api configuration	Backend API
Serilog	Logger configuration	Serilog

It is recommended that you save the application settings within your local User Secrets.

Backend API Configuration

Setting	Description	Type	Default
BaseUrl	The backend base url	string
Port	The backend url port	string
Timeout	The backend request timeout	TimeSpan	100 seconds
ApiKey	The backend API key	string

The backend API configuration can be declared in the following locations.

Priority	Source	Content
1.	Environment variable PayrollApiConnection	Backend API configuration connection string.
2.	Environment variable PayrollApiConfiguration	Path to the backend API configuration JSON file.
3.	File apisettings.json	Backend API configuration JSON file located in the program folder.
4.	File appsettings.json	ApiSettings from the application configuration JSON file.

API Configuration from connection string

The following is an example of a backend API configuration within a connection string:

BaseUrl=https://localhost; Port=44354; Timeout=02:46:40; ApiKey=MyApiKey; 

API Configuration from JSON

The following is an example of a JSON-based backend API configuration:

{
    "BaseUrl": "https://localhost",
    "Port": 44354,
    "Timeout": "02:46:40",
    "ApiKey": "MyApiKey"
}

---

API Key

If a key is required to access the backend API, it must be obtained from one of the following sources (in order of priority):

1. Environment variable PayrollApiKey
2. Payroll HTTP configuration (see PayrollEngine.Client.Core)

---

Application Logs

The payroll console stores its logs in the application folder logs.

---

Docker Support

The Payroll Console is available as a pre-built Docker image from the GitHub Container Registry.

Pre-built image (ghcr.io)

Run a command against a Backend running in Docker Compose:

<<<<<<< HEAD
docker build --no-cache -t payroll-console .

Run the container to deploy the examples/local files with the environment variable (if appsettings.json is not used):

docker run -it --rm \
  -e PayrollApiConnection="baseUrl=http://<backend-url>;port=<backend-port>;..." \
  -v "$(pwd)/PayrollEngine/examples":/examples \
  payroll-console /examples/Setup.All.pecmd
=======
docker run --rm --network payroll-engine_default \
  -e PayrollApiConnection="BaseUrl=http://backend-api:8080; Port=8080;" \
  ghcr.io/payroll-engine/payrollengine.payrollconsole:latest \
  PayrollImport MyPayroll.json

Run tests:

docker run --rm --network payroll-engine_default \
  -e PayrollApiConnection="BaseUrl=http://backend-api:8080; Port=8080;" \
  ghcr.io/payroll-engine/payrollengine.payrollconsole:latest \
  PayrollTest --testFile Tests/Test.All.pecmd

Run against a Backend on the host machine:

docker run --rm \
  -e PayrollApiConnection="BaseUrl=http://host.docker.internal; Port=5001;" \
  ghcr.io/payroll-engine/payrollengine.payrollconsole:latest \
  Help

Build from source (development)

docker build -t payroll-console .
docker run --rm -it payroll-console Help
>>>>>>> 8037570 (New `PayrunEmployeePreviewTest` command for testing payrun job preview results)

See the Container Setup documentation for the full Docker Compose stack.

---

Build

# Run from the project folder (PayrollConsole/)
dotnet run -- Help

# Publish self-contained binary
dotnet publish -c Release -r win-x64 --self-contained

Environment variable used during build:

Variable	Description
PayrollEnginePackageDir	Output directory for the NuGet package (optional)

---

Solution Projects

Name	Type	Description
PayrollEngine.PayrollConsole.Commands	Library	Console commands
PayrollEngine.PayrollConsole	Exe	Console application

---

Third Party Components

• Excel conversion with NPOI — license Apache 2.0
• Logging with Serilog — license Apache 2.0

---

See Also

• Payroll Console — Automator role documentation
• Command Reference — full argument and toggle reference for all commands
• Client Services — SDK used by this tool
• PayrollEngine Examples — example .pecmd files and test fixtures