The `disc` CLI¶

The disc command-line tool provides a unified interface for working with Acorn DFS, ADFS, and AFS disc images. Install it with:

uv add oaknut-disc

Both disc and oaknut-disc are registered as console scripts – use whichever you prefer.

Filing-system prefixes¶

When a disc image carries multiple partitions (e.g. an ADFS hard disc with an AFS tail partition), prefix the in-image path to select the target partition:

disc ls scsi0.dat              # default: ADFS root
disc ls scsi0.dat adfs:'$'     # explicit ADFS
disc ls scsi0.dat 'afs:$'      # AFS root
disc cat scsi0.dat 'afs:$.Library.Free'

The prefix is case-insensitive (afs:, AFS:, Afs: all work). When no prefix is given, the filing system is auto-detected from the image extension (.ssd/.dsd for DFS, .adf/.adl/.dat for ADFS).

Mismatches are rejected immediately:

$ disc ls games.ssd 'adfs:$'
Error: image is DFS format; cannot access as ADFS

Acorn star-aliases¶

Acorn-style aliases are accepted alongside the Unix command names. They must be quoted or escaped on POSIX shells because of the * prefix:

disc '*CAT' games.ssd       # same as: disc ls games.ssd
disc '*TYPE' games.ssd '$.HELLO'   # same as: disc cat

Unix command	Acorn alias
`ls`	`*CAT`
`cat`	`*TYPE`
`rm`	`*DELETE`
`mv`	`*RENAME`
`cp`	`*COPY`
`chmod`	`*ACCESS`
`mkdir`	`*CDIR`
`title`	`*TITLE`
`opt`	`*OPT4`
`stat`	`*INFO`

Cross-image copy¶

The cp command uses image:path colon syntax for copying files between disc images of any format combination:

disc cp source.ssd:'$.HELLO' target.dat:'$.HELLO'

Load and exec addresses are preserved. Access attributes are mapped as losslessly as the target format allows (e.g. DFS only has a locked bit, so public-read from ADFS is dropped).

For within-image copies, use the three-argument form:

disc cp image.adl '$.Original' '$.Copy'

Creating a Level 3 File Server disc¶

A complete walkthrough for building a bootable L3FS hard disc image:

# Create a 10 MiB ADFS hard disc image
disc create scsi0.dat --format adfs-hard --capacity 10MiB --title Server

# Copy the file server binary from its DFS floppy
disc cp FS3v126.ssd:'$.FS3v126' scsi0.dat:'$.FS3v126'

# Create a !BOOT file and set the boot option
printf '*RUN $.FS3v126\r' | disc put scsi0.dat '$.!BOOT' -
disc opt scsi0.dat 3

# Plan the AFS partition (shows geometry, free space, suggested command)
disc afs-plan scsi0.dat

# Initialise AFS with users and libraries
disc afs-init scsi0.dat --disc-name Server --cylinders 309 \
  --user Syst:S --user RJS:2MiB \
  --emplace Library --emplace Library1

# Inspect the result
disc tree scsi0.dat

The --emplace option accepts either a shipped library name (Library, Library1, ArthurLib) or a path to any ADFS .adl image. Everything in the image is copied into a directory of the same name on the AFS partition.

Shell quoting¶

Acorn paths contain characters that POSIX shells interpret specially. Use single quotes to prevent expansion:

$ – shell variable prefix
! – zsh history expansion
* – glob character (for star-aliases)

disc cat image.dat '$.!BOOT'     # single quotes: safe
disc cat image.dat "$.!BOOT"     # double quotes: zsh expands !
disc '\*CAT' image.dat           # backslash-escape the *

The disc CLI¶