plus3 manual

plus3 is a command-line tool for creating, managing, and extracting files from +3DOS disk images (.dsk) as used by the ZX Spectrum +3. This manual documents every command and flag. For the library API see LIBRARY-USAGE.md; for format details see PLUS3DOS-PITFALLS.md.

Synopsis

plus3 <command> [flags] [arguments]

Flags may appear before or after the positional arguments, so both plus3 create disk.dsk --force and plus3 create --force disk.dsk are accepted.

Run plus3 <command> -h to see the flags for any command, plus3 --help for the command list, and plus3 --version for the version.

Numbers for --load-addr and --line accept decimal (32768) or hexadecimal (0x8000).

Commands

• create - create a new blank disk image
• add - add a file to a disk image
• list - list the catalogue
• info - show disk usage and details
• extract - extract a file to the host (or detokenise BASIC)
• delete - delete a file

create

Create a new, blank +3DOS disk image in the standard single-sided +3 format (40 tracks, 9 sectors per track, 512-byte sectors, 1 KB blocks, 64-entry directory).

plus3 create [flags] <disk.dsk>

Examples:

plus3 create game.dsk
plus3 create game.dsk --label MYGAME --force

add

Add a host file to a disk image, writing a correct PLUS3DOS header and managing block allocation and the directory.

plus3 add [flags] <disk.dsk> <file>

-t and --type are equivalent. With auto, the type is chosen from the host file's extension:

Type notes:

• code - a machine-code block. --load-addr sets the address it loads to.
• basic - an already-tokenised BASIC program, stored verbatim. --line sets the auto-run line (use a value of 32768 or above for no auto-run).
• basictext - plain-text BASIC source, which is tokenised on import. Each source line must begin with a line number, e.g. 10 CLEAR 32767: LOAD "game"CODE: RANDOMIZE USR 32768. The tokeniser covers keywords, integer constants (0-65535), string literals, and REM comments; keywords inside strings and after REM are left literal. It does not produce floating-point literals, DEF FN calculator slots, or embedded colour-control bytes, so for programs that rely on those, tokenise with a full toolchain and add the result with -t basic.
• screen - a SCREEN$ dump. The host file must be exactly 6912 bytes (6144 pixel bytes plus 768 attribute bytes); other sizes are rejected.
• raw - the bytes are stored as-is.

As a safeguard, add prints an advisory warning (to standard error, suppressed by --quiet) when the input looks like the wrong BASIC form for the chosen type: if -t basictext is given input that already parses as tokenised BASIC, or -t basic is given plain-text source. The operation still proceeds exactly as asked; the warning only flags a likely mistake.

The on-disk name is derived from the host filename (8.3, upper-cased).

Examples:

plus3 add game.dsk loader.bas -t basic     --line 10   # already tokenised
plus3 add game.dsk loader.txt -t basictext --line 10   # plain-text source
plus3 add game.dsk game.bin   -t code --load-addr 0x8000
plus3 add game.dsk title.scr  -t screen
plus3 add game.dsk data.dat   -t raw --force

list

List the catalogue of files on a disk image.

plus3 list [flags] <disk.dsk>

Examples:

plus3 list game.dsk
plus3 list game.dsk --sort size --reverse
plus3 list game.dsk --pattern '*.BAS' --long
plus3 list game.dsk --json

info

Show summary information about a disk image: file count, space used and free, and format details.

plus3 info [flags] <disk.dsk>

--validate is on by default; the check is a structural sanity check on the image, not a guarantee that a real +3 will accept every file.

Examples:

plus3 info game.dsk
plus3 info game.dsk --verbose
plus3 info game.dsk --json

extract

Extract a file from a disk image back to the host, or detokenise a BASIC program to readable text.

plus3 extract [flags] <disk.dsk> <name>

-o and --output-dir are equivalent and name a directory (it is created if needed); the output filename is taken from the disk file's name. Extraction uses the PLUS3DOS header's length field, so it is byte-exact rather than rounded to the record size.

With --basic, the program is detokenised to readable text. Without -o the text goes to standard output; with -o <dir> it is written to <name>.txt in that directory.

If a file whose header marks it as a tokenised BASIC program is extracted without --basic, extract prints an advisory warning (suppressed by --quiet) suggesting --basic. The extraction still proceeds as asked.

Examples:

plus3 extract game.dsk GAME.BIN -o outdir
plus3 extract game.dsk GAME.BIN -o outdir --strip-header
plus3 extract game.dsk LOADER.BAS --basic
plus3 extract game.dsk LOADER.BAS --basic -o outdir

delete

Delete a file from a disk image, freeing its blocks.

plus3 delete [flags] <disk.dsk> <name>

Examples:

plus3 delete game.dsk GAME.BIN --force

Exit status

plus3 returns a non-zero exit status and prints an Error: message to standard error when a command fails (for example, a missing disk image, a wrong-sized screen file, or an existing output file without --force / --overwrite). On success it returns zero.