Skip to content

CLI Reference

Ryan Cole edited this page Nov 15, 2026 · 2 revisions

pbeta <command> --help is the authoritative reference. Every command that reads an analysis accepts plain or gzipped JSON (.gz).

Exit codes

repair: 0 every hook resolved, 1 some need review, 2 error. Other commands: 1 means "found something" where the table says so, 2 an error.

Core

Command What it does
analyze <binary> --out <json> Analyze a PE x64 or x86 binary (detected). --pdb adds names, signatures and struct layouts (must match the binary). --type <name> records an extra struct's layout. --functions-from takes boundaries from a Ghidra export.
match --old --new Match and verify every function between two analyses. --json for the full report.
bind --hooks --binary Set placeholder target.build values to the binary's SHA-256. --from limits it to one placeholder; --out writes elsewhere. Exit 1 if nothing was bound.
repair --old --new --hooks Move a hook manifest to a new build. See below.
mappings --old --new Accepted mappings for a build pair (with --store, reviewers' decisions too); every other old function as pending with its reason. Read only.

repair options

Option Meaning
--out Write the repaired manifest.
--new-binary Regenerate a unique pattern for every re-bound hook.
--store Record mappings and review items; honor review decisions.
--earlier <analysis> An older build some hooks are still bound to. Repeatable.
--trial-out Also write a trial manifest for behavioral runs.
--old-trace, --new-trace Scenario traces as behavioral evidence.
--cases Recorded calls, replayed on --new-binary.
--propose Ask the AI Proposer about hooks with no candidate (needs --allow-remote or --replay).
--json Machine-readable output.

Review

Command What it does
review list Open items (--all for decided). Exit 1 if any are open.
review accept <id> --reviewer Accept --candidate <rva>, or --function <rva> with --old-analysis/--new-analysis. --force for a candidate verification rejected.
review reject <id> --reviewer None of the candidates is the counterpart.
review revoke <id> --reviewer Withdraw an accepted mapping; the item reopens.

All take --note and --store (default .pbeta/store.json). See Review Queue.

Output for hooking

Command What it does
host-config --hooks... --out The Hook Host's configuration. --analysis for PDB signatures.
handler-stubs --hooks... --out Handler DLL source with declarations from prototypes. --dll picks one DLL; --force overwrites.
header --hooks... --out hooks.gen.h: each build's RVAs and patterns, looked up by SHA-256.
pattern <binary> --rva Shortest unique byte pattern for a function.

Behavioral evidence

Command What it does
harness-spec --hooks --analysis --out Record spec for the recording hook DLL.
trace-diff --hooks Compare --old/--new scenario traces, or check one --baseline. Exit 1 on any difference.
replay --cases --binary --old-rva --new-rva Replay recorded cases by emulation. --others as a control.

See Behavioral Evidence.

Other

Command What it does
propose --old --new Ask the AI Proposer about unmatched functions. Needs --allow-remote or --replay.
analysis-diff <a> <b> Compare two analyses of the same build (e.g. native vs Ghidra vs PDB). Exit 1 if they disagree.

pbeta-mcp

See MCP Server.

Clone this wiki locally