List running emulated PET sessions (name, model, pid, monitor port).

Boot a fresh emulated PET (headless, warp). Models: pet2001-4k, pet2001, pet3032, pet4032, pet8032, pet8296. Optionally attach a d64/d80/d82 disk image.

Attach to a running PET session, or boot one (headless, warp) if none exists. Idempotent; "started" reports which happened.

Stop a running PET session (the only one if name is omitted).

Reset the PET (soft, or hard power-cycle). Leaves the machine running.

The session and whether the machine is running or stopped right now. state is answered by the session daemon's own tracking (no emulator traffic); "unknown" without a daemon. Also reports the loaded program and any source files changed since it was loaded (stale binary!).

Read the PET screen as plain text. This is the PREFERRED way to see program output — faster and more reliable than screenshots for AI use. Graphics decode to Unicode glyphs; style="ascii" restores the legacy conservative mapping.

Read the raw screen-code matrix (rows x cols of ints) — exact values for checking glyphs without decoding ambiguity.

Save a PNG screenshot. Prefer pet_screen_text for reading output; use this only when pixel-level appearance matters. scale gives an integer nearest-neighbour upscale (small PET screens read better at 2-3x).

Read emulated memory. addr accepts $hex, 0xhex, decimal, or a symbol from the loaded label file. Returns hex-encoded bytes plus "bytes" as a decimal int array.

Search memory for a byte pattern (values: one or more $hex/decimal bytes). Returns match addresses; "truncated" is true when limit clipped the list. Does not disturb run/stop state.

Write bytes to emulated memory. addr accepts $hex/0xhex/decimal/symbol.

Read CPU registers. PC is annotated with the nearest symbol when a label file is loaded.

Set a CPU register (e.g. PC, A, X, Y). value accepts $hex/0xhex/decimal.

Set a breakpoint at an address or symbol. Machine keeps running; use pet_wait_break to block until it fires.

List breakpoints/watchpoints with hit counts.

Remove a breakpoint/watchpoint by id.

Remove ALL breakpoints (exec checkpoints); watchpoints are kept. Checkpoints persist across pet_run/rebuilds — clear stale ones or duplicates accumulate.

Remove ALL watchpoints (load/store checkpoints); breakpoints are kept.

Set a watchpoint on a memory range (default: both load and store).

Execute N instructions. The machine STAYS STOPPED afterwards; use pet_continue to resume.

Run until the current subroutine returns. Machine stays stopped.

Resume execution after a breakpoint/step.

Run until an address/symbol is executed count times; machine stays stopped there. count>1 = deterministic frame stepping on a loop label. On timeout: raises with the machine LEFT RUNNING and the checkpoint removed.

Block until TEXT appears on the screen. A timeout returns {"fired": null, "screen": ...} (not an error) so you can inspect what the program actually displayed.

Block until the byte at addr equals the value ($hex/decimal accepted).

JSR one routine in isolation (fake return address on the stack, optional A/X/Y on entry) and stop at its RTS — the unit-test primitive: poke inputs, call, then assert registers/memory. Machine ends STOPPED on success, RUNNING on timeout.

Block until a breakpoint/watchpoint fires; reports checkpoint id, PC, and registers. Machine is left stopped when it fires. On timeout the machine is LEFT RUNNING (your checkpoints remain set) and the result is {"fired": null, "machine": "running", ...} — data, not an error.

Assemble 6502 source (ca65 syntax) to a .prg + VICE label file.

Package a .s/.bas/.prg into an artifact any VICE user can run: a .prg, or (when output ends in .d64/.d80/.d82) a disk image whose first file is the program so xpet out.d64 autostarts it. Returns the exact run command in "run".

Build/tokenize a .bas/.s/.prg as needed, then load and RUN it on the running PET. Registers assembly symbols on the session automatically.

Load a .prg via autostart (optionally without RUN); optionally register a VICE label file for symbolic debugging.

Type BASIC program text into the running PET via the keyboard (keywords may be upper or lower case; each line ends with \n). Set run=true to type RUN afterwards.

Type text into the running PET's keyboard buffer (\n = RETURN). Buffered keys never touch the live key-down state — games reading $97 need pet_key_hold.

Hold KEY down for N game ticks by re-poking $97 before each one, running to the frame anchor at (label or address executed once per tick) between pokes; the machine ends STOPPED there. KEY is one character or 'space'. BASIC 4 models only ($97 holds a matrix index on BASIC 2).

Create a blank d64/d80/d82 disk image.

List the directory of a disk image.

Copy a host file onto a disk image.

Copy a file off a disk image to the host.

Attach a disk image to the running PET and LOAD+RUN its first file.

Identify the loaded ROM set (names + content hashes).

Disassemble live memory with ROM + session symbol annotations. start accepts $hex/0xhex/decimal or a symbol (e.g. CHROUT).

Run a declarative YAML test (boots its own fresh PET; see spec §8).

Run every example-program directory (program + expect.txt) as a test.