unidecompiler-cli

unidecompiler-cli is the command-line host for installed unidecompiler frontend plugins. It discovers plugins through the unidecompiler.frontends entry-point group and uses the public DecompilerEngine facade.

Install the CLI and one or more frontend packages:

python -m pip install unidecompiler-cli unidecompiler-plugin-python-pyc

Run unidecompiler --help for command-line usage.

Progress is disabled by default so ordinary output remains clean for shell pipelines. Enable the single-line two-level progress bar explicitly with --progress (TTY auto mode) or --progress always; it is written only to stderr. Use --progress never to make the disabled behavior explicit.

Use -o/--output to write one successful artifact to a file, or --output-dir to export every successful artifact from a batch. Directory exports use sanitized basenames and never overwrite an existing file; these options leave stdout empty and report the destinations on stderr:

unidecompiler sample.pyc --output sample.pse
unidecompiler samples/ --output-dir decompiled/
unidecompiler samples/ --format ast-json --output-dir ast/

For a VS Code navigation sidecar, opt in explicitly and provide both paths. The sidecar is written after the pseudocode file and is never generated by a normal export. It is available only for one pseudocode --output export, not for --output-dir or --format ast-json:

unidecompiler sample.pyc \
  --output sample.pse \
  --vscode-metadata sample.pse.unidec.json

The sidecar contains the exported text's UTF-8 SHA-256, UTF-16 source-map offsets, and minimal instruction navigation facts. It does not repeat the pseudocode or include source paths, AST, IR, CFG, diagnostics, or other engine data.

Starter projects are exported through the host-side template package as well:

unidecompiler template frontend MyVM -o ./my-vm \
  --author "Your Name" \
  --description "My bytecode frontend" \
  --requirements "Decode and lift the VM" \
  --suffix .vm --version 1

unidecompiler template gui_plugin MyPanel -o ./my-panel \
  --author "Your Name" \
  --description "A read-only GUI panel" \
  --requirements "Show analysis data"

The same template export is available as an interactive wizard:

unidecompiler template --interactive

The short form is unidecompiler template -i. The wizard only collects template settings and then calls the same host-side exporter; it does not change decompilation or recovery behavior.

Frontend templates can opt into the simulator and AI kit explicitly:

unidecompiler template frontend MyVM -o ./my-vm \
  --author A --description D --requirements R \
  --suffix .vm --version 1 \
  --simulation --ai-guidance \
  --interpreter-source ./vm_interpreter.c \
  --bytecode-sample ./sample.bin \
  --entry-kind symbol --entry-value main

Both options also accept --no-simulation and --no-ai-guidance; they are disabled by default. AI guidance validates the supplied files for size, regular-file status, and likely credentials before copying them.

export-template is accepted as an alias. Template export is atomic and never overwrites an existing destination directory.

The optional simulator command is hosted here, while execution remains in the separate simulator library:

unidecompiler simulate sample.bytecode --function 'Example.run' --args '[1, 2]'

For trusted programs that require functions outside the lifted module, pass a Python environment file. Top-level functions are matched by name, while their stdout and stderr are returned as structured simulation events:

unidecompiler simulate sample.pyc --function main --environment runtime.py