trs80-tool is a command-line tool for inspecting and
manipulating TRS-80 files, cassettes, and floppies. Its source code is
available on Github.
You can download stand-alone binaries of the latest version:
On Linux and macOS you’ll need to make the file executable:
% chmod +x trs80-toolOn macOS you’ll additionally have to remove the quarantine:
% xattr -d -r com.apple.quarantine trs80-toolThe trs80-tool program supports these file formats:
.BASPRINT are stored as a single byte), but the tool supports reading Basic programs
that are in text (non-tokenized) format. When writing a file with a .BAS extension,
the file is always tokenized..ASC.WAV.CAS.CMD.SYS.CMD, but is meant to store system code
in a disk operating system. Can also store the boot sector, in which
case it's not in .CMD format, it's just the raw bytes..3BN.CAS files..L1.JV1.JV3.JV1 because it can encode a mix of FM and MFM signals on the same track..DMK.DSK.JV1,
.JV3, or .DMK file. Use the
info command to find out..SCP.ASM.CMD, .SYS, or
.3BN file using the disasm command..LSTasm or disasm commands’
--listing flag..ROM.BIN.ROM..HEXThe tool takes a command as its first argument:
% trs80-tool COMMAND args ...Global flags are:
--version Show the tool's version number.
--help Show the usage message.
--color=COLOR Force color mode (off, 16, 256, 16m, or auto).By default trs80-tool detects the color capabilities of the terminal
and sets the --color flag automatically. You can override this, either
to turn off color (if it bothers you) or to force it on (when piping into
a pager). For example:
% trs80-tool --color=16 hexdump in.cmd | less--trace=MODULE show trace logs for module (base, emulator, floppy).Show tracing logs for the specified module. These log lines can reveal how the module makes various decisions, and can help debugging. This flag is mostly intended for the developer, but can help explain why (for example) a specific floppy isn't being recognized. The “base” module deals with TRS-80 file formats; the “emulator” module is the TRS-80 emulator itself; and the “floppy” module is for floppy-related messages. Repeat the option to enable tracing for multiple modules.
dirThe dir command shows the contents of an archive file. Archives
files are those that can contain other files. These are cassette files
(in WAV or CAS format) and floppy disks (in JV1, JV3, DMK, or SCP format).
% trs80-tool dir FILEThe output format depends on the type of archive. Cassette files show baud rates, whereas floppy disks show creation date and type of file.
Normally system file are hidden, but can be shown by specifying
the --system option.
infoThe info command takes a list of filenames and displays a one-line
description of the contents of the file, such as its type (system
program, Basic program) and, if known, the embedded filename.
% trs80-tool info in1.cmd in2.bas in3.cas in4.wavThe --verbose flag displays some information (like floppy geometry) for
some file types:
% trs80-tool info --verbose in1.dmk in2.dskThe --json flag dumps (almost) everything we know about the
file in JSON format. This is currently used as part of a regressions suite
for floppies, but may also be useful to an AI agent.
convertThe convert command converts a list of input files to an output file or
directory. There are several different ways to use this command.
A single file can be converted to another format:
% trs80-tool convert in.cmd out.3bn (diskette to cassette format)
% trs80-tool convert in.bas out.asc (de-tokenize Basic program)Several files can be put into an archive:
% trs80-tool convert in1.bas in2.3bn in3.cmd out.wavThis creates a cassette audio file containing the three files. Note that the
.CMD file will be converted to .3BN format.
Archive files can be extracted if the destination is a directory:
% mkdir out
% trs80-tool convert in.wav out (decode cassette and extract files)
% trs80-tool convert in.cas out
% trs80-tool convert in.dmk outUse the --system flag to include system files from floppies.
Archive files can be converted to other archive formats:
% trs80-tool convert in.dmk out.wav
% trs80-tool convert in.wav out.casWhen writing a cassette format, the baud rate of the input file will be used, if it's known:
% trs80-tool convert in1.cas in2.cas in3.cas out.wav(The baud rate can be guessed from the .CAS file contents.) If the
baud rate can't be guessed, 500 baud (low-speed) will be used:
% trs80-tool convert in1.bas in2.3bn out.wavThis can be overwritten using the --baud command-line flag:
% trs80-tool convert --baud 1500 in1.cas in2.cas in3.cas out.wav
% trs80-tool convert --baud 1500 in1.bas in2.3bn out.wavIf a system program doesn't have a built-in start address, one
will be guessed by the info command:
% trs80-tool info in.cas
in.cas: System program (VCEPRN, /17408) on a low speed cassetteThe start address can be set with the --start flag:
% trs80-tool convert --start 17408 in.cas out.cas
Wrote out.cas: System program (VCEPRN) in low speed CAS file
% trs80-tool info out.cas
out.cas: System program (VCEPRN) on a low speed cassetteThe address auto can be used to guess an appropriate start address:
% trs80-tool convert --start auto in.cas out.cas
Wrote out.cas: System program (VCEPRN) in low speed CAS fileWhen converting .BIN or .ROM files, the --start flag specifies
both the load address and the start address:
% trs80-tool convert --start 0x1024 in.rom out.cmdAn assembly language listing disassembly file can be generated from .CMD,
.SYS, and .3BN files:
% trs80-tool convert in.cmd out.asm
% trs80-tool convert in.3bn out.lstThe disassembler attempts to guess what is code and what is data. If the input program relocates itself, some entry points will be missing and code will instead be disassembled as data. You can explicitly list entry points:
% trs80-tool convert --entry 0x7059,0x7064,0x71B9,0x7263 in.cas out.lstSee also the disasm command.
hexdumpThe hexdump command displays a hex dump of the input file, with annotations.
See the --color flag for how to force coloring on or off.
By default the command will collapse consecutive identical lines:
% trs80-tool hexdump in.cmdUse the --no-collapse flag to turn off this collapsing:
% trs80-tool hexdump --no-collapse in.cmdsectorsThe sectors command displays a table of the sectors in a floppy disk. The columns
are the sectors and the rows are the tracks. For each sector a character is displayed:
- No sector.
S Single-density sector.
D Double-density sector.
X Deleted sector.
C CRC error (ID or data).
? Missing sector.Use the --contents flag to also show the contents of the sectors.
The --bad flag lists all sectors that are missing or that
have a CRC error, as well as which file (if any) is on each bad sector.
Can be combined with --contents to also show the contents of the
bad sectors.
asmThe asm command assembles the specified assembly language source code:
% trs80-tool asm program.asm program.cmdIt can generate .CMD, .3BN, .CAS, .WAV,
BIN, or HEX files. For .CAS or
.WAV files the default baud rate is 500, but can be set with the --baud
flag:
% trs80-tool asm --baud 1500 program.asm program.casA listing file can be generated with the --listing flag:
% trs80-tool asm --listing program.lst program.asm program.cmddisasmThe disasm command disassembles the specified program:
% trs80-tool disasm saucer.cmdIf the program is a .CMD, .SYS, or .3BN file, it is loaded into the correct place
in memory. If it's a .ROM or .BIN file, it is loaded at 0x0000, but this
can be change with the --org flag:
% trs80-tool disasm --org 0x8000 file.binThe disassembler tries to guess which bytes are code and which are data by
following the path of the program, starting with its main entry point. Additional
entry points can be specified with the --entry flag:
% trs80-tool disasm --entry 0x0000,0x3799,0x377B model3.romNote that if any entry point is listed, then 0x0000 must be specified again if
applicable. If you wish to disable this “smart” disassembly and just disassemble continuously
through the program, specify the --full flag. If you specify this flag, bytes
that were originally data will be disassembled too. To make these bytes easier to find,
specify the --data-comment flag, which adds a comment to each instruction with
the ASCII of the instructions's bytes.
The output can be controlled with --no-labels to not create labels
for jump targets and --no-known to not reference known ROM addresses. The
--hex-format flag controls the format of hex numbers, which can be c
for 0x12 (the default), dollar for $12, or h for 12h.
A listing file can instead be generated with the --listing flag:
% trs80-tool disasm --listing program.cmdThe --no-binary flag will suppress opcode binary in the listing.
The --upper flag will generate upper case assembly language.
runRun a TRS-80 emulator in the shell:
% trs80-tool runThis is experimental and does not currently work well with games, and may not work at all in a Microsoft Windows shell.
Use the --model flag to specify the model (1, 3, or 4, defaults to 3) and
the --level flag to specify the Basic level (1 or 2, defaults to 2).
% trs80-tool run --model 1 --level 1Specify a program or floppy to load and run directly:
% trs80-tool run tdos13a.dsk
% trs80-tool run frogger.cmdUse the --mount flag to specify a cassette
or floppy to mount:
% trs80-tool run --mount in.casOnly one cassette may be mounted, but several floppies can be specified and will be assigned to consecutive drives, starting at 0:
% trs80-tool run --mount in.cas in1.dmk in2.dmk in3.dmkIf, from within the emulator, you modify the floppy, the virtual file
will be modified as well. Specify the --write-protected option
to mount all floppies as write-protected.
The --xray flag shows nothing in the shell but starts a web server
for the X-ray debugger. This is experimental and not yet documented.
replStarts an interactive session for exploring the Z80. Type help to get
a list of commands. Type an assembly language instruction (such as ld a,5)
to assemble it, write it to memory, explain it, execute it, and show
its effects on flags and registers. This virtual machine is not in
a TRS-80 context (it has no ROM or peripherals).
mcpRuns an MCP server on stdin/stdout, which lets an AI assistant drive a TRS-80 directly. The assistant can boot a ROM, type at it, run it for an exact number of clock cycles, and inspect the screen, memory, and registers. The machine stays running between requests, so the assistant can explore interactively instead of guessing.
You don’t run this command yourself. Your AI tool starts it for you, so what you do is tell that tool about it. With Claude Code:
% claude mcp add --scope user trs80 -- trs80-tool mcpOther MCP clients use a JSON configuration file. The entry looks like this:
{
"mcpServers": {
"trs80": {
"command": "trs80-tool",
"args": ["mcp"]
}
}
}In both cases trs80-tool must be on your PATH. If it isn’t,
use the full path to the binary instead. MCP servers are started when your AI tool
starts, so restart it after adding this.
These are the tools the assistant gets:
boot — start a machine, either with the stock Basic ROM or with a
.cmd file that replaces the ROM. On the stock ROM it answers the
Cass? and Memory Size? questions and waits for
READY.load_program — load and start a program file on the running machine.load_basic — put a Basic listing straight into memory on the stock ROM,
much faster than typing it.type — type text at the keyboard, waiting until the ROM has taken every key.key — press or release a single key and leave it that way, for
programs that care whether a key is held down.run — run for a number of clock cycles or emulated seconds.step — single-step the CPU.run_until_pc — run until the program counter reaches an address.run_until_screen — run until some text appears on the screen, and
report roughly how long it took.run_until_memory — run until a memory location holds a value, and
report exactly how long it took. This is how you time a program precisely, for
example by waiting for the first and last bytes of a screen fill.screen — read the screen as text.read_memory, write_memory, registers.search_memory — find a byte sequence, for locating code in ROM.disassemble — disassemble straight out of memory, ROM included.profile_pc — run for a while and report where the program counter
spent its time, as a histogram of the hottest addresses.call_routine — call a machine-language routine with chosen registers
and report exactly how many clock cycles it took, the way another program calling
it would see it.Timings are reported in Z80 clock cycles (t-states) rather than wall-clock time, so they’re exact and repeatable no matter how fast the emulator happens to run on your machine.
helpThe help command shows more specific information about other commands:
% trs80-tool help dir
% trs80-tool help convertThis change log covers the tool and the related web apps
(My TRS-80,
the IDE,
and the cassette reader).
Run trs80-tool --version to see which version you have.
trs80-tool v2.9.1: Added a --json flag
to the info command.trs80-tool v2.9.0: Added the mcp
command, which runs an MCP server so that an AI assistant can drive the emulator.trs80-tool v2.8.12: Improvements to the disasm command:
FLT,
DVR, and OV? files will
be treated like CMD files.CAS and WAV files can be
disassembled directly. If multiple programs are on the
cassette, only the first will be disassembled.trs80-tool v2.8.11: The --full flag of the
disasm command no longer causes jump targets to be
disassembled. The assumption is that all code is sequential.trs80-tool v2.8.10: Instructions from the disasm
command are now canonical when there are variants. For example, it will
generate or b where it used to generate or a,b.rst ones.trs80-tool v2.8.9: Improvements to the disasm command:
--no-labels flag, jumps to the
current address will list the address and not the $ symbol.DEFB instead of .BYTE.trs80-tool v2.8.8:
--system flag to the convert command
to extract system files from floppies.disasm command understands LDOS-style PDS files for
SYS6.SYS and SYS7.SYS, disassembling each
overlay separately.trs80-tool v2.8.7: Disassemble VTOS .SYS files better
by handling the CMD block type 0x10 (yanked load block) like 0x01 (data).trs80-tool v2.8.6: Handle .SYS files that are raw dumps
of floppy boot sectors. These work with the info,
hexdump, and disasm commands.trs80-tool v2.8.3: Add --full and
--data-comment flags to the disasm command.trs80-tool v2.8.2: Fix a bug in the display of file sizes in the
dir command.SYSTEM BASIC command to start the load.trs80-tool v2.8.1: Suppress some confusing warnings regarding
copy-protected or damaged DMK files.trs80-tool v2.8.0: The sectors command has a new
--bad option to show only missing or corrupted sectors, as well
as which file (if any) is on each bad sector. Can be combined with
--contents to also show the contents of the bad sectors.trs80-tool v2.7.0:
run command, if the mounted floppy is modified,
the changes will be written to the underlying virtual floppy file.
Specify the --write-protected option to mount the floppy
write-protected.dir command has a new --system option
to show system files.trs80-tool v2.6.0: Add --upper flag to the
disasm command.nv and v for
po and pe flags.% as binary
prefix. Instead of writing %1010,
use 1010b or 0b1010.trs80-tool v2.5.0:
info --verbose.run command.run command..ASC file)..CAS files to avoid misdetection
of cassette headers.trs80-tool v2.4.1: The convert command can go from
.ROM and .BIN files to .CMD and
.3BN files. The --start flag specifies the load
and start address.trs80-tool v2.4.0:
repl command.--no-labels, --no-known, --hex-format,
and --no-binary flags to the disasm command.trs80-tool v2.3.1: Use braille for graphics characters.trs80-tool v2.3.0:
run command.asm command.trs80-tool v2.2.0:
sectors command.--verbose flag to info command to display
floppy geometry.disasm command.trs80-tool v2.1.0: Add hexdump command.trs80-tool v2.0.10: Add --entry flag to help with
disassembling programs that relocate themselves.trs80-tool v2.0.8:
info command will display a guessed start address for
system programs with no specified start address.--start flag to set the start address of system files.trs80-tool v2.0.7: Can read high-speed CAS files with non-aligned bytes.trs80-tool v2.0.6:
info command.convert command.trs80-tool v2.0.5: Can write multi-file CAS files.trs80-tool v2.0.4:
trs80-tool v2.0.3: Initial release.