Skip to content

CLI Overview

ppee-cli is PPEE's headless frontend. It prints any part of a PE file as human-readable text or JSON, patches fields, feeds the similarity database, and runs as an MCP server.

Synopsis

ppee-cli [options] <pe-file>
ppee-cli --mcp [--mcp-allow-write]
ppee-cli --help | --version

Options come first and the file comes last. Exactly one input file is accepted per run; to process many files, see batch recipes.

How the options fit together

flowchart TD
    A[ppee-cli args] --> B{--help / --version / --mcp?}
    B -- yes --> Z[print / serve and exit]
    B -- no --> C[Load file]
    C --> D{--set given?}
    D -- yes --> E[Apply edits in order]
    E --> F{--save?}
    F -- yes, all edits OK --> G[Write file or -o PATH]
    D -- no --> H
    F -- no --> H
    G --> H[Analyze selected sections]
    H --> I{--json?}
    I -- yes --> J[JSON document on stdout]
    I -- no --> K[Text report on stdout]

The options fall into four groups:

Group Options Reference
Section filters: choose what to include --headers --dirs --sections --hashes --similarity --imports --exports --basereloc --tls --debug --bound-imports --delay-imports --resources --exception --security --loadconfig --net --richheader --appmanifest --analysis --analysis-deep --strings --all Section filters
Output: choose how it is printed --json --timing Output options
Editing: change the file --set --save -o Editing options · --set address syntax
Behavior and modes --no-similarity --no-update-check --mcp --mcp-allow-write --help --version Behavior options

No filter means everything

If you give no section filter, PPEE behaves as if you passed --all. Once you give one filter, only the sections you name are printed.

stdout, stderr and exit codes

  • stdout carries only the report (text or JSON), so ppee-cli --json … | jq always receives valid JSON.
  • stderr carries diagnostics: edit and save confirmations, warnings, --timing output and update notices.
Exit code Meaning
0 Success
1 Bad usage (unknown option, missing file, more than one file), the file could not be read, the file is not a valid PE, any --set edit failed, or the save failed 
$ ppee-cli notes.txt; echo "exit=$?"
'/home/me/notes.txt' is not a valid PE file
exit=1

Environment variables

Variable Effect
PPEE_JOBS=<n> Number of worker threads. The default is the number of CPUs the process may use, which respects container CPU quotas and affinity masks (see Docker CPU limits)

Platform differences

Behavior Windows Linux Docker
Startup update check Yes (disable with --no-update-check) No No (the image passes --no-update-check)
Signature validity (WinVerifyTrust) in --security Yes "Not available on this platform" Same as Linux
Path encoding Arguments in the ANSI code page; MCP paths as UTF-8 UTF-8 UTF-8
Similarity DB location Next to ppee-cli.exe Next to ppee-cli /ppee/ppee-cli.similarity.db

Next