Commands Reference

bp-ea

This command erases all breakpoints already set.

bp-ea

Available aliases: eab

bp-list

This command lists the breakpoints already set.

bp-list

Available aliases: bpl

Each breakpoint is listed in bp-set syntax — its address specification, its type options, its length, -once, its message, its hit count rule and its condition — so a line pasted after bp-set recreates the breakpoint. A run-to target is marked <run-to target>. Breakpoints made by LOGPOINT, ASSERTION and WPMEM comments are listed after the others, by kind; an assertion also shows how Klive reads its expression (read as:), with every operation in parentheses. What bp-set cannot say goes on an indented second line: <disabled>, the live hit count (hits: 3) of a breakpoint with a condition or a hit rule, and, when relevant, <inactive: unknown label score> or <condition error: …>:

[1]: $8010 -hit *4 -if A == $FF && !ZF
     (hits: 2)
[2]: [code/code.kz80.asm]:12 -if w[score] > 100
     (hits: 0) <inactive: unknown label score>

Logpoints read from LOGPOINT source comments are listed after them, under their own heading, with their source line and address. They are read-only: bp-del and bp-en do not touch them; edit the comment and build again.

bp-del

This command removes a breakpoint.

bp-del <address-spec> [-r] [-w] [-i] [-o] [-c] [-m <mask>] [-v <value>] [-len <bytes>]

Available aliases: bd

A breakpoint an ASSERTION or WPMEM comment created cannot be removed: bp-del says which comment made it. Remove the comment and rebuild, or switch the kind off with as-en -d or wp-en -d.

The address-spec parameter can be

• a 16-bit address (using the number for the address), for example, $120a or 32768;
• an address with a partition (the partition and the address separated with a colon), for example, r1:$32ac (meaning $32ac, provided ROM 1 is paged in) — see Machine-Specific Memory Partitions for the names each machine uses;
• a NextReg write on the ZX Spectrum Next (nr: then the register number), for example, nr:$07 — meaning “stop when Next Register $07 is written”. This is the one breakpoint that does not name a place: it watches a machine event, so it has no address, no partition and no disassembly. Add = and a value to break only on that value, and / and a mask to compare only some of its bits, as in nr:$07=$03/$0f. See NextReg Write Breakpoints;
• a Copper instruction on the ZX Spectrum Next (cu: then a Copper list index, $000-$3FF), for example, cu:$00B — meaning “stop when the Copper completes list instruction $00B”: a MOVE when it is issued, a WAIT when its condition is satisfied. Like nr:, it has no address and no partition. See Copper Breakpoints;
• a sprite attribute write on the ZX Spectrum Next (sp: then a sprite, $00-$7F), for example, sp:$0C — meaning “stop when an attribute byte of sprite $0C is written”, through port $57 or the $35-$39/$75-$79 NextReg mirrors, by the CPU, the DMA or the Copper. Add -attr and a list of attribute bytes (0-4) to watch only those, as in sp:$0C -attr 0,1 or -attr 0-3. Like cu:, it has no address and no partition. See Sprite Attribute Breakpoints;
• a watch symbol (WS: then a build symbol), for example, WS:score -w -len 2 — a memory breakpoint anchored to the symbol rather than to an address, so a rebuild that moves the symbol moves the watched bytes, and it does not stop while the build has no such symbol. This is what the Watch view’s Break on write creates, and how bp-list prints it;
• or a source code line specification, for example, [code/code.kz80.asm]:12

w-add

This command adds a watch expression for a symbol.

w-add [>]<symbol>[:<type>[:<length>]]

Available aliases: w

The watch expression specification format is [>]<symbol>[:<type>[:<length>]] where:

• symbol: A valid identifier (symbol name)
• >: Optional flag. When present, the watch is marked as direct (the IDE will treat the symbol as a direct value/address).
• type: Optional data type (defaults to b if omitted). One of the following:
  • a: byte array (requires length)
  • b: 8-bit number (default)
  • w: 16-bit little-endian number
  • l: 32-bit little-endian number
  • -w: 16-bit big-endian number
  • -l: 32-bit big-endian number
  • f: flag (boolean, zero is false, other values are true)
  • s: string (requires length)
• length: Required for array (a) and string (s) types, must be between 1 and 1024

Examples:

• w-add playerScore - 8-bit value (default type)
• w-add >playerScore - 8-bit value with direct flag
• w-add playerScore:w - 16-bit little-endian value
• w-add playerName:s:32 - 32-byte string
• w-add inventory:a:64 - 64-byte array
• w-add isAlive:f - boolean flag

w-del

This command removes a watch expression by symbol name.

w-del <symbol>

Available aliases: wd

The symbol parameter is the name of the symbol for which the watch expression should be removed.

w-ea

This command erases all watch expressions.

w-ea

Available aliases: wea

w-list

This command lists all defined watch expressions.

w-list

Available aliases: wl

This command displays all defined watchpoints with their symbol names, data types, lengths (if applicable), and resolved addresses/partitions (if the symbols have been resolved after compilation).

bp-en

This command turns a breakpoint already set on or off.

bp-en <address-spec> [-r] [-w] [-i] [-o] [-d] [-c] [-m <mask>] [-v <value>]

Available aliases: bd

The address-spec parameter can be

• a 16-bit address (using the number for the address), for example, $120a or 32768;
• an address with a partition (the partition and the address separated with a colon), for example, r1:$32ac (meaning $32ac, provided ROM 1 is paged in) — see Machine-Specific Memory Partitions for the names each machine uses;
• a NextReg write on the ZX Spectrum Next (nr: then the register number), for example, nr:$07 — meaning “stop when Next Register $07 is written”. This is the one breakpoint that does not name a place: it watches a machine event, so it has no address, no partition and no disassembly. Add = and a value to break only on that value, and / and a mask to compare only some of its bits, as in nr:$07=$03/$0f. See NextReg Write Breakpoints;
• a Copper instruction on the ZX Spectrum Next (cu: then a Copper list index, $000-$3FF), for example, cu:$00B — meaning “stop when the Copper completes list instruction $00B”: a MOVE when it is issued, a WAIT when its condition is satisfied. Like nr:, it has no address and no partition. See Copper Breakpoints;
• a sprite attribute write on the ZX Spectrum Next (sp: then a sprite, $00-$7F), for example, sp:$0C — meaning “stop when an attribute byte of sprite $0C is written”, through port $57 or the $35-$39/$75-$79 NextReg mirrors, by the CPU, the DMA or the Copper. Add -attr and a list of attribute bytes (0-4) to watch only those, as in sp:$0C -attr 0,1 or -attr 0-3. Like cu:, it has no address and no partition. See Sprite Attribute Breakpoints;
• or a source code line specification, for example, [code/code.kz80.asm]:12

The -d option disables the breakpoint.

bp-en and bp-del accept -hit, -log and -if and ignore them, so you can turn a bp-list line into either command by changing only its first word.

bp-set

This command sets a breakpoint.

bp-set <address-spec> [-r] [-w] [-i] [-o] [-c] [-m <mask>] [-v <value>] [-len <bytes>] [-attr <bytes>] [-once] [-log "<message>"] [-hit <spec>] [-if <condition>]

Available aliases: bp

The type options are mutually exclusive: -r watches memory reads, -w memory writes, -i I/O reads and -o I/O writes. With none of them, the breakpoint is an execution breakpoint.

• -m <mask> is the port mask for -i and -o, and the value mask for a nr: breakpoint.
• -v <value> breaks only when that value is written; nr: breakpoints only.
• -c also breaks when the copper writes the register, not only when the CPU does; nr: breakpoints only, and off by default.
• -len <bytes> makes a memory breakpoint (-r or -w) watch a range of that many bytes from its address, 1 to 65536; the range may not run past $FFFF. The length is part of the breakpoint’s identity, so bp-del and bp-en need it too.
• -attr <bytes> makes a sp: breakpoint watch only those attribute bytes (0-4, as a list with ranges: 0,1, 0-3, 1,3-4); without it, all five. It is not part of the identity: bp-set on the same sprite with another list updates the breakpoint.
• -once makes a one-shot breakpoint: it is removed the first time it stops the machine, and it is never saved with the project. With -hit or -if, “the first time” means the first time its own rule and condition let it stop, so -once -hit 10 stops on the 10th hit and is then gone. A logpoint never stops, so it cannot be a one-shot. bp-set without -once makes it a regular breakpoint again. See One-Shot Breakpoints.
• -log "<message>" makes the breakpoint a logpoint: instead of stopping, it writes the message to the Log pane and continues. Write the message in double quotes (\" and \\ inside it), before -if. See Logpoints for the message syntax. Errors are reported with a caret, as for a condition.
• -hit <spec> sets a hit count rule: 10 (or =10) stops on the 10th hit only, >10 after it, >=10 from it on, <10 before it, <=10 up to it, and *10 on every 10th hit. The number runs from 1 to 65535. A hit is counted only when the condition, if any, is true.
• -if <condition> sets a condition: the machine stops only when it is true. -if must be the last option, because everything after it to the end of the line is the condition, taken verbatim — no quoting needed. A condition that is one double-quoted string is unquoted, so -if "A == 1" works too. See Conditions and Hit Counts for the language.

bp-set states the whole breakpoint: setting one that already exists replaces its condition, hit rule and message, and leaving out -if, -hit or -log removes them — so bp-set without -log turns a logpoint back into a breakpoint. The hit counter is kept.

bp-set $8000 -if A == $FF && !ZF
bp-set $9000 -w -hit *4 -if VAL == $AA
bp-set [code/code.kz80.asm]:12 -hit >=10
bp-set $8000 -log "x={A} at {PC:hex16}"
bp-set [code/code.kz80.asm]:42 -log "[LOOP] B={B}" -hit *100
bp-set $8000 -once -hit 3
bp-set $5B00 -w -len 32

A condition that does not parse is refused with its column and a caret under the mistake:

Condition error at column 6: Unexpected '=='; expected a value
  A == == 1
       ^^

A label the last build did not define is a warning, not an error: the breakpoint is set, but it does not stop — and does not count — until a build defines the label.

The address-spec parameter can be

• a 16-bit address (using the number for the address), for example, $120a or 32768;
• an address with a partition (the partition and the address separated with a colon), for example, r1:$32ac (meaning $32ac, provided ROM 1 is paged in) — see Machine-Specific Memory Partitions for the names each machine uses;
• a bank-relative address on the ZX Spectrum Next (the 16K bank, a colon, then + and the offset within that bank), for example, 05:+$0100 — meaning offset $0100 inside 16K bank 5, wherever that bank happens to be paged in. The bank is a 16K bank number in hexadecimal, 00 to 6F, and the offset runs from $0000 to $3FFF. Unlike the partition form above, this breakpoint follows its bank rather than sitting at one Z80 address, which is what makes it useful for code that pages banks in and out. Not available for the -i and -o (I/O) breakpoint types, which watch a port rather than memory;
• a NextReg write on the ZX Spectrum Next (nr: then the register number), for example, nr:$07 — meaning “stop when Next Register $07 is written”. This is the one breakpoint that does not name a place: it watches a machine event, so it has no address, no partition and no disassembly. Add = and a value to break only on that value, and / and a mask to compare only some of its bits, as in nr:$07=$03/$0f. See NextReg Write Breakpoints;
• a Copper instruction on the ZX Spectrum Next (cu: then a Copper list index, $000-$3FF), for example, cu:$00B — meaning “stop when the Copper completes list instruction $00B”: a MOVE when it is issued, a WAIT when its condition is satisfied. Like nr:, it has no address and no partition. See Copper Breakpoints;
• a sprite attribute write on the ZX Spectrum Next (sp: then a sprite, $00-$7F), for example, sp:$0C — meaning “stop when an attribute byte of sprite $0C is written”, through port $57 or the $35-$39/$75-$79 NextReg mirrors, by the CPU, the DMA or the Copper. Add -attr and a list of attribute bytes (0-4) to watch only those, as in sp:$0C -attr 0,1 or -attr 0-3. Like cu:, it has no address and no partition. See Sprite Attribute Breakpoints;
• a watch symbol (WS: then a build symbol, with -r or -w), for example, WS:score -w -len 2, as described under bp-del;
• or a source code line specification, for example, [code/code.kz80.asm]:12

bp-reset-hits

This command resets the hit counter of one breakpoint, or of every breakpoint when you give no address specification.

bp-reset-hits [<address-spec>] [-r] [-w] [-i] [-o] [-m <mask>] [-v <value>]

Available aliases: bprh

Hit counters also start again from zero whenever the machine restarts — Start after Stop, Restart, or a reset. Pausing and resuming keeps them, and so does editing a breakpoint’s condition or hit rule.

lp-en

This command switches logpoint groups on and off.

lp-en [<group> ...] [-d]

Available aliases: lpe

Without groups, it switches every logpoint on (or, with -d, off). With groups, only the named groups log (or, with -d, the named groups stop logging and the rest keep logging). Group names are not case-sensitive; a logpoint without a [GROUP] is in DEFAULT. The setting is saved with the project, and a logpoint logs only when both it and its group are enabled.

lp-en -d
lp-en SPRITES LOOP
lp-en LOOP -d

as-en

This command switches the breakpoints of DeZog ASSERTION source comments on or off for the project.

as-en [-d]

Available aliases: ase

Without -d it switches them on, with -d off. They are on by default; the setting is saved with the project and takes effect at once, without a rebuild. See ASSERTION and WPMEM comments.

wp-en

This command switches the watchpoints of DeZog WPMEM source comments on or off for the project.

wp-en [-d]

Available aliases: wpe

It works like as-en.

lp-groups

This command lists every group the current logpoints name, whether it logs, and how many logpoints it holds. It also says whether ASSERTION and WPMEM comments are switched on.

lp-groups

Available aliases: lpg

close

Use this command to close the folder currently opened in the IDE.

close

clh

Use this command to clear the interactive command prompt history.

clh

cls

Use this command to clear the interactive command output.

cls

compile

This command compiles the code, provided a Klive project is loaded, and a build root file is selected.

compile

Available aliases: co

crd

This command creates an empty disk file: a DSK file for the ZX Spectrum +3 models (and compatible), or a blank, formatted TR-DOS disk (.trd) for the Pentagon 128’s Beta 128 interface.

crd <disk-type> <disk-name> [<disk-folder>] [-p]

These are the arguments of the command:

• disk-type: One of these supported formats:
  • ss: Single-sided CPC
  • ds: Double-sided CPC
  • sse: Single-sided Extended CPC
  • dse: Double-sided Extended CPC
  • trd80ds: TR-DOS, 80 tracks, double-sided (640K)
  • trd40ds: TR-DOS, 40 tracks, double-sided (320K)
  • trd80ss: TR-DOS, 80 tracks, single-sided (320K)
  • trd40ss: TR-DOS, 40 tracks, single-sided (160K)
• disk-name: The name of the disk file (the .dsk or .trd extension is added automatically)
• disk-folder: An optional folder in which the new disk file is created. The folder must exist.
• -p: Creates the disk file within the currently opened project folder (under disks).

debug

This command compiles the code. If the compilation is successful, it injects the code into the current virtual machine and starts it in debug mode. This command requires that a Klive project be loaded.

debug

Available aliases: rd

Note: The command will start (or restart) the virtual machine.

dis

This command disassembles the specified memory section and displays the disassembly result in a new document pane.

dis <start> <end> [-d] [-c] [-lc]

It requires a start and an end (inclusive) address. Use the -d option if you want the disassembly to display addresses, numbers, and instructions with decimal numbers. The -c option turns on the concise mode (disassembled bytes are omitted from the output). By default, labels do not end with colons; however, you can turn on this mode with the -lc option.

Note: This command does not support bank operations (yet). It can disassemble only the currently paged 64K memory.

em-debug

This command starts the current machine in debug mode.

em-debug

Available aliases: :d

em-out

This command executes all instructions until it exits the current subroutine and pauses at the instruction following the subroutine call. It expects the machine to be paused when this command is issued.

em-out

Available aliases: :o

Note: If the function returns unconventionally (for example, popping the return address and jumping to it, etc.), this command may not stop the machine.

em-pause

This command pauses (suspends) the current machine.

em-pause

Available aliases: :p

em-restart

This command restarts (stops, and then starts) the current machine.

em-restart

Available aliases: :r

em-start

This command starts the current machine.

em-start

Available aliases: :s

em-sti

This command executes the next Z80 instruction from the current PC (Program Counter) and pauses the machine again. It expects the machine to be paused when this command is issued.

em-sti

Available aliases: :

em-sto

This command executes the next Z80 instruction from the current PC (Program Counter). If that instruction is a function call or a block instruction, it executes the entire subroutine or block operation before pausing again. It expects the machine to be paused when this command is issued.

em-sto

Available aliases: .

Note: If the function call does not return to the instruction following the current instruction at the PC address, the machine won’t pause again (unless it reaches a breakpoint).

em-stop

This command stops the current machine.

em-stop

Available aliases: :h

expc

This command compiles the code and exports it according to the specified options.

expc filename [-n name] [-f format] [-as] [-p] [-c] [-b border]
  [-sb] [-addr address] [-scr screenfile]

These are the input arguments and options:

• filename: The name of the exported file
• `-n: The name of the program in the exported file. This name will be displayed during the LOAD operation.
• -f: The file format to use:
  • hex: Intel HEX format
  • tzx: TZX file format
  • tap: TAP file format
• -as: Autostart the exported code after loading it
• -p: Add a PAUSE statement into the loader (before starting the loaded code)
• -c: Add a clear statement to keep the end of the BASIC code before the start address of the exported code
• -b: Specifies the border color to set when the loader program starts
• -sb: The compiled code may contain multiple segments. If this option is used, the exporter merges all code segments into one (filling up the padding code with zeros). Otherwise, each code segment goes into a separate CODE file.
• -addr: Specifies the start address of the exported code. The exported extracts this information from the compilation result if not specified. However, you can change the inferred address with this option.
• -scr: You can specify a screen file (TAP or TZX format) to load after the autoloader.

Note #1: If the compilation fails, no code will be exported.

Note #2: If you compile code for a ZX Spectrum 128 (or upper) model with multiple bank support, the exporter creates a loader that loads the banks in the compilation (and puts them into the appropriate memory bank) before starting the app.

export-patterns

Use this command on the ZX Spectrum Next to save the 16K of sprite pattern RAM as a .spr file — 64 8-bit patterns, which the sprite editor opens. A 4-bit pattern is half of one of them, so nothing is lost whatever the program uses.

export-patterns [<file>] [-f] [-o]

Available aliases: exppat

A relative path is in the project folder. Without a file the command picks the first free name of pattern-ram.spr, pattern-ram-2.spr, and so on. -f replaces an existing file; -o opens the file in the sprite editor once it is written. The Sprite Inspector’s ⋯ → Export pattern RAM as .spr runs export-patterns -o.

hide-copper

Use this command to close the Copper List.

hide-copper

Available aliases: hcop

hide-history

Use this command to close the Execution History.

hide-history

Available aliases: hhist

hide-disassembly

Use this command to hide the machine code disassembly view.

hide-disassembly

Available aliases: hdis

hide-memory

Use this command to hide the memory contents view.

hide-memory

Available aliases: hmem

inject

This command compiles the code, and if the compilation is successful, it injects the code into the current virtual machine. This command requires that a Klive project be loaded and the virtual machine be paused.

inject

Available aliases: inj

nav

This command navigates to the specified project file (to an optional position). If the file is not open yet, the IDE opens it.

nav projectFile [line] [column] [-r reason]

The projectFile argument is a project file name. When you specify the name, use the full name (including the file extension) relative to the project’s root folder. For example, if your file is in the code folder and named program.zxb, use the code/program.zxb parameter.

You can specify an optional line and column argument to jump to the specified location within the file.

With the -r option, the jump is remembered in the navigation history, so nav-back can return to where you were. reason is what the history list shows as the cause of the jump: definition, outputLink, breakpoint, memoryGoTo, disassemblyGoTo, nexLabel, nexBank, z88Bank, tabSwitch, explorer or command. Without -r, the jump is not remembered.

nav-back

This command goes back to the previous place in the navigation history, like the Back toolbar button.

nav-back

Available aliases: nb

When there is nowhere to go back to, the command says so and does nothing else.

nav-forward

This command goes forward to the next place in the navigation history, like the Forward toolbar button.

nav-forward

Available aliases: nf

nav-history

This command lists the navigation history, newest place first. > marks where you are; each line shows the document, the position in it, and the reason the place was remembered.

nav-history

Available aliases: nh

nav-clear

This command empties the navigation history.

nav-clear

ncp

This command copies a file between the host filesystem and ZX Spectrum Next storage.

ncp to <host-source> <next-destination> [-cim <cim-file>]
ncp from <next-source> <host-destination> [-cim <cim-file>]

Available aliases: next-copy

The command has two directions:

• to: Copies a host file into ZX Spectrum Next storage.
• from: Copies a file from ZX Spectrum Next storage to the host filesystem.

By default, the command uses the current emulator storage. This mode works only when the current machine is ZX Spectrum Next. You can also specify a .cim image explicitly with -cim <cim-file>; this mode does not depend on the current machine type.

The command runs only when the emulator is stopped or not started. It is rejected while the emulator is running or paused, and it does not start, stop, or pause the machine automatically.

If the target is a folder, the command reuses the source file name. Missing target folders are created recursively. If the target file already exists, the command asks for overwrite confirmation before replacing it.

Examples:

ncp to "build/game.nex" "/games/game.nex"
ncp to "build/game.nex" "/games/"
ncp from "/logs/boot.txt" "./boot.txt"
ncp from "/logs/boot.txt" "./logs/"
ncp to "./assets/title.scr" "/assets/" -cim "/tmp/test-card.cim"
ncp from "/logs/boot.txt" "./boot.txt" -cim "/tmp/test-card.cim"

nex-run

This command runs a .nex file on the ZX Spectrum Next, optionally with debugging.

nex-run <nex-file> [-d] [-e]

Available aliases: nexrun

Use -d to start in debug mode, so breakpoints are armed while the program runs.

Use -e to stop on the program’s first instruction. Klive reads the entry point from the NEX header, works out which 16K bank it falls in, and sets a temporary breakpoint there before the file is loaded — so the machine stops the moment NextZXOS hands control to the program, with the entry bank paged in. The breakpoint removes itself when it fires; it is never added to your project or to the file’s annotations. -e turns on debug mode by itself, so you do not need -d with it.

This is the option to use on a NEX you did not write: you do not need to know where its code lives, only that it has to start somewhere. If the entry point is below $4000 — ROM at the moment the program starts, so not part of the file — Klive says so and runs the program without stopping.

The command copies the file into the emulated SD card image — under _klive/, the same folder the build-and-run path uses — and then boots NextZXOS and enters .nexload for it, which is how a NEX is loaded on real hardware too. The machine is stopped first, because the card image is a file the running machine also reads.

Unlike run and debug, this command needs no project: it runs any NEX file you point it at, whether Klive built it or not. It requires the current machine to be ZX Spectrum Next, and reports an error rather than switching machines for you.

The same three actions are available from the Explorer’s context menu on a .nex file, and from the buttons in a NEX file’s document tab.

nex-run "games/demo.nex"
nex-run "games/demo.nex" -d
nex-run "games/demo.nex" -e

zx-snapshot

This command loads a ZX Spectrum snapshot (a .sna, .z80 or .szx file) and debugs or runs it.

zx-snapshot <snapshot-file> [-r | -d]

Available aliases: zxsnap

With no option (or with -d), the snapshot is debugged: the machine starts in debug mode and stops at the snapshot’s program counter before executing that instruction. Use -r to run the snapshot. Use only one option at a time.

The snapshot decides the machine: the command switches to the ZX Spectrum 48K, 128K or +2E/+3E the snapshot needs. With a project open, it refuses a snapshot for another machine type, and keeps the project’s model for a snapshot of the same type. Disks a .szx file links are read and inserted.

The same actions are available from the Explorer’s context menu on a snapshot file, from the buttons in a snapshot’s document tab, from File → Open File…, and by dropping the file onto the Emulator window. See Using ZX Spectrum Snapshots for what Klive can load.

zx-snapshot "snapshots/game.z80"
zx-snapshot "snapshots/game.sna" -r
zxsnap "snapshots/demo.szx" -d

zx-snapshot-save

This command saves the ZX Spectrum 48K, 128K or +2E/+3E as a snapshot.

zx-snapshot-save <snapshot-file> [-f]

Available aliases: zxsave

The file’s extension picks the format: .szx, .z80 or .sna. .szx keeps the whole state; the command lists anything .z80 or .sna cannot hold as warnings, and refuses a state the format would load back differently. An existing file is replaced only with -f.

The machine must be running or paused. A running machine is paused for the capture and runs on afterwards; a paused one stays paused. File → Save Snapshot… does the same after asking for a file. See Using ZX Spectrum Snapshots for what each format keeps.

zx-snapshot-save "snapshots/level3.szx"
zx-snapshot-save "snapshots/level3.z80" -f
zxsave "snapshots/bug.sna"

zx-rzx

This command plays an RZX input recording on the ZX Spectrum.

zx-rzx <rzx-file> [-d] [-s <segment>]

Available aliases: rzx

The recording decides the machine, as a snapshot does (see zx-snapshot). With -d, the machine starts in debug mode and stops at the recording’s first instruction; breakpoints and stepping work while it plays. -s starts at a segment (an embedded snapshot), counted from 1. When the recording ends the machine pauses; a desync pauses it at the instruction that desynced. See Playing and Recording RZX Files.

zx-rzx "recordings/game.rzx"
zx-rzx "recordings/game.rzx" -d
rzx "recordings/longplay.rzx" -s 3

zx-rzx-record

This command starts recording an RZX file from the ZX Spectrum’s current state.

zx-rzx-record

The machine must be a ZX Spectrum 48K, 128K or +2E/+3E, running or paused. A playback that is running or paused is taken over: the recording starts from where it stands.

zx-rzx-stop

This command stops the RZX recording and saves it.

zx-rzx-stop <rzx-file> [-f]

The file holds the first snapshot and every recorded frame (the rollback points are left out). An existing file is replaced only with -f. The machine stays paused.

zx-rzx-rollback

This command rolls the RZX recording back to a rollback point.

zx-rzx-rollback [n]

With no argument it goes back to the latest point; n goes back to the n-th latest. Everything recorded after the point is discarded, and the machine is paused there.

zx-rzx-point

This command inserts a rollback point into the RZX recording, at the next frame.

zx-rzx-point

zx-rzx-video

This command renders an RZX recording to a video file with the screen recorder.

zx-rzx-video <rzx-file> [-t]

The video uses the screen recorder’s frame rate, quality and format, and stops at the recording’s end or at a desync. The recording plays as fast as the emulator can run it, with the speaker muted; -t plays it in real time instead. Screen recording must be available (FFmpeg installed).

zx-rzx-video "recordings/game.rzx"

state-save

This command saves the machine’s complete state to a Klive state file (.kls).

state-save <state-file> [-f]

Available aliases: ssave

It works for every machine Klive emulates in its own cores (ZX Spectrum 48K, 128K, +2E/+3E, ZX Spectrum Next, Cambridge Z88, ZX80, ZX81). The machine must be running or paused; a running machine runs on afterwards. An existing file is replaced only with -f. See Saving and Restoring the Machine State.

state-save "states/before-boss.kls"
ssave "states/bug.kls" -f

state-load

This command loads a Klive state file and debugs or runs it.

state-load <state-file> [-r | -d] [-y]

Available aliases: sload

The command switches to the machine, model and configuration the state was saved on. With no option (or with -d), the machine starts in debug mode and stops at the saved program counter; -r runs it. A ZX Spectrum Next state whose SD card image has changed since is refused unless you add -y. With a project open, a state of another machine type is refused.

state-load "states/before-boss.kls"
sload "states/bug.kls" -r

z88-snapshot

This command loads a Cambridge Z88 snapshot (a .z88 file saved by OZvm) into the Z88 machine and debugs or runs it.

z88-snapshot <z88-file> [-r | -d | -a]

Available aliases: z88snap

With no option (or with -d), the snapshot is debugged: the machine starts in debug mode and stops at the snapshot’s program counter before executing that instruction. Use -r to run the snapshot. -a does what the file’s Autorun flag says — run when it is set, debug and stop at the program counter when it is not — as opening the file with File | Open File… does. Use only one option at a time.

The command makes the machine fit the snapshot: it switches to the Cambridge Z88, or sets the Z88 up again with the snapshot’s internal RAM and LCD size, when needed. It refuses to do that when a project for another machine is open. The real-time clock is advanced by the time the snapshot spent on disk.

The same actions are available from the Explorer’s context menu on a .z88 file, and from the buttons in a .z88 file’s document tab. See Using Z88 Snapshots for what Klive can load.

z88-snapshot "snapshots/game.z88"
z88-snapshot "snapshots/game.z88" -r
z88-snapshot "snapshots/game.z88" -a

tape-load

This command puts a .tap or .tzx file into the ZX Spectrum’s tape deck and, optionally, starts it loading.

tape-load <tape-file> [-r | -d]

Available aliases: tapeload

With no option, the tape is only inserted, as Machine | Tape | Insert Tape… does; inserting the tape already in the deck rewinds it. -r then resets the machine and starts the tape loading: it types LOAD "" on a 48K and chooses the Tape Loader (Loader on a +2A/+3) from a 128K’s start-up menu. -d does the same with your breakpoints armed. A relative path is taken from the project folder.

The command works on the ZX Spectrum 48K, 128K and +2/+3 only. It is what the tape viewer’s buttons and the Explorer’s context menu on a tape file run; see Loading from Tape.

tape-load "tapes/game.tzx"
tape-load "tapes/game.tzx" -r

nex-label

This command adds a label to the launched NEX file’s annotations, at the address the machine is stopped at.

nex-label <name> [<address>]

Available aliases: nl

Use it when you have just worked out what a routine does: the name goes into the .nex.dis annotations from the debugger, and the Disassembly view starts using it on its next refresh instead of showing a bare address.

The label is local to the bank the address is currently in, because that is the only thing the address means — the same routine sits somewhere else the next time its bank is paged elsewhere. Klive reads the current memory mapping to work out which bank that is, and refuses if the launched file does not contain it.

The machine must be paused, unless you give an address: a running machine’s program counter has moved on by the time the command reads it, so “where we are” would name an arbitrary instruction.

The label is written to the .nex.dis file straight away. If the NEX file’s viewer is open, the label joins the edits it is holding first, so neither can overwrite the other.

nex-label DrawSprite
nl ClearScreen
nex-label VBlankWait $C120

newp

This project creates a new Klive project and optionally opens it.

newp <machine-id> <project-name> [<template>] [-p <project-folder>] [-o]

The machine-id argument specifies the ID of the machine and an optional model. When you specify the machine and model type, use a colon to separate the machine ID from the model ID. For example, use sp48 for the basic ZX Spectrum 48K model and sp48:ntsc to use the NTSC version of ZX Spectrum 48K. See the Machine Types article for these IDs.

The project-name argument defines the project’s name. Unless the optional project-folder parameter is specified, the new project is created in the KliveProjects folder within your user folder.

Klive may support multiple project templates for a particular machine type (it provides a default template for each). If you want a specific template, specify its name in the template argument. See the Project Templates article for more information about available templates.

By default, the IDE creates a new project but does not open it. However, if you add the -o option, the new project will be immediately opened.

num

This command displays its argument number in decimal, hexadecimal, and binary formats.

num <number>

The input argument can be in decimal, hexadecimal, or binary format.

open

Use this command to open a folder.

open [<folder-path>]

Available aliases: op

If the folder-path argument is omitted, the IDE opens the show folder dialog to select a project folder. Otherwise, the IDE opens the project you specified. If the folder path is relative, the IDE loads the folder within your user directory’s KliveProjects folder.

outp

You can select a particular output pane with this command.

outp <paneId>

The paneId argument can be one of the available output panes (emu, build, or script).

project:excluded-items

This command lists the definitions of excluded project items. You can use the -global option to list the items that are excluded globally.

project:excluded-items [-global]

Available aliases: project:list-excluded, proj:excluded-items, proj:list-excluded, p:lx

project:exclude-item

This command adds or deletes excluded project items. You can use the -global option to list the items that are excluded globally. The -d option signs that the defined option should be deleted from the exclusion list. You can specify multiple items to add or delete.

project:exclude-item [--global] [-d] <item-path-1> ... <item-path-n>

Available aliases: project:exclude, proj:exclude-item, proj:exclude, p:x

run

This command compiles the code. If the compilation is successful, it injects the code into the current virtual machine and starts it. This command requires that a Klive project be loaded.

run

Available aliases: r

Note: The command will start (or restart) the virtual machine.

run-build-function

This command starts the build command function (see the build.ksx file) named in the command argument.

run-build-function <function-name>

Available aliases: rbf

The build.ksx file contains several commands, such as buildCode, injectCode, runCode, debugCode, and exportCode. Some projects may have additional custom commands.

run-to

This command runs the machine until it reaches a given address, then stops — without leaving a breakpoint behind.

run-to <address-spec>

Available aliases: rtc

The address-spec parameter accepts exactly the same forms as bp-set, including the ZX Spectrum Next’s bank-relative 05:+$0100 form. That last one is what makes this work on a bank that is not paged in yet: the machine runs until that offset inside that 16K bank is executed, wherever NextZXOS ends up paging the bank.

The breakpoint Klive uses is temporary in both senses — it is removed the moment it is reached, and it is never saved to your project or to a NEX file’s annotations. So the next time you continue, the machine does not stop there again.

What “run” means depends on what the machine is doing:

You can also do this from the disassembly view without typing a command: hold Ctrl (Cmd on macOS) and click the breakpoint margin next to the line you want to reach. This works in the Disassembly panel and in a popped-out NEX bank alike.

run-to $8000
run-to r1:$32ac
run-to 05:+$0100
run-to cu:$00B
run-to sp:$0C

On the ZX Spectrum Next, run-to cu:<index> runs until the Copper completes that list instruction — the Copper List’s Run to here — and run-to sp:<sprite> runs until an attribute byte of that sprite is written — the Sprite Inspector’s Run until attribute write.

script-cancel

This command runs the script file specified in the argument.

script-cancel <script-file-path-or-script-id>

Available aliases: sc

You can provide a script file name or a script ID as an argument. When you start a script, the ID of the running script is displayed. You can also get a particular script’s ID from the Script History panel.

When you specify a file name, use the full name (including the .ksx file extension) relative to the project’s root folder. For example, if your script is in the scripts folder and named myScript.ksx, use the scripts/myScript.ksx parameter.

script-output

This command navigates to the output document of the specified script.

script-output <script-id>

Available aliases: so

You must provide a script ID as an argument. When you start a script, the ID of the running script is displayed. You can also get a particular script’s ID from the Script History panel.

script-run

This command runs the script file specified in the argument.

script-run <script-file-path>

Available aliases: scr

Provide the full file name (including the .ksx file extension) relative to the project’s root folder. For example, if your script is in the scripts folder and named myScript.ksx, use the scripts/myScript.ksx parameter.

sjasmp-reset

Provide the folder path of the SjasmPlus compiler.

sjasmp-reset <SjasmPlus executable folder> [-p]

Available aliases: sjasmpr

Klive stores the SjasmPlus settings in the Klive.setting file. If you want to change this path for a particular project (perhaps you want to test with another SjasmPlus version), use the -p switch to save this setting into the currently open project.

You can also configure SJASMPLUS from the graphical dialog available at Settings > Integrations > SjasmPlus > Configure… (see Settings).

set

You can use this comment to set or delete a particular Klive setting.

set [-p] [-u] <key> [<value>] 

Use the -p option to set a project setting or -u for a user setting. <key> is the setting key, <value> is the new setting value. The specified key is removed if you omit <value>.

Note: Project settings are saved in the currently open project file, while user settings are saved in the Klive/live.settings file under your user folder.

If you do not specify the context (with -p or -u), the IDE will save a project setting, provided a project is open; otherwise, it saves a user-level setting.

setl

This command lists the specified settings.

setl [-p] [-u] [<setting>] 

Use the -p option to list project settings or -u for user settings. By default, all settings in the specified bucket are listed. Additionally, you can specify a setting prefix in <setting>. In this case, only matching settings are listed.

Note: Project settings are saved in the currently open project file, while user settings are saved in the Klive/live.settings file under your user folder.

If you do not specify the context (with -p or -u), the IDE will list project settings, provided a project is open; otherwise, it lists user-level settings.

setm

This command lists the specified settings.

setl [-pull] [-push] [-c] 

This command moves settings from the user setting file to the current project file (-pull) or vice versa (push). The additional -c option copies the settings instead of moving them.

Note: You can use either -pull or push. This command works only when a Klive project is open in the IDE.

setmem

This command sets the memory contents at the specified address with the provided value. When you set the content, you can use 8-bit, 16-bit, 24-bit, and 32-bit values using little-endian or big-endian assignment.

setmem <address> <value> [-b8] [-b16] [-b24] [-b32] [-be]

The -b8 (default), -b16, -b24, and -b32 options determine the data size (1, 2, 3, or 4 bytes, respectively) to write into the memory. These options are exclusive.

The -be option specifies the big-endian mode; the most significant byte of the value is written to the address specified in the command.

Lets assume you execute this command:

setmem $4000 $010203 -b24

It will store $03 at address $4000, $02 at $4001, and $01 at $4002 (little-endian mode). However, adding the -be options like this:

setmem $4000 $010203 -b24 -be

Will reverse the order of bytes: It will store $01 at address $4000, $02 at $4001, and $03 at $4002 (big-endian mode).

setz80Reg

Use this command to set one of these Z80 registers:

• 8-bit: A, F, B, C, D, E, H, L˙, XH, XL, YH, YL, I, and R`
• 16-bit: AF, BC, DE, HL, AF', BC', DE', HL', IX, IY, PC, SP, and WZ (memptr).

setz80Reg <register> <value> 

Available aliases: sr

When the value is outside the register’s valid range, the command will give you a warning and keep only the last 8 or 16 bits.

show-copper

Use this command to open the ZX Spectrum Next’s Copper List, and optionally to reveal one list index in it.

show-copper [<index>]

Available aliases: shcop

With an index ($000-$3FF), the list turns Follow PC off, selects that slot and scrolls to it.

show-history

Use this command to open the Execution History: the instructions the CPU ran in the current debug session.

show-history

Available aliases: shhist

It works on every machine that records execution history: every Z80 machine (not the Commodore 64).

history

Use this command to print the newest execution history records to the command output: the step, the frame position, the address, the bytes, the instruction, the source line and the registers each instruction changed.

history [<count>]

The count is 1-10000; it is 20 by default. History is recorded only in debug sessions.

history-export

Use this command to write the execution history, or a range of it, to a text or CSV trace file, so that two runs can be compared with a diff tool. The machine must be paused or stopped.

history-export <file> [-from <-n|#seq>] [-to <-n|#seq>] [-count <n>]
               [-format text|csv] [-columns default|viewer|all|<id,id,...>]
               [-absolute] [-repeats] [-nointerrupts] [-nomarkers] [-filter <text>]
               [-noheader] [-bom] [-f]

• file: .txt, .log or .trace writes text, .csv writes CSV; -format overrides the extension.
• -from, -to: the range, inclusive. -42 is a step back from the present, #1234 a record’s sequence number. By default, the whole history.
• -count: the newest n records, or n records from -from.
• -columns: default (frame tact addr bytes instr changes), viewer, all, or a comma-separated list of seq, step, frame, tact, addr, bytes, instr, source, changes, regs, flags, ctx.
• -absolute: absolute frame and sequence numbers (relative to the first exported record by default).
• -repeats: write the HALT, display-run and DMA counts (masked as ×* by default).
• -nointerrupts: leave out interrupt and NMI service; -nomarkers leaves out the line that marks each.
• -filter: the Execution History’s filter (an address, a range, a label, or text).
• -noheader: no ; header lines. -bom: a UTF-8 byte order mark.
• -f: replace an existing file.

Available aliases: hexp

debug-recording-save

Use this command to save the reverse-debugging session as a debug recording (.klr): its keyframes, inputs, breakpoints and watches. The machine needs a reverse-debugging timeline (start it with debugging); a running machine runs on.

debug-recording-save <file.klr> [-from <-n|#seq>] [-sparse] [-sources] [-f] [-note <text>]

• -from: drop everything before the last keyframe at or before this point: -42 steps back from the present, #1234 a record’s sequence number.
• -sparse: keep only keyframes about a second apart.
• -sources: embed the compilation’s source files (by default only their names and fingerprints).
• -f: replace an existing file.
• -note: a description; the rest of the line.

Available aliases: drsave

debug-recording-load

Use this command to open a debug recording: it switches to the machine the recording was made on and stands paused where it was saved, with the whole recording to step back through.

debug-recording-load <file.klr> [-start] [-verify] [-nobreakpoints] [-y]

• -start: stand at the recording’s start instead; Continue replays it with breakpoints active.
• -verify: replay the whole recording once, checking every keyframe.
• -nobreakpoints: keep the current breakpoints instead of adding the recording’s.
• -y: a recording made by another Klive build cannot be replayed; open its end state instead.

Available aliases: drload

history-clear

Use this command to empty the execution history.

history-clear

Available aliases: hclr

step-back

Use this command to step back to the previous instruction in the execution history of the paused machine. The CPU panel, the editor and the disassembly show that point; memory stays at the present.

step-back

Available aliases: stb

With source stepping on, it steps back by statements.

step-forward

Use this command to step forward through the execution history; after the newest record it returns to the present.

step-forward

Available aliases: stf

step-back-over

Use this command to step back like step-back, passing over a call that returned to the call instruction itself.

step-back-over

Available aliases: stbo

step-back-out

Use this command to step back to the call (or interrupt) that entered the current routine.

step-back-out

Available aliases: stbu

reverse-continue

Use this command to go back to the previous point where an enabled breakpoint would have stopped the machine. With reverse debugging on, the machine is really there: every breakpoint kind is checked, and a memory-write breakpoint finds the last write to an address. With it off, only execution breakpoints are searched in the recorded history; conditions that read only registers and flags are checked against the recorded registers, other conditions count as hit, and the output says so.

reverse-continue

Available aliases: rcont

reverse-continue-cancel

Use this command to stop a running Reverse Continue search. The machine goes back where the search started.

reverse-continue-cancel

Available aliases: rcancel

history-take-over

Use this command, while the machine stands in the past of a reverse-debugging session, to make that point the present: the recorded future is discarded and the machine continues live from there. It asks first and names what the discarded future leaves behind (SD card writes it undoes, tape files that stay); -y skips the question.

history-take-over [-y]

Available aliases: htake

history-present

Use this command to leave the execution history and show the live machine again.

history-present

Available aliases: hpres

history-goto

Use this command to move to a point of the execution history: a step back from the present (-42) or a record’s sequence number (#1234).

history-goto <-n | #sequence>

coverage

Use this command to control code coverage and the memory heat map. Alias: cov.

coverage on [-nocounts] | off | reset | status
coverage export <file> [-format lcov|csv|kcov] [-norom] [-f]
coverage load <file>
coverage smc

• on, off: turn coverage on or off for the session. -nocounts keeps only whether each byte was executed, read or written, not how often.
• reset: clear everything coverage recorded.
• status: whether coverage is on, what it counted, how full the counter pool is, the time split and the current build’s line coverage.
• export: write LCOV (.info, .lcov), CSV (.csv) or Klive coverage (.kcov); -format overrides the extension, -norom leaves ROM bytes out of a CSV, -f replaces an existing file.
• load: merge a .kcov file into the current coverage.
• smc: list the self-modified bytes, with the nearest label and their counts.

coverage-reset

Use this command to clear code coverage and the heat map. Alias: covr.

coverage-reset

memory-heat

Use this command to set the memory view’s heat map, as its Heat selector does.

memory-heat <off|exec|read|write|all>

profile

Use this command to control the profiler. Alias: prof.

profile start [-calls] [-at <address|label>] [-until <address|label>]
profile stop | reset | status
profile top [n] [-by self|inclusive|calls] [-waiting]
profile export <file> [-format fuse|csv|callgrind|speedscope] [-addresses] [-f]

• start: reset the profile and start a window. -calls records the call graph. -at starts counting the first time the program reaches the address; -until stops profiling the next time it gets there after that.
• stop: stop profiling; the profile stays until the next start or reset.
• reset: clear the profile.
• status: whether profiling is on and armed, the time and frames measured, and the call graph’s counters (calls, interrupts, stack switches).
• top: the top n routines (10 by default), sorted by self time, inclusive time or calls. -waiting keeps time in HALT in the table.
• export: write speedscope (.json), callgrind (callgrind.out.*, .callgrind), CSV (.csv) or Fuse (.prof); -format overrides the file name, -addresses writes the Addresses table as CSV, -f replaces an existing file.

profile-start

Use this command to start profiling, as profile start does. Alias: pst.

profile-start [-calls] [-at <address|label>] [-until <address|label>]

profile-stop

Use this command to stop profiling, as profile stop does. Alias: psp.

profile-stop

show-profiler

Use this command to display the Profiler document. Alias: shprof. hide-profiler (hprof) closes it.

show-profiler

test-list

Use this command to list the unit tests of the last successful build, by suite, with their addresses and links to their labels. Alias: tl.

test-list

test-run

Use this command to build the project and run its unit tests. The report goes to the Tests output pane; the command prints the summary. Alias: tr.

test-run [<pattern>] [-failed] [-coverage]

• pattern: run only the tests whose Suite.UT_name matches; * matches any run of characters (MathTests.*, *Overflow*). All tests (or the project’s unitTests.include) when omitted.
• -failed: run only the tests that failed or ended in an error in their last run.
• -coverage: record code coverage while the tests run and show it in the editor.

test-debug

Use this command to debug one unit test in the emulator: it stops at the test’s first instruction, and reaching TC_END stops with “passed”. Alias: td.

test-debug <test>

test is the test’s Suite.UT_name, its label alone, or a * pattern that names one test.

test-init

Use this command to add unit-test support to the project: Klive’s include file next to the build root (kept when one is there already), and its include line in the build root.

test-init

test-junit

Use this command to write the last unit-test run’s results as JUnit XML, the file klive test --junit writes in CI (Unit Tests on the Command Line). The Testing activity’s Export results as JUnit… context-menu item runs it.

test-junit <file> [-notimestamp]

• file: the XML file to write.
• -notimestamp: leave the run’s time out, so two runs with the same results write the same file.

show-disassembly

Use this command to display the machine code disassembly view, and optionally to show an address in it.

show-disass [<address>]

Available aliases: shdis

With an address, the view switches to the full 64K listing, turns Follow PC off and scrolls to that address. The Show in Disassembly menu items of the editor and the Breakpoints view use it.

show-memory

Use this command to display the memory contents view.

show-memory

Available aliases: shmem

show-patterns

Use this command to open the ZX Spectrum Next’s Sprite Inspector on its Patterns view, and optionally to select a pattern in it.

show-patterns [<index>]

Available aliases: shpat

The index is a 256-byte pattern slot (0-63), the number an 8-bit sprite uses. The inspector shows the slot’s users and, when sprites read it as 4-bit halves, both halves.

show-sprites

Use this command to open the ZX Spectrum Next’s Sprite Inspector on its Sprites view, and optionally to select a sprite in it.

show-sprites [<index>]

Available aliases: shspr

With an index (0-127), the sprite is selected: the inspector shows it and the Patterns view marks its pattern. The View → Machine Views → Sprite Inspector menu item runs show-sprites. In a document too narrow for the Patterns view beside the table, show-patterns switches to its tab.

show-tilemap

Use this command to open the ZX Spectrum Next’s Tilemap Inspector on its Map view, and optionally to select a cell in it.

show-tilemap [<col> <row>]

Available aliases: shtm

With a column (0-79) and a row (0-31), the cell is selected: the inspector decodes it and the Tiles view marks its tile. The View → Machine Views → Tilemap Inspector menu item runs show-tilemap.

show-tiles

Use this command to open the ZX Spectrum Next’s Tilemap Inspector on its Tiles view, and optionally to select a tile in it.

show-tiles [<index>]

Available aliases: shtl

With an index (0-511), the tile is selected: the inspector lists the cells that use it, and the map outlines them.

show-layer2

Use this command to open the ZX Spectrum Next’s Layer 2 Inspector, optionally on a source.

show-layer2 [displayed|shadow|window]

Available aliases: shl2

displayed shows the banks from NextReg $12, shadow those from $13, and window the set the port $123B write window maps. Without a source the document keeps the one it shows. The View → Machine Views → Layer 2 Inspector menu item runs show-layer2.

layers

Use this command on the ZX Spectrum Next to hide, show or solo a video layer on the emulator screen (Video Layers). It changes only what the emulator shows, never the machine.

layers [ula|tm|l2|spr|all|transparency] [on|off|solo]

Without arguments it lists the layers. A layer without an action is toggled; solo shows that layer alone; all on shows every layer and all off hides them all; transparency on marks the pixels no layer covers. The layers are also accepted by their names: tilemap, layer2, sprites. A change shows the Layers strip under the emulator screen, whose chips do the same.

show-layers

Use this command to open the ZX Spectrum Next’s Layers document: the priority stack, one card per layer, and one picture per layer.

show-layers

Available aliases: shly

The View → Machine Views → Layers menu item runs show-layers.

beam

Use this command to show or hide the beam position on the paused emulator screen: where the raster is, and which part of the picture is left from the previous frame.

beam [on|off]

Without an argument it says whether the overlay is shown. The beam button in the emulator toolbar and Settings → Emulator → Beam position change the same setting.

step-copper

Use this command on the ZX Spectrum Next to run the machine until the Copper completes its next instruction. The machine stops at the end of the Z80 instruction during which that happened.

step-copper

Available aliases: stcop

Like run-to, it needs the machine paused, stopped, or running with debugging. See Stepping The Copper.

zxb-reset

Use this command to set ZXBASIC integration.

zxb-reset <Full ZXBC executable path> [<python3 path>] [<start of machine code>]

Available aliases: zxbr

Provide the full executable path of the ZXBC compiler. Optionally, you can provide the path to the Python3 executable and the start of the machine code. See the ZXBASIC integration article for more information.