9.1 Command-line options

Every option JNEXT accepts is listed below, grouped the way the manual groups them. This page, the jnext(1) man page and USAGE.md are three renderings of one source, so they cannot disagree with each other.

A bare filename is shorthand for --load, so jnext game.tap works. Anything starting with - is treated as an option, never as a filename, and naming the program both ways at once is rejected.

For a quick reminder without leaving the shell:

$ jnext --help
$ jnext --version
$ man jnext

If you ever find the documentation and the program disagreeing, the program is right — please report it.

Machine and program

--machine TYPE

Machine type: 48k, 128k, plus3, next (default).

--load FILE

Load a program. The format is detected from the extension: .nex, .sna, .szx, .z80, .tap, .tzx, .wav, .rzx. (.rzx is accepted here and plays back, as --rzx-play.)

--nex-args LINE

Argument line for a NEX V1.3 program. LINE is placed, verbatim and zero-terminated, in the CLI buffer the file’s header declares (its address and size), and DE points at it when the program starts. A line as long as or longer than that buffer is truncated to the buffer’s size with no terminator - which is what the reference V1.3 loader does. Quote LINE to pass more than one word: jnext --load game.nex --nex-args "level 3". Only V1.3 declares a CLI buffer, so the option is inert - with a warning - for a V1.0-V1.2 file, or a V1.3 file whose header declares no buffer.

--experimental-nex-v1.3

Allow loading NEX V1.3 files. NEX V1.3 is an experimental format and is not supported in any way; without this flag, loading a NEX file whose header version exceeds V1.2 is refused with an error naming the version found (exit status 1). In the GUI, selecting such a file shows a warning dialog instead, with Cancel as the default. V1.0-V1.2 files are unaffected either way.

--sdcard FILE

Mount SD-card image FILE (.img). Optional; see Why JNEXT needs an SD-card image.

--sdcard-download-confirm

Skip the download prompt for the default-location image and proceed.

--sdcard-download-force

Force re-download and re-patch of the default-location image, to recover a corrupted one. Ignored when --sdcard is given: an explicit path always wins.

--sdcard-readonly

Open the SD image read-only, so the host file is never modified. The emulated machine sees a write-protected card: writes are rejected with the SD write-error token rather than silently discarded. Use it when a run must not disturb an image other runs share.

--speed PERCENT

Emulator throttle: 50 = half, 100 = normal, 200 = 2x, 400 = 4x. Clamped to 10..1000.

--when-slow-prefer WHAT

What to sacrifice on a host that cannot emulate in real time: audio (default) or video. It changes nothing on a host with headroom.

audio keeps the sound card fed by emulating two frames in one frame slot when it runs low. The first frame of such a pair is overwritten before it can be painted, so the picture advances in an uneven, lurching way while the sound stays clean.

video never drops a frame for the sound card. The extra frame runs in the next slot instead, so it gets its own present, and the machine simply runs slower than real time. The sound queue then runs down to its floor and the last sample level is held to bridge the gap, which is heard as stutter and a dropped pitch. This is how FUSE-style emulators degrade.

Interactive frontends only; inert under --headless, which is uncapped and has no audio device. The GUI equivalent is When the host is too slow under Settings > Preferences > Startup, which applies live.

--joy1-source SRC

Host source for Joy 1 (port 0x1F): sdl (autodetected gamepad, default) or keys (host arrow keys, Space = fire).

--joy2-source SRC

Host source for Joy 2 (port 0x37): sdl (default) or keys. Only one connector may use keys. Interactive (SDL/Qt) frontends only; inert under --headless.

--tape-realtime

Real-time tape loading, at the speed of an actual tape, instead of fast load.

--tape-save FILE

Append blocks SAVEd through the 48K ROM SA-BYTES routine to FILE (.tap). Trap-based: it fires when the ROM save routine at 0x04C2 runs with ROM paged at slot 0. Without this option no SAVE capture happens.

--esxdos-stub

Intercept RST $08 calls and provide in-memory config I/O plus .RUN sibling-NEX chaining, without booting NextZXOS.

--rtc “YYYY-MM-DD HH:MM:SS”

Pin the RTC to a fixed date and time (a frozen clock) instead of following the host clock, which makes boot screenshots deterministic. The ISO YYYY-MM-DDTHH:MM:SS form is also accepted.

--silent

Disable all sound output (beeper, the three AY/YM chips, DAC/Covox/ Specdrum). No audio device is opened and the emulator skips PSG and mixer sample synthesis entirely, which can measurably speed up CPU-bound runs. Tape loading (EAR input) is unaffected.

--inject FILE

Load a raw binary into RAM.

--inject-org ADDR

Load address for --inject (hex, default 8000).

--inject-pc ADDR

Entry point for --inject (hex, default: same as --inject-org).

--inject-delay N

Wait N frames before injecting (default 0). Use around 100 if the binary calls ROM routines that need the system variables set up first.

Networking (ESP-01 WiFi)

--esp

Enable the emulated ESP-01 WiFi module on UART 0. Off by default - see 5.6 Networking for what turning it on gives the running program.

--no-esp

Force the ESP off for this run, overriding a saved GUI preference that enables it. Given both, whichever comes last on the command line wins.

--esp-allow HOST

Only let the running program connect to HOST. Repeatable: give the option once per host. HOST is a single name - a comma is rejected rather than taken as a separator or as part of the name, because a name that silently matched nothing would look like a restriction that is in force when it is not. Matching is exact and case-insensitive, with no wildcards, and an IP address must be listed as itself. With no --esp-allow at all the program may name any host (subject to the always-refused addresses in 5.6 Networking). Requires --esp.

--esp-listen-address ADDR

Bind the running program’s AT+CIPSERVER to ADDR, default 127.0.0.1. ADDR is a numeric IP address, never a name - an address resolved through DNS could change under you. The default means a program that opens a server is reachable only from this machine; widening it (0.0.0.0) exposes that program to your network, which is why it has to be asked for. Nothing listens until the program itself sends AT+CIPSERVER. Requires --esp.

Recording and playback

--record FILE

Record video and audio to an MP4. Requires ffmpeg(1) on the PATH. If the recording cannot be produced (encoder failure, no usable output), jnext reports the error and exits non-zero. If the recording cannot even be started (no usable ffmpeg), jnext exits non-zero immediately, without running the emulation.

--wav-record FILE

Record the mixed stereo output to a 44.1 kHz, 16-bit PCM WAV. Works headless and requires neither an audio device nor ffmpeg.

--dac-trace FILE

Record segment,tstate,channel,value rows for physical DAC writes. A cold boot starts a new segment.

--audio-gain-db DB

Set master host audio gain from -24 dB to +24 dB (default 0 dB). The gain is applied after the emulated hardware mix; overflow saturates at the 16-bit PCM limits.

--audio-gain-beeper-db DB

Set host gain for beeper EAR/MIC/tape-EAR audio from -24 dB to +24 dB.

--audio-gain-ay0-db DB

Set host gain for TurboSound AY chip 0 from -24 dB to +24 dB.

--audio-gain-ay1-db DB

Set host gain for TurboSound AY chip 1 from -24 dB to +24 dB.

--audio-gain-ay2-db DB

Set host gain for TurboSound AY chip 2 from -24 dB to +24 dB.

--audio-gain-dac-db DB

Set host gain for Specdrum, Soundrive and Covox DAC audio from -24 dB to +24 dB.

--rzx-play FILE

Play back an RZX recording.

--rzx-record FILE

Record input to an RZX file.

--rewind-buffer-size N

Frame-snapshot ring buffer for backwards execution. Opt-in; default 0 = off.

--trace

Enable the per-instruction trace log (a 10K-entry ring). Also enabled implicitly by --rewind-buffer-size N with N > 0, and toggleable in the debugger.

Headless and automation

--headless

Run with no display and no audio device, at maximum speed.

--benchmark N

Headless only. Run exactly N frames uncapped, print one machine-parseable BENCH line (wall seconds, fps, T-states/s, T-states/frame, CPU speed, host core, build type) plus a human summary to stdout, then exit. Used by make bench (test/bench/bench.sh).

--benchmark-label NAME

Workload label printed verbatim in the BENCH line (default: the loaded file’s basename, or boot-<machine>). No whitespace, since the BENCH line is space-delimited.

--delayed-screenshot FILE

Save a PNG screenshot after a delay.

--delayed-screenshot-time N

Delay in seconds (default 10).

--delayed-screenshot-frames N

Delay in frames. Overrides --delayed-screenshot-time.

--delayed-screenshot-layers LIST

Layers to compose into the screenshot: a comma-separated list of ula, layer2, sprites, tiles, all (default all).

--delayed-automatic-exit N

Exit the emulator after N seconds.

--delayed-automatic-exit-frames N

Exit after N frames. Overrides --delayed-automatic-exit.

--delayed-snapshot FILE

Headless only. Save a snapshot after a delay in frames. The format is chosen by the extension of FILE: .szx, .nex, anything else .sna.

--delayed-snapshot-frames N

Delay in frames for --delayed-snapshot (default 0).

--delayed-keypress SECS KEY

Press KEY after SECS seconds. Headless only, repeatable.

--delayed-keypress-frames N KEY

Press KEY after N emulated frames. This is the frames-unit spelling of --delayed-keypress, not an override of it: both forms queue into the same list, so giving both schedules two keypresses.

--delayed-nmi SECS BUTTON

Press an NMI BUTTON after SECS seconds. Headless only, repeatable. BUTTON is case-insensitive and names which button to press, spelled as the label on a real Next’s case. Of its three buttons, two raise an NMI: nmi (aliases mf, m1) is the NMI button, wired to the Multiface; drive (alias divmmc) is the DRIVE button, wired to the DivMMC. RESET is not an NMI button and is not accepted here. The press goes through the same path as the host F9 / F10 hotkeys, so it is subject to the same enable gates — NextREG 0x06 bit 3 for the Multiface, bit 4 plus NextREG 0x83 bit 0 for the DivMMC — and a press with its gate closed does nothing, exactly as on hardware. One press generates one NMI, not a repeating one.

--delayed-nmi-frames N BUTTON

Press BUTTON after N emulated frames. This is the frames-unit spelling of --delayed-nmi, not an override of it: both forms queue into the same list, so giving both schedules two presses.

--compositor-trace FILE

Dump a per-pixel compositor trace (CSV) for one frame.

--compositor-trace-frame N

Target frame for --compositor-trace (default 250).

KEY is case-insensitive and is one of: a single character (a-z, 0-9, ., ,, ;, :), one of the symbolic names ENTER, RETURN, SPACE, UP, DOWN, LEFT, RIGHT, or a compound sym+char / caps+char (for example sym+m is .).

Debugging

--magic-breakpoint

Enable the magic-breakpoint opcodes (ED FF and DD 01).

--persistent-breakpoints

Keep breakpoints and watchpoints armed while the debugger window is closed. Without this option — the default — closing the window disarms them, and nothing stops. With it, a hit pauses the machine and reopens the debugger window at the breakpoint. With the window already open, behaviour is unchanged. The breakpoint check then runs on every instruction for the whole run, which is what “persistent” costs; it is accepted but has no effect in --headless, in the SDL-only build and in builds without the debugger, since only the debugger can set a breakpoint.

--magic-port PORT

Enable the magic debug port at PORT (hex, for example 0x00FF).

--magic-port-mode MODE

Magic-port output mode: hex (default), dec, ascii, line.

--profile

Enable the CPU T-state profiler. It allocates an mmap’d histogram and accumulates one entry per executed instruction; on exit the histogram is written to --profile-output.

--profile-output FILE

Output path for --profile (default profile.dat).

--log-level SPEC

Set per-subsystem log levels; see the LOGGING section of the man page.

--log-file FILE

Write the log to FILE instead of the console. FILE is truncated at the start of every run, and jnext exits non-zero if it cannot be opened rather than quietly logging to the console instead. See the LOGGING section of the man page.

Misc

--help, -h

Print the built-in help and exit.

--version, -V

Print the version and exit.