Commands Reference

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 Available aliases: shmem

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).

show-memorye partition and the address separated with a colon), for example, r1:$32ac (meaning $32ac, provided ROM 1 is paged in);

  • or a source code line specification, for example, [code/code.kz80.asm]

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);
  • 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);
  • 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 projeFile [line] [column]

The filename 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.

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.

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.

sjasm-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.

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

💡

This command runs only when the machine is paused. In other states, it gives an error message.

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.

Scripting SyntaxMachine Types