PPExec Documentation

Overview

PPExec runs a program on one or many Windows computers at once: either locally, on remote machines across the network, as another user, as Local System, or on a logged-on user’s desktop. It copies what the program needs to each target, checks each target against criteria you choose before copying/executing, streams the program’s output back (console output and return code), and records every run in a log folder of its own.

PPExec has two front-ends sharing one engine:

• PPExec GUI (ppexec-gui.exe) - a windowed application for building, saving and running jobs interactively.
• PPExec command line (ppexec.exe) - for scripts, scheduled tasks and deployment tools.

Both run the same underlying code, understand the same filters and write identical log folders. Anything you can do in one you can almost always do in the other; where one has an option the other lacks, they will be highlighted in this document.

1 - Components

The service hosts must be located in the same folder as ppexec.exe and ppexec-gui.exe. PPExec looks for them in the same directory as whichever front-end is running.

2 - Installation

Run “PPExecSetup.exe” as an administrator. The installer:

• installs to “C:\Program Files\Emerita\PPExec” by default (you can choose another folder).
• adds a PPExec entry to the Start menu for launching the GUI.
• optionally adds a desktop shortcut (Create a desktop shortcut, which is off by default).
• optionally adds the installation folder to the system PATH (Add PPExec to the system PATH, on by default), so ppexec can be typed in any new Command Prompt or PowerShell window. Console windows that were already open before installation will not see the change until they are reopened.

PPExec is a 64-bit program and installs on 64-bit Windows only. It can still run programs on 32-bit targets (see 32-bit targets).

To uninstall, use Settings › Apps (or Programs and Features). The uninstaller also removes the PATH entry if it added one. Your log folders under %LOCALAPPDATA%\Emerita\PPExec\Logs are left in place.

Nothing needs to be installed on the target computers. PPExec copies the relevant service host for the duration of each run and removes it afterwards.

3 - Requirements

On the computer running PPExec

• A 64-bit Microsoft supported edition of Windows.
• To run a program locally as Local System (-s) or on the interactive desktop (-i), PPExec installs a temporary service on this computer, so it must be run as an administrator (an elevated prompt, or Run as administrator for the GUI).
• A plain local run (no target computers, no -s/-i) needs no special rights beyond those needed to start the program.

On each remote target

PPExec reaches a target using the same mechanisms Windows’ own remote administration tools do. Each target must allow:

• An administrator account. The account PPExec connects with - your currently logged-on account, or the one given with -u / the User field - must be a member of the target’s local Administrators group.
• The admin share (ADMIN$ by default) - File and Printer Sharing must be enabled and reachable through the target’s firewall (SMB, TCP port 445). PPExec copies its service host, and ultimately your program, through it.
• Remote service control - PPExec creates, starts, stops and deletes a temporary service through the target’s Service Control Manager.
• Named pipes over SMB - PPExec talks to its service and relays your program’s input and output over named pipes on the same connection.

32-bit (x86) targets

ppexec-svc.exe is a 64-bit program and cannot start on 32-bit Windows. In order to run on 32-bit targets, restrict the run to them with an Architecture = x86 (32-bit) filter (GUI Filter tab, or -filter "arch=x86"). PPExec then copies ppexec-svc-x86.exe instead.

Always target 32-bit and 64-bit runs separately.

4 - Licensing and registration

Editions

PPExec is licensed per edition. Each edition sets how much one run may do; if a run asks for more, PPExec reduces it to the edition’s limits, prints a notice saying what it changed, and carries on.

• A Business Edition run given more than 100 computers will run on the first 100 in the list and reports the rest as dropped, for example: Business Edition limits one run to 100 targets; 140 requested, first 100 retained.
• “Concurrent sessions” and “concurrent copies” are explained in Concurrency.
• On a Business Edition machine the GUI’s Concurrent sessions and Concurrent copies fields start at 10 and 5 (also their maximums) instead of the usual 32 and 10.
• Concurrent sessions and Concurrent copies may increase in future for Enterprise and Contractor editions.

Trial

An unregistered copy runs while its evaluation period is active. Each ppexec.exe run starts with the same banner a licensed copy shows, saying how much of the trial remains:

Licensed to   : Trial version
Remaining     : 28 days

In the GUI, the Settings tab’s Registration › Username field shows remaining trial days Trial version - 28 days remaining.

Once the trial has ended, runs are refused with exit code -14 until the software is registered.

Registering

Registration is per source/central console machine (target machines do not need registration), and is done from the GUI:

1. Open PPExec GUI and go to the Settings tab.
2. Click Register….
3. Enter the Username and Serial number exactly as supplied with your license, and click OK.

On success the Registration section of the Settings tab shows the license. The same registration covers ppexec.exe on the machine.

Seeing what a machine is licensed for

• GUI: the Settings tab’s Registration section shows Username, Serial (all but the last block masked, e.g. XXXXX-XXXXX-KLMNO), Edition and Support until (e.g. 26 September 2026). The About… box shows the license holder and support expiry date.
• Command line: every run begins with the license banner:

  Licensed to   : Company Ltd (Enterprise Edition - Unlimited devices for named company)
  Support until : 26 September 2027

License and integrity errors

Before every run PPExec verifies its license and its own digital signature. If either check fails, nothing is started anywhere.

5 - How a run works

Understanding the execution sequence should help improve your experience of using PPExec.

Where the program runs

The steps for each remote target

1. Signature checks (once per run, before anything else).
2. Connect to the target’s admin share (\\target\ADMIN$), using the supplied credentials if any.
3. Copy the service host (ppexec-svc.exe) into the share, under a service name unique to this run (see Service names). For security reasons, PPExec first confirms the service host carries Emerita’s valid digital signature and refuses to send it otherwise. This is to reduce the security threat from running unauthorized patched versions of the product.
4. Install and start the service through the target’s Service Control Manager.
5. Check the filter. The service evaluates your filter criteria on the target itself. A target that does not match is left alone and reported as Filtered - nothing else is copied to it.
6. Copy your program and any additional files (only with Copy app to target / -c).
7. Launch the program with the requested account, privileges, priority, working directory and so on.
8. Stream its standard output and error back to PPExec until it exits or the timeout expires. With a single target the command line also sends your keyboard input (or anything piped or redirected into ppexec) to the program, so ppexec \\server cmd.exe gives you a working remote command prompt - see Interactive sessions. With several targets, programs receive no input, so run them with options that do not prompt - silent/unattended switches for installers, for example.
9. Clean up: files copied during this run are deleted (unless you asked to keep them), the service is stopped and deleted, and the service host file is removed.

Serial and parallel runs

• Serial: one target at a time, in list order. This is the default for the command-line version, PPExec.exe (for PSExec/PAExec compatibility); each target’s output is printed as it arrives.
• Parallel: up to N targets at once (-par N, or the GUI’s Concurrent sessions). The GUI runs in parallel by default (32 concurrent sessions, up to a maximum of 256). Using the command line PPExec.exe, a parallel run shows a live progress display instead of output, and each target’s output goes to its own log file.

Concurrency

Two separate limits apply to a parallel run:

Every remote target receives at least the service host, and with Copy app to target also your program and additional files. Without the copy limit, a wide run would start that many transfers through one network interface at once. With the defaults, up to 32 targets are in progress but at most 10 are copying; the others carry on connecting, launching and waiting meanwhile. The copy limit covers every copy the process makes, across all targets.

Both limits are subject to the edition caps in Licensing.

Where copied files go on the target

With Copy app to target (-c), the program is copied:

• to the same path it has on this computer, if that file already exists on the target at that path (it is then only replaced if Force copy / -f or -v says so); otherwise
• into the target’s Windows folder (%SystemRoot%).

Additional files (-add / Additional Files) are placed beside the program on the target; a folder is copied with its contents and subfolders, under a folder of the same name.

Clean-up

After the program exits, PPExec deletes every file this run put on the target, and any folders that were created only to hold them. It never deletes a file that was already there, even if -f or -v replaced it. Files are left in place when:

• -cnodel is given (command line only), or
• the run did not wait for the program (Don’t wait for exit / -d) - the program is still running and may need them.

The service itself is always stopped and removed.

Service names

By default each target’s temporary service is named PPExec-<process id>-<this computer's name>-<random token>, so several runs, from one or many computers, can work on the same target at the same time without interfering. The command line can override this:

• -sname name - use exactly this service name (and name.exe for the file).
• -noname - use the fixed name PPExec.

A fixed name means two runs on the same target at the same time will collide; use it only when you need a predictable name, for example so a script can clean up after an interrupted run.

6 - Using the GUI

Start PPExec from the Start menu or run ppexec-gui.exe. The window has a banner and five tabs:

Whilst the window always starts at the default size, it can be resized and maximised.

6.1 - The Operation tab

Below the fields:

• Status line - the current phase (Idle, connecting, copying, installing, launching, waiting, done).
• Output box - the run’s own output: where it is being logged, the license banner, any edition-limit notice, run-level messages, the closing run summary, and - for a local run - the program’s output. Each remote computer’s own output is on the Execute tab.

The button column:

Closing the window during a run cancels the run safely (though is not recommended); everything logged up to that point is kept.

6.2 - The Computers tab

The list of target computers - empty means run on this computer.

Names are trimmed, a leading \\ is removed, and duplicates are ignored (case-insensitively), whichever button added them. Import adds to the list; Open replaces it.

The Domain… and Browse… pickers both have Select all / Select none and a running “n of m selected” count. If the domain holds more computers than one directory query may return (normally 1,000), the picker says so prominently rather than presenting a partial list as complete.

How Browse finds computers. Browse first asks the network’s browser service for its computer list. On most modern networks that service is disabled and returns nothing, so Browse then sweeps this computer’s own subnet (the 254 addresses around its IPv4 address) for machines answering NetBIOS name queries. The picker tells you when the sweep was used. The sweep only finds computers that are on, on this subnet, and have NetBIOS over TCP/IP enabled - use Domain…, Add… or Import… for anything else.

6.3 - The Filter tab

“Define which devices to run the Application on.” Tick a row to use it; a run proceeds on a computer only if it meets every ticked row. With nothing ticked, every computer qualifies.

What each criterion means is described in full in Target filters.

The Open Filter… and Save Filter… buttons read and write a .flt file (see .flt files), the same format the command line’s -loadfilter reads - so a filter built here can be used in scripts unchanged. Open Filter… replaces the whole tab. If the file names an OS version, language or service pack that is not in this tab’s lists (the text format accepts any build number, for example), that row is left unticked and a message tells you; run such a filter with ppexec.exe -loadfilter to use it exactly as written.

6.4 - The Settings tab

Run options

Run elevated and Run limited are ignored when Run as Local System is ticked - Local System is its own account.

Paths

Registration (read-only): Username, Serial, Edition and Support until for this machine’s license, plus the Register… button (see Registering).

Settings take effect when Run is pressed. They are kept for the rest of the session and can be saved with the Operation tab’s Save….

6.5 - What Run checks

Before starting, Run checks the form and lists every problem at once, then takes you to the first field that needs attention. Nothing is started until all of them are fixed:

• Application is filled in.
• If Password is filled in, User is too.
• Execution Timeout is a whole number (or blank).
• Every Additional Files entry exists on this computer.
• Run elevated and Run limited are not both ticked.
• Connection timeout is blank or a whole number; Concurrent sessions is blank or a whole number of 1 or more; Concurrent copies is blank or a whole number from 1 to 32.
• Every ticked Filter row has what it needs (a registry key, a drive and size, a product name, a file path, a process or service name, a domain name where the operation names one, a whole number of hours, and a value wherever the chosen comparison needs one).

An empty computer list is not a problem - it means “run on this computer”.

6.6 - The Execute tab

Clicking Run adds the Execute tab and switches to it. It stays for the rest of the session, so the last run can still be read after it finishes.

Computers in this run lists every computer from the start, with:

Log for the selected computer shows that computer’s messages and program output. Until you click a row, the view follows the run (the first computer to start, then the next as each finishes); click any row to read its log.

The GUI shows a program’s output but does not send it keyboard input: a program that waits for input waits until it times out. For an interactive session with a single computer (a remote command prompt, for example), use ppexec.exe - see Interactive sessions.

7.1 - Syntax

ppexec [\\computer[,computer2,...] | \\* | @file] [options] <app> [app arguments]

• Targets come first, if any:
  • \\name or \\name1,name2,name3 - a comma-separated list (no spaces).
  • @file - read computer names from a text file, one per line.
  • \\* - every server the domain’s browser service reports (often empty on modern networks; prefer @file).
  • Nothing - run on this computer.
• Options come next. Each starts with -, -- or /, and names are not case-sensitive (-filter, --filter and /FILTER are the same). If an option is given twice, the first one counts.
• The program is the first word that is not an option. Everything after it is passed to the program as its arguments, so PPExec options must come before the program name. Quote the program path if it contains spaces.

The same computer may not be listed twice in one run (names are compared case-insensitively).

Running ppexec with no arguments, or ppexec -?, prints the built-in usage summary.

7.2 - Option reference

Credentials

Account and privileges

-h, -l and -s cannot be combined with each other (except that -s overrides -h).

Execution

Priority

The last one given wins.

Parallel runs

Copying files to the target

Target filter

Remote connection and service

See Service names before using -sname or -noname.

Logging

Every run is logged automatically (see Log folders); these add extra destinations.

-accepteula is accepted and ignored, for compatibility with scripts written for similar tools.

7.3 - What you see

Every execution of ppexec.exe - a run, a help request or a command-line mistake - begins with the banner and the license lines. A run then names its log folder:

PPExec V1.0.0: Parallel Processing Exec - © Emerita Codeworks 2026
==================================================================

Licensed to   : Company Ltd (Enterprise Edition - Unlimited devices for named company)
Support until : 26 September 2027

Logging to    : C:\Users\jo\AppData\Local\Emerita\PPExec\Logs\Log_2026-09-26_10-15-02

• Local and serial runs then print each step and the program’s own output as it happens, ending with a line such as setup.exe returned 0 (0x00000000).
• Parallel runs (-par with more than one computer) show a three-line live display - overall progress, how many workers are busy, and the last few computers to finish - and then an execution summary:

  === EXECUTION SUMMARY ===
  Total computers: 40
  Successful: 38
  Failed: 2
  
  Performance:
    Average execution time: 5210ms
    Fastest: 2480ms (WS014)
    Slowest: 11873ms (WS031)
  
  Failed:
    ...

• Each computer’s full output is in its own file in the log folder.

Press Ctrl+C (or Ctrl+Break) to stop a run. PPExec stops as soon as it can, computers not yet started are left untouched, and PPExec exits with -11. This applies in an interactive session too: Ctrl+C ends the session rather than interrupting a command inside it (see below).

7.4 - Interactive sessions

When a run has exactly one target, ppexec.exe behaves like PsExec: the program’s output appears as it is written, and what you type is sent to the program’s standard input. Starting a command interpreter therefore gives you a remote command prompt:

C:\> ppexec \\SERVER01 cmd.exe
...
Starting cmd.exe on \\SERVER01...
Console channels secured (Kerberos, encrypted)

Microsoft Windows [Version 10.0.26200.9550]
(c) Microsoft Corporation. All rights reserved.

C:\Windows\System32>hostname
SERVER01

C:\Windows\System32>exit
cmd.exe returned 0 (0x00000000)

The same applies to a local run through the PPExec service (-s with no target computer), so ppexec -s cmd.exe from an elevated prompt gives a command prompt running as Local System.

Typing. Input is sent a line at a time, when you press Enter; the line is edited locally until then (Backspace, arrow keys and so on). What you type is encrypted on its way to the target, as the program’s output is on its way back.

Ending the session. Leave it the way the program expects - exit for cmd.exe, for example. You can also:

Piped and redirected input. Input does not have to come from the keyboard. Anything piped or redirected into ppexec is sent to the program, and the end of that input ends the program’s input, as Ctrl+Z does:

ppexec \\SERVER01 cmd.exe < C:\Scripts\collect.cmd

type answers.txt | ppexec \\SERVER01 C:\Tools\setup.exe

When no input is sent. The program receives no input when:

• the run has more than one target (serial or parallel): as one keyboard cannot type into several programs at once.
• it is run with -d (don’t wait), since PPExec is not connected to the program once it has started.
• it is run with -i (interactive desktop): the program’s window is on the target’s desktop, and it is used there, not through PPExec.
• it is started from the GUI (see the Execute tab).

Things to know.

• A program that reads its input from a pipe may print each line it reads, so a command can appear twice. PPExec drops that repeat when it can recognise it; a second copy that remains is harmless.
• Programs that draw full-screen, react to single key presses, or hide what you type (text editors, some password prompts) do not work well interactively. The remote program has no console of its own, only its standard input and output. Give such programs their answers as options or redirected input instead.
• Characters are sent in this console’s code page. If the target uses a different one, accented and other non-ASCII characters may appear wrong on either side; chcp on both ends shows the code page in use.

7.5 - Examples

Run a command on one remote computer as the current user:

ppexec \\SERVER01 ipconfig /all

Open an interactive command prompt on a remote computer (see Interactive sessions):

ppexec \\SERVER01 cmd.exe

Run a batch of commands on a remote computer from a local file:

ppexec \\SERVER01 cmd.exe < C:\Scripts\collect.cmd

Run as a specific account, prompting for the password:

ppexec \\SERVER01 -u Company\admin cmd /c dir C:\

Read the password from a file and delete the file afterwards:

ppexec \\SERVER01 -u Company\admin -p@ C:\secure\pw.txt -p@d hostname

Copy an installer to 200 computers listed in a file, 25 at a time, and run it silently as Local System with a 10-minute limit each:

ppexec @C:\lists\workstations.txt -par 25 -s -c -to 600 C:\Packages\agent-setup.exe /quiet

Copy a program together with its support files:

ppexec \\SERVER01,SERVER02 -c -add "C:\Tool\tool.dll;C:\Tool\config" C:\Tool\tool.exe --scan

Only touch 64-bit servers that have been up for less than two days and have the Print Spooler running:

ppexec @servers.txt -par 16 -filter "arch=x64; oslevel=server; uptime<48; service:spooler running" C:\Tools\check.exe

Use a filter saved from the GUI:

ppexec @servers.txt -loadfilter C:\Filters\win11-x64.flt -c C:\Tools\check.exe

Show a program on the logged-on user’s desktop of a remote machine:

ppexec \\WS042 -s -i notepad.exe

Start a long-running program without waiting:

ppexec \\SERVER01 -d C:\Tools\monitor.exe

Run locally as Local System (from an elevated prompt):

ppexec -s cmd /c whoami

Open an interactive command prompt running as Local System on this computer (from an elevated prompt):

ppexec -s cmd.exe

8 - Target filters

A filter decides which computers a run is allowed to touch. It is built on the GUI’s Filter tab, or written as text for -filter / -loadfilter - the two are interchangeable.

8.1 - How filters behave

• Every criterion must hold. A computer that fails any one is skipped.
• Checked on the target itself, by the PPExec service, so it works even where Remote Registry is disabled. For a local run, PPExec checks this computer the same way.
• Checked before anything else is copied. Only the service host has been copied at that point, and it is removed as usual.
• Skipped is not failed. A computer that does not match reports Filtered (exit code -12) with the reasons it failed, is counted separately in the summary, and does not decide a multi-computer run’s exit code. Only when every computer was filtered out is the run’s own exit code -12, since nothing ran at all.
• Can’t check means doesn’t qualify. If the service cannot be asked (for example, a broken connection), the program is not run there, and that computer is reported as a failure, not as Filtered. A criterion that cannot be evaluated (a registry key that cannot be read, say) does not match.

8.2 - Writing a filter as text

Criteria are separated by semicolons:

-filter "arch=x64; oslevel=server; uptime<48"

Each criterion has the form

name[:subject] operator [operand]

• Spaces around the operator are optional: uptime<48 = uptime < 48.
• Names, operators and keywords are not case-sensitive.
• A subject containing spaces must be quoted with ' or ". Single quotes are easiest, since the whole filter is usually already inside double quotes: file:'C:\Program Files\App\a.dll' exists.
• Comparisons (<cmp>) are =, <> (or !=), <, >, <=, >=.
• Keyword criteria also accept the value without =: oslevel server means oslevel=server.

8.3 - Criteria reference

8.4 - Examples

os >= 'Windows 11 23H2'
os >= 10.0.22631; arch = x64
oslevel = server; domain is Company
lang = 'English (any)'
reg:'HKLM\SOFTWARE\Company\Agent!Version' < 4.2
reg:HKLM\SOFTWARE\Company notexists
disk:C: >= 5GB
software contains 'Microsoft Office' version >= 16.0
software isnot 'Company Agent'
file:'C:\Program Files\Company\agent.exe' < 4.2.0.0
process:setup.exe notrunning
service:wuauserv running
reboot notpending; user nobody
uptime < 168

9.1 - Computer list files

Plain text, one computer name per line. Used by @file on the command line and by the GUI’s Import… / Open… (which also accept comma-separated names). Save… on the Computers tab writes this format, so lists move freely between the GUI and scripts. A UTF-8 byte-order mark is accepted.

SERVER01
SERVER02.Company.com
WS042

9.2 - Job files (.ppe)

Written by the GUI’s Save… and read by Open… on the Operation tab. A .ppe holds the Operation, Settings and Filter tabs as plain text, so it can be read, edited, compared and kept under version control:

# PPExec settings - Passwords are not saved for security reasons.
version = 1

[operation]
app = C:\Packages\agent-setup.exe
additional_files = C:\Packages\agent.cfg; C:\Packages\certs
args = /quiet
user = Company\deploy
working_dir =
timeout = 600

[settings]
run_as_local_system = yes
interactive = no
copy_app = yes
dont_wait = no
run_elevated = no
run_limited = no
priority = normal
connect_timeout = 30
concurrent_sessions = 25
concurrent_copies = 10
force_copy = no
service_binary_path =
remote_log_path =
local_log_path =
target_share =

[filter]
arch = x64
uptime < 48

• Lines starting with # are comments.
• Yes/no values accept yes/no, true/false, on/off, 1/0.
• priority is one of low, belownormal, normal, abovenormal, high, realtime.
• The [filter] section is exactly the .flt format below.
• The password is never saved. Opening a file leaves the Password field as it was.
• The computer list is not included; save it separately from the Computers tab.
• Opening a file replaces the form. Anything in the file that could not be applied - an unknown key, an unreadable value, a filter entry the Filter tab cannot display - is listed in a message rather than silently dropped. A file that cannot be read at all changes nothing.

9.3 - Filter files (.flt)

Written by Save Filter…, read by Open Filter… and by ppexec.exe -loadfilter. One criterion per line, in exactly the syntax of -filter; # starts a comment:

# PPExec filter settings.
arch = x64
oslevel = server
reg:'HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion!CurrentBuild' >= 19045
file:'C:\Program Files\App\agent.dll' exists
uptime < 48

Any line can be pasted into -filter and back.

9.4 - Log folders

Every run, from either front-end, writes a folder of its own:

%LOCALAPPDATA%\Emerita\PPExec\Logs\Log_<yyyy-mm-dd>_<hh-mm-ss>\
    SERVER01.log
    SERVER02.log
    PPExec.log
    status.csv

status.csv has the same columns as the GUI’s Execute list:

Computer,Status,Exit,Time
SERVER01,Successful,0,2.5s
SERVER02,Failed,-8,8.0s
SERVER03,Filtered,-12,1.1s

Status is one of Successful, Failed, Filtered, Cancelled or, if a computer never reported back at all, Unreported. A local run’s status.csv has the header only.

Logs are written as the run goes, so a cancelled or interrupted run still leaves everything up to that point (status.csv is written only when the run ends). If the log folder cannot be created, PPExec says so and runs anyway. PPExec never deletes old log folders - remove them yourself when no longer needed. In the GUI, Logs opens the log root folder.

9.5 - The run summary

Each run ends with a summary in PPExec.log (and in the GUI’s output box):

===== PPExec run summary =====
Application:   agent-setup.exe /quiet
Ran as:        Company\deploy
Started:       2026-09-26 10:15:02
Finished:      2026-09-26 10:17:44
Elapsed:       2m 42.1s
Computers:     40, up to 25 at once
  Successful:  37
  Failed:      1
  Filtered:    2 (did not meet the filter)
Fastest:       WS014 (2.5s)
Slowest:       WS031 (11.9s)
Result:        exit code -8
Log folder:    C:\Users\jo\AppData\Local\Emerita\PPExec\Logs\Log_2026-09-26_10-15-02

Failed:
  WS022                exit code -8: could not copy agent-setup.exe to \\WS022\ADMIN$

Computers the run never reached (cancelled) are counted as Not run. Fastest/Slowest appear only when more than one computer ran, and the Failed: section only when something failed.

10.1 - Codes

On success, PPExec’s exit code is the exit code of the program it ran. PPExec’s own failures use the negative codes below.

10.2 - Runs on multiple computers

A run on many computers still exits with a single code:

• Parallel runs (-par n with more than one computer, or the GUI with Concurrent sessions above 1): the first non-zero code in list order, or 0 if every computer succeeded. Filtered computers are ignored, unless every computer was filtered (then -12).
• Serial runs (the command-line default): the code of the last computer that was started.

So a serial run whose earlier computers failed can still exit 0. When you need to know whether every computer succeeded, read status.csv in the run’s log folder, or use -par so that any failure is reflected in the exit code.

10.3 - Using exit codes in scripts

Command Prompt / batch:

ppexec @servers.txt -par 20 -c C:\Tools\check.exe
if %ERRORLEVEL% EQU 0 (
    echo All computers succeeded.
) else if %ERRORLEVEL% EQU -12 (
    echo No computer met the filter.
) else (
    echo Failure: %ERRORLEVEL%
)

PowerShell:

& ppexec.exe '@servers.txt' -par 20 -c C:\Tools\check.exe
switch ($LASTEXITCODE) {
    0       { 'All computers succeeded.' }
    -14     { 'Not licensed.' }
    default { "Failure: $LASTEXITCODE" }
}

# Per-computer results from the newest log folder:
$log = Get-ChildItem "$env:LOCALAPPDATA\Emerita\PPExec\Logs" -Directory |
       Sort-Object Name | Select-Object -Last 1
Import-Csv (Join-Path $log.FullName 'status.csv') |
       Where-Object Status -eq 'Failed'

In PowerShell, quote @file arguments ('@servers.txt'), because @ has a meaning of its own there.

11 - Troubleshooting

For more detail on any failure, open the run’s log folder (GUI: Logs). The <computer>.log for each failed computer ends with the reason. For service-side diagnostics, add a Remote log path / -rlo.

12 - Security notes

• Passwords are never written to disk by PPExec. They are not saved in .ppe files. At the command line, it is preferable to use the interactive prompt (give -u without -p) or -p@ file -p@d over -p password, which is visible in the process list and in command history.
• Signed binaries only. PPExec verifies its own digital signature before every run, and the service host’s before sending it to any target. A modified or unsigned file is refused rather than run with administrator rights across your network.
• Nothing left behind. Each target’s temporary service is removed after the run, along with the service host and - unless you ask otherwise - every file the run copied.
• Filters are checked before copying, so computers you did not mean to touch receive nothing but the temporary service host, which is removed. (We do not use the RemoteRegistry service as this is disabled by default on newer Windows builds)
• Unique service names (the default) prevent one run from interfering with another on the same target.
• Realtime priority (-realtime) can make a target unresponsive; use it only when you understand the consequences.

13 - Appendix: quick reference

GUI ↔ command line

Windows releases known to the OS version filter

Windows NT 4.0 · Windows 2000 · Windows XP · Windows XP x64 / Server 2003 · Windows Vista · Windows Vista SP1 / Server 2008 · Windows Vista SP2 / Server 2008 SP2 · Windows 7 / Server 2008 R2 · Windows 7 SP1 / Server 2008 R2 SP1 · Windows 8 / Server 2012 · Windows 8.1 / Server 2012 R2 · Windows 10 1507 · Windows 10 1511 · Windows 10 1607 / Server 2016 · Windows 10 1703 · Windows 10 1709 · Windows 10 1803 · Windows 10 1809 / Server 2019 · Windows 10 1903 · Windows 10 1909 · Windows 10 2004 · Windows 10 20H2 · Windows 10 21H1 · Windows 10 21H2 · Windows 10 22H2 · Server 2022 · Windows 11 21H2 · Windows 11 22H2 · Windows 11 23H2 · Windows 11 24H2 / Server 2025 · Windows 11 25H2 · Windows 11 26H2

Any other release can be given by its version number, e.g. os >= 10.0.26200.

Exit codes at a glance