BASIC Commands
Spectranext extends ZX BASIC with filesystem, stream, socket, and configuration commands. Most commands use a % prefix. Some filesystem commands also have a . form for shell-like direct path usage.
Use % commands when you want normal BASIC expressions:
10 LET A$="games"
20 %cd A$
Use . commands when you want to type a literal path directly:
.cd games
.cat /sys/bin
Quick Start
Open the built-in resource index:
!
Mount a filesystem automatically into a free slot and switch to it:
%mount "https://spectranext.net/demo/hn"
Mount into a specific slot and select it:
%mount 0, "xfs://ram/"
%fs 0
Load the default boot.zx program from the current filesystem:
%load ""
!
Open the Spectranext resource index.
!
This is the same resource browser that is available from the launcher. It is intended for browsing published resources and demos.
%mount
Mount a filesystem.
%mount "url"
%mount slot, "url"
The one-argument form chooses a free mount slot and then switches the current filesystem to that slot.
The two-argument form mounts into the slot you specify. Use %fs afterwards if you also want to make it current.
10 %mount "https://spectranext.net/demo/hn"
20 %load ""
10 %mount 3, "tnfs://example.com/public"
20 %fs 3
30 %cat
Common URL forms include:
xfs://ram/for the local RAM/flash overlay filesystemtnfs://host/pathfor TNFShttps://host/path/for a read-only HTTP(S) directory
.mount
Alias for %mount.
.mount "url"
.mount slot, "url"
This command still uses the normal BASIC expression parser because its syntax includes a URL string and optionally a numeric mount slot.
%umount
Unmount a filesystem slot.
%umount slot
Example:
%umount 3
Unmounting closes the selected mount point. Do not unmount a filesystem while programs are still using open streams or files from it.
.umount
Alias for %umount.
.umount slot
This command still uses the normal BASIC numeric parser.
%fs
Select the current mounted filesystem.
%fs slot
Example:
%fs 0
Filesystem commands such as %cat, %cd, %load, and %save operate on the currently selected mount point.
.fs
Alias for %fs.
.fs slot
This command still uses the normal BASIC numeric parser.
%cd
Print or change the current directory.
%cd
%cd "path"
%cd path$
With no argument, %cd prints the current working directory. With an argument, it expects a BASIC string expression.
10 LET D$="/games"
20 %cd D$
30 %cat
.cd
Print or change the current directory using a direct literal path.
.cd
.cd path
Example:
.cd /games
Use .cd for interactive use. Use %cd from BASIC programs when the path comes from a variable or expression.
%cat
List a directory.
%cat
%cat "path"
%cat path$
With no argument, %cat lists the current directory. With an argument, it expects a BASIC string expression.
10 %cat "/sys/bin"
.cat
List a directory using a direct literal path.
.cat
.cat path
Example:
.cat /sys/bin
%load
Load a ZX-format file from the current filesystem.
%load "filename"
%load ""
%load "filename" CODE
This follows the normal ZX BASIC LOAD shape, but loads from the selected filesystem instead of tape. An empty filename loads boot.zx.
%load ""
%load "game.zx"
CODE loads a CODE file at the address stored in the file header.
.load
Alias for %load.
.load "filename"
.load ""
.load "filename" CODE
This command still uses the normal BASIC loader syntax.
% + LOAD
SE BASIC-compatible spelling for %load.
%LOAD "filename"
In firmware this is registered as % followed by the ZX BASIC LOAD token. It exists for compatibility with software that emits tokenized LOAD syntax.
%save
Save a ZX-format file to the current filesystem.
%save "filename"
%save "filename" LINE line
%save "filename" CODE address,length
%save "filename" SCREEN$
This follows the normal ZX BASIC SAVE shape, but writes to the selected filesystem instead of tape.
Examples:
%save "program.zx"
%save "program.zx" LINE 10
%save "screen.scr" SCREEN$
%save "block.bin" CODE 32768,1024
.save
Alias for %save.
.save "filename"
.save "filename" CODE address,length
This command still uses the normal BASIC save syntax.
% + SAVE
SE BASIC-compatible spelling for %save.
%SAVE "filename"
In firmware this is registered as % followed by the ZX BASIC SAVE token.
%aload
Load a raw file directly into memory.
%aload "filename" CODE address
Unlike %load, this does not expect a ZX/TAP-style header. It reads the file bytes directly into the address you provide.
%aload "data.bin" CODE 32768
.aload
Alias for %aload.
.aload "filename" CODE address
This command still uses the normal BASIC expression and CODE syntax.
%asave
Save a raw memory block directly to a file.
%asave "filename" CODE address,length
Unlike %save, this writes raw bytes without a ZX/TAP-style header.
%asave "dump.bin" CODE 32768,4096
.asave
Alias for %asave.
.asave "filename" CODE address,length
This command still uses the normal BASIC expression and CODE syntax.
%tapein
Select a TAP file as the tape input source.
%tapein "filename"
%tapein file$
After this command, normal tape loading commands can read from the selected TAP file.
10 %tapein "browser.tap"
20 LOAD ""
.tapein
Select a TAP file using a direct literal path.
.tapein filename
Example:
.tapein /sys/bin/browser.tap
%info
Show information about a file.
%info "filename"
%info file$
The output includes file metadata that can be obtained from the selected filesystem.
.info
Show information about a file using a direct literal path.
.info filename
Example:
.info readme.txt
%loadsnap
Load a snapshot file through the snapshot manager module.
%loadsnap "filename"
The command expects a BASIC string expression. Snapshot support is provided by the snapshot manager module.
.loadsnap
Load a snapshot file using a direct literal path.
.loadsnap filename
Example:
.loadsnap game.sna
%mv
Rename or move a file.
%mv "source","destination"
%mv source$,destination$
Example:
%mv "old.txt","new.txt"
.mv
Rename or move a file using direct literal paths.
.mv source,destination
Example:
.mv old.txt,new.txt
%cp
Copy a file.
%cp "source","destination"
%cp source$,destination$
Example:
%cp "readme.txt","backup.txt"
.cp
Copy a file using direct literal paths.
.cp source,destination
Example:
.cp readme.txt,backup.txt
%rm
Remove a file.
%rm "filename"
%rm file$
Example:
%rm "old.log"
.rm
Remove a file using a direct literal path.
.rm filename
Example:
.rm old.log
%mkdir
Create a directory.
%mkdir "path"
%mkdir path$
Example:
%mkdir "games"
.mkdir
Create a directory using a direct literal path.
.mkdir path
Example:
.mkdir games
%rmdir
Remove a directory.
%rmdir "path"
%rmdir path$
The directory must be removable by the underlying filesystem.
.rmdir
Remove a directory using a direct literal path.
.rmdir path
Example:
.rmdir olddir
%chmod
Change file mode or send a filesystem-specific control flag.
%chmod "filename", mode
%chmod file$, mode
On Spectranext's local XFS filesystem, normal writes go to the RAM layer first. To make a file survive power loss, commit it to the overlayed flash layer with mode 32768.
10 %mount "xfs://ram/"
20 %fopen #4, "snapshot.sna", "w"
30 REM save or write file contents here
40 %close #4
50 %chmod "snapshot.sna", 32768
The value 32768 is the Spectranext XFS commit-to-flash control flag. After the command finishes, the file remains visible in the same filesystem path but is stored in flash.
.chmod
Change file mode or send a filesystem-specific control flag using a direct literal path.
.chmod filename, mode
Example:
.chmod snapshot.sna,32768
The filename is raw, but the mode is still parsed as a BASIC number.
%connect
Open a TCP client stream and connect it to a host.
%connect #stream, "hostname", port
Example:
%connect #4, "example.com", 80
The stream can then be used with normal BASIC stream I/O, such as PRINT #4;.
%listen
Open a listening TCP stream.
%listen #stream, port
Example:
%listen #4, 2000
%accept
Accept an incoming connection on a listening stream.
%accept #stream, port
Example:
%accept #5, 2000
This command is part of the development stream/socket interface.
%close
Close an open stream.
%close #stream
Example:
%close #4
Close streams when you are done with them. Open sockets, files, and directories consume limited resources.
%fopen
Open a file as a BASIC stream.
%fopen #stream, "filename", "mode"
The mode string is made from these letters:
rreadwwriteaappendccreatettruncate
If a file is opened writable and no explicit create/truncate/append flag is supplied, the firmware uses create-and-truncate defaults.
Examples:
10 %fopen #4, "readme.txt", "r"
20 INPUT #4; A$
30 %close #4
10 %fopen #4, "out.txt", "w"
20 PRINT #4; "Hello"
30 %close #4
%opendir
Open a directory as a BASIC stream.
%opendir #stream, "path"
Example:
%opendir #4, "/"
Directory streams are read-only and are intended for programs that want to enumerate directory entries through the stream subsystem.
%seek
Seek to an absolute position in an open file stream.
%seek #stream, position
Example:
%seek #4, 0
The current implementation parses the position as a 16-bit BASIC integer.
%oneof
Set the BASIC line number to jump to when a stream reaches EOF.
%oneof line
Example:
10 %oneof 1000
This is part of the development stream interface.
%reclaim
Reclaim stream memory.
%reclaim
Use this after stream-heavy development sessions if stream memory needs to be cleaned up.
%control
Open a stream control channel.
%control #stream
Example:
%control #15
This is a low-level development command for the stream subsystem.
%fsconfig
Open the filesystem configuration UI.
%fsconfig
Use this for interactive filesystem configuration.
%ifconfig
Open the network configuration UI.
%ifconfig
This command is currently view-only in Spectranext.
%cfgset
Set a numeric configuration value.
%cfgset section,id,value
The section, id, and value arguments are numeric. The configuration item ID encodes the value type expected by the firmware.
%cfgset$
Set a string configuration value.
%cfgset$ section,id,"value"
%cfgset$ section,id,value$
Use this for configuration entries whose value is a string.
%cfgcommit
Commit pending configuration changes.
%cfgcommit
Configuration writes are staged in RAM first. Use %cfgcommit to persist them.
%cfgabandon
Discard pending configuration changes.
%cfgabandon
This abandons the RAM copy of edited configuration and leaves persisted configuration unchanged.
%cfgnew
Create a new empty configuration.
%cfgnew
This overwrites any existing configuration when committed. Use with care.
%cfgnewsec
Create a new configuration section.
%cfgnewsec section
Example:
%cfgnewsec 4096
%cfgrm
Remove a configuration item from a section.
%cfgrm section,id
Example:
%cfgrm 4096,1