Skip to content

Command Line

WacKEDmaN edited this page Nov 12, 2026 · 8 revisions

Command line

The program is cpcse.exe on Windows, cpcse on Linux, and CPCSyntaxError.app/Contents/MacOS/cpcse on macOS.

There are three ways to start it:

  1. With a window (the usual way). Some options change this session only.
  2. Headless screenshot mode (--shot): no window; the machine runs for a number of frames, then saves a screenshot and stops. For scripts and tests.
  3. CSL mode (--csl): no window; plays a CPC Script Language file. Refer to CSL scripts.

Windows note: cpcse.exe is a windowed program, so a Command Prompt does not wait for it. The headless modes write their output to the Command Prompt that started them. In a batch file that needs the result, use start /wait cpcse.exe ....

Options for the window

Option What it does
--roms <folder> Use another ROM folder
--machine <name or file> Start with a machine profile (refer to Machines and ROMs). A name is looked for in the machines folder.
--gdb[=port] Start the GDB server (default port 12000)
--api[=port] Start the command API (default port 6128)
--mcp[=port] Start the MCP server for AI agents (default port 6129, http://127.0.0.1:6129/mcp)
--load <file>[@addr] Load a file once the firmware has started
--watch <file>[@addr] Load it, and again each time the file changes
--run entry or --run <addr> Start a loaded .bin
--reset Reset before each load
--command <text> Type this after loading (\n is Enter)
--symbols <file> Labels for the debugger and for addresses
-i <file>, --inject <file> TRSE: put the file into memory and start it
-o <addr>, --offset <addr> TRSE: where -i puts the file (default &6000)
-s <file>, --sym_file <file> TRSE: symbols, and its break $xxxx lines as breakpoints
-O system.model=N TRSE: the machine for this session (0 = 464, 1 = 664, 2 = 6128, 3 = 6128 Plus)
--crash-test <kind> Crash on purpose to test the crash report: segv, abort, throw, stack, divide

The external-debugging options are in External debugging.

Headless screenshot mode

cpcse --shot out.bmp --model cpc6128 --frames 200 --disk game.dsk --type "RUN\"GAME\n"

--shot <file.bmp> starts this mode. The machine runs for --frames frames (default 200), then the picture is saved and the program ends. Disc writes are off unless --disk-writeback is given. The settings file is not used or changed.

The machine

Option What it does
--model <id> cpc464, cpc664, cpc6128, cpc464plus, cpc6128plus, gx4000
--ram <KB> RAM from 64 to 4160 KB
--crtc <0-4> The CRTC type
--gate-array <part> 40007, 40008 or 40010
--z80 nmos|cmos The Z80 part
--gx4000-128k The GX4000 128K RAM mod
--plus-expansion classic|internal The Plus RAM expansion type
--roms <folder> The ROM folder
--xrom <slot>=<file> An expansion ROM in a slot (can be given more than once)
--frames <n> How long to run
--seq <n> Save this many frames one after the other, from --frames on (to see motion)

Media

Option What it does
--disk <file> A disc in drive A
--disk-writeback Write the program's disc writes into the image file
--tape <file> A tape in the deck (.cdt, .tzx, .tap, .wav); PLAY is down
--tape-fast <baud>|instant|off Fast loading speed, instant loading, or off. The decision for each block is printed at the end.
--record-tape <file.cdt> A blank tape with RECORD down; saved in that file at the end
--cart <file> A cartridge (.cpr or .cro)
--cro-group <n> The CRO group to run
--picogx <folder> The PicoGX's SD card folder
--picogx-launch <file> The file the PicoGX launches, relative to its SD card folder
--sna <file> Load a snapshot
--savesna <file> Save a snapshot at the end
--dumpram <file> Save the raw RAM at the end (no header)

Input

Option What it does
--type <text> Typed after the machine starts. \n is Enter.
--keys <codes> Keys tapped, separated by commas (for example Space). r<N> runs N frames with no key. Key*N holds the key for N frames (ArrowRight*200). Key! presses the key and keeps it held, for the frames that --seq saves.
--f1at <n> Press F1 every n frames
--mouse <script> A mouse and keyboard script, run after the other steps (below)
--mouse-interface amx|kempston|multiplay-a|multiplay-b A mouse interface

The --mouse script is a list of commands separated by ;:

Command What it does
w<frames> Wait
m<dx>,<dy> Move the mouse
c Click
d Double-click
j<bits>,<frames> Hold the joystick (bits: 1 up, 2 down, 4 left, 8 right, 16 fire)
t<text> Type text
k<key> Tap a key (for example kEnter)
s<file.bmp> Save a screenshot
n Press the Multiface II STOP button

For example: --mouse "w120;j5,60;j16,2;tDIR;kEnter;sshot.bmp". This is enough to control a desktop such as SymbOS with no window.

Video

Option What it does
--beam The beam renderer
--raster-overlay Draw the raster timing overlay
--monitor-set <id> ctm644, ctm640, cm14, gt64, gt65, mm12
--hhold <-79..79>, --vhold <-50..50> The monitor's hold controls
--brightness <0-100> The set's front knob
--contrast <0-100> The second knob (monochrome sets)
--intensity <R,G,B> The output intensity, 0 to 200% each

Expansions

Option What it does
--m4 <folder> An M4 Board, this folder its SD card
--multiface A Multiface II
--sf2 A Symbiface II
--sf3 A SYMBiFACE III
--xmass An X-MASS IDE interface (with --ide)
--ide <folder> The Symbiface or X-MASS IDE drive's folder
--sf3-usb <folder>, --sf3-sd <folder> A SYMBiFACE III with this USB stick or SD card folder
--sf3-rombank <n> The SF3 SD card's ROM bank
--albireo <folder> An Albireo at &FE80, this folder its SD card (- for no card)
--albireo-usb <folder> Its USB port: a folder (a USB stick), mouse or none
--albireo2 <folder>, --albireo2-usb <folder> The same for a second Albireo at &FE40
--albireo-serial <line> Albireo 1 as an Albireo 1.1 with its serial link: tcp:host:port, listen:port, com:COM3, loopback or -
--albireo-switches <S1S2S3S4> Its DIP switches, four digits 0 or 1 (default 1100)
--hd20 <file.img> A Dobbertin HD20 with this image
--serial <line> The RS232C card: tcp:host:port, listen:port, com:COM3, loopback
--gfx9000 A GFX9000
--gfx9000-monitor beside|window|switch|video9000 Where its picture goes
--v9990-shot <file.bmp> Also save the GFX9000's picture
--video9000-shot <file.bmp> Also save the Video9000's mixed picture
--opl4 An OPL4 card
--playcity A PlayCity
--speech ssa1|dktronics|lambdaspeak3 A speech unit
--mp3card <folder> The LambdaSpeak 3 MP3 card's folder
--dac digiblaster|amdrum A DAC

Sound and video files

Option What it does
--wav <file> The sound of the whole run
--record <file> The whole run: .avi, .mp4 or .wav
--record-format mjpeg|h264 The video format (h264 needs ffmpeg)
--record-source shown|cpc|gfx|both Which picture

C builds

Option What it does
--cbuild <main.c> Build a C project, then run it
--cpctelera <folder> With CPCtelera's library
--sdcc <folder> SDCC's folder (default: found)
--codeloc <addr> The code address, without cfg/build_config.mk
--force-assets Run every CPCtelera asset step again
--z88dk <folder>, --sccz80 Build with z88dk (with sccz80)

Always give --shot with --cbuild: without --shot, the program opens its window after the build.

Output

Option What it does
--diag Print diagnostic information

Examples

cpcse --shot out.bmp --model cpc464 --tape game.cdt --type "RUN\"\n\n" --frames 3000
cpcse --shot out.bmp --model cpc6128plus --cart game.cpr --frames 600
cpcse --shot out.bmp --model cpc6128 --m4 sdcard --type "RUN\"SYM\n" --frames 1200
cpcse --shot out.bmp --model cpc6128 --disk demo.dsk --type "RUN\"DEMO\n" --frames 2000 --record demo.mp4 --record-format h264

Clone this wiki locally