Metadata-Version: 2.4
Name: unidecompiler-cli
Version: 0.2.3
Summary: Command-line host for unidecompiler plugins
Author-email: Wker <1670133844@qq.com>
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/Wker666/unidecompiler
Project-URL: Repository, https://github.com/Wker666/unidecompiler
Project-URL: Issues, https://github.com/Wker666/unidecompiler/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: unidecompiler<0.3.0,>=0.2.2
Requires-Dist: unidecompiler-export<0.3.0,>=0.2.2
Requires-Dist: unidecompiler-simulator<0.3.0,>=0.2.3
Requires-Dist: unidecompiler-symbolic<0.3.0,>=0.2.3
Requires-Dist: unidecompiler-simulation-host-python<0.3.0,>=0.2.2

# 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:

```sh
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:

```sh
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`:

```sh
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:

```sh
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:

```sh
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:

```sh
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:

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

Bounded symbolic execution uses the same opaque frontend query and explores
the recovered generic IR only. `--symbolic` names scalar symbolic parameters;
all other parameters are supplied through `--concrete`:

```sh
unidecompiler symbolic sample.pyc --function add \
  --symbolic '{"left":{"sort":"int"}}' --concrete '{"right":5}'
```

Use `--format text` for a human-readable summary. Exploration is bounded by
`--max-paths`, `--max-steps`, `--max-loop-unroll`, `--max-call-depth`, and
`--solver-timeout-ms`; symbolic sorts are `bool`, `int`, `real`, and `bitvec`
with a positive `bit_width`. JSON output contains each path's constraints,
model, return/raise value, and CFG trace. Non-success statuses such as
`unsupported`, `solver_timeout`, limits, `cancelled`, and `invalid_request`
are returned explicitly and produce a non-zero exit code.

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:

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