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

bp-del

This command removes a breakpoint.

bp-del <address-spec>

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;
• or a source code line specification, for example, [code/code.kz80.asm]

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> [-d]

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;
• or a source code line specification, for example, [code/code.kz80.asm]

The -d option disables the breakpoint.

bp-set

This command sets a breakpoint.

bp-set <address-spec>

Available aliases: bp

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;
• or a source code line specification, for example, [code/code.kz80.asm]

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 (DSK format) you can use with ZX Spectrum +3 models (and compatible).

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
• disk-name: The name of the disk file (.dsk extension as 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.

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, 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

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

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 IDE > Integrations > SJASMPLUS....

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-disassembly

Use this command to display the machine code disassembly view.

show-disassembly

Available aliases: shdis

show-memory

Use this command to display the memory contents view.

show-memory

Available aliases: shmem

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.