Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

CLI Reference

While the Certo Desktop Wrapper provides a comprehensive visual environment for designing and executing your virtual hardware, Certo also ships with a lightweight Command Line Interface (CLI).

The CLI is currently focused on providing quick access to engine tools and schema extraction directly from your terminal.

EMU Tools: certo emu

The emu cli provides direct terminal access to the underlying emulation engine’s utility functions.

Usage

certo emu [OPTIONS] <COMMAND>

Options

  • -h, --help: Prints the help manual for the emu tools.
  • -V, --version: Prints the specific version of the EMU engine currently running under the hood.

Sub-Commands

scan

Initiates the schema extraction engine. You can pass a raw C/C++ header file (.h) or a compiled binary target (.so, .elf) containing DWARF debug symbols.

Usage
certo emu scan [OPTIONS] <TARGET>

The engine will parse the file and automatically generate the JSON-based memory schemas Certo uses to translate system call payloads.

Options
  • --outdir <DIR>: Output directory for scanned schemas. (Default: ui/src-tauri/schemas).
  • --include-host: Include host standard headers (/usr/include).
  • -I, --include <DIR>: Additional include directories for clang (can be specified multiple times).
Example:
certo emu scan ./include/driver_interface.h

package-template

Compile a transport-template source directory into a single self-contained .vhb for the “New from Template” gallery (see Transport Templates). The packager scans the manifest’s headers, embeds the decode schemas, and inlines each <syscall>_template.tcl dump-and-default stub, stamping Meta.kind = "TransportTemplate".

Usage
certo emu package-template [OPTIONS] <DIR>

<DIR> must contain a manifest.json and a tcl/ directory of stubs.

Options
  • --out <PATH>: Explicit output .vhb path.
  • --outdir <DIR>: Output directory when --out is not given. (Default: ui/src-tauri/templates).
  • --include-host: Include host standard headers (/usr/include) when scanning.
Example:
certo emu package-template ui/src/plugins/emu/templates/usb --include-host

The bundled templates are normally produced for you at build time by tools/generate_templates.sh (invoked from tools/init-bundle.sh); run the command directly only when authoring or iterating on a template.

info

Inspect a virtual hardware behavior file (.vhb or .vhbx) without booting the emulation engine. This allows you to check static configurations, structure, and behavior logic beforehand.

Usage
certo emu info [OPTIONS] --vhb <PATH>
Options
  • --vhb <PATH>: Path to the .vhb or .vhbx file.
  • -f, --format <FORMAT>: Output format, either text or json. (Default: text).
  • -v, --verbose: Print expanded details, including raw TCL logic.
Example:
certo emu info --vhb ./behaviors/ethernet.vhb --format json

run

Boot the emulation engine and execute a target command within the simulated hardware environment.

Usage
certo emu run [OPTIONS] --vhb <PATH> [-- <COMMAND> [ARGS]...]
Options
  • --vhb <PATH>: Path to the .vhb or .vhbx file.
  • --pure-virtual: Force strict virtual mode, disabling any fallback to host hardware.
  • -v, --verbose: Stream emulation engine logs alongside the target command output.
Example:
certo emu run --vhb ./behaviors/ethernet.vhb --pure-virtual -- ping -c 3 192.168.1.1

shell

An interactive REPL for building and sending VHB interaction payloads. Loads a VHB project, arms the engine, and drops into a prompt where you can select interactions, set field overrides, and execute them — all without writing a target process or test harness.

The shell is particularly useful for iterating on software_driver_script logic in software driver mode (see Software Driver Mode).

Usage
certo emu shell [OPTIONS] --vhb <PATH>
Options
  • --vhb <PATH>: Path to the .vhb or .vhbx file to load.
  • --software-driver: Enable software driver mode. The engine acts as the software layer and sends payloads to real hardware, returning the hardware’s response. Without this flag the engine runs in hardware driver mode (default).
Shell Commands

Once inside the prompt (emu>), the following commands are available:

CommandDescription
listList all interactions from the loaded VHB, with their type and alias. In software driver mode, Inbound/Outbound labels are shown from the software’s perspective.
select <id>Select an interaction by ID or alias. The prompt changes to emu(<id>)> to confirm the selection.
set <field> <value>Accumulate a field override for the selected interaction. Overrides are injected as TCL variables before the script runs. Certain keys (fd, host, port, flags) also control OS dispatch.
defaultsPrint the software_driver_script for the selected interaction.
sendExecute the selected interaction with all accumulated overrides. Prints the result as JSON: { "fields": {...}, "raw_bytes": [...] }.
resetClear all accumulated field overrides for the selected interaction.
helpPrint the command reference.
exit / quit / ^DExit the shell.
Example: Hardware Driver Mode (inspect interactions)
certo emu shell --vhb ./behaviors/audio_device.vhb

Certo EMU Shell — hardware-driver mode
VHB: ./behaviors/audio_device.vhb
Type 'help' for available commands.

emu> list
  ctl-card-info [Inbound] — card_info_ioctl
  pcm-write [Outbound] — pcm_write

emu> select ctl-card-info
Selected: ctl-card-info

emu(ctl-card-info)> defaults
  (no software_driver_script defined)

emu(ctl-card-info)> exit

Exiting EMU shell.
Example: Software Driver Mode (drive real hardware)
certo emu shell --software-driver --vhb ./behaviors/sensor.vhb

Certo EMU Shell — software-driver mode
VHB: ./behaviors/sensor.vhb

emu> select sensor-read
emu(sensor-read)> defaults
binary format H* "0102030405060708"

emu(sensor-read)> send
{"fields":{},"raw_bytes":[12,0,128,0,0,0,0,0]}