Command reference¶

Every disc subcommand, grouped by purpose. Each entry’s arguments, options, Acorn star-aliases, and report set are live introspections of oaknut.disc.cli, so the page cannot drift from what the installed binary accepts.

The repeated report-output flags (--no-reports, --report, --header, --detailed) are described once in Output formats: --as — only the format selector --as is repeated on each command below.

Inspection¶

disc ls¶

List directory contents (Acorn alias: *CAT).

Accepts a COMPOUND_PATH (the in-image INNER_PATH is optional and defaults to the root).

Usage

disc ls [OPTIONS] OUTER:INNER

Arguments

OUTER:INNER

Options

-H, --access-byte: Show the raw access byte as two hex digits alongside the symbolic form.
--as [display|json|tsv]: Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

The standard report-output flags — --report, --no-reports, --all-reports, --header/--no-header, --detailed/--essential — are also accepted; see Output formats: --as.

Reports

entries: Directory entries with load/exec/length/attributes.

Acorn aliases

*CAT

Examples

$ disc ls 'arcadians.ssd:$'
              arcadians.ssd — ARC (acorn-dfs)               
┏━━━━━━━━━┳━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━┓
┃ Name    ┃ Type ┃ Load       ┃ Exec       ┃ Length ┃ Attr ┃
┡━━━━━━━━━╇━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━┩
│ !BOOT   │ file │ 0x00000000 │ 0x00000000 │ 44     │ LWR/ │
│ ARC     │ file │ 0x00001900 │ 0x00001900 │ 2304   │ LWR/ │
│ Arcadi2 │ file │ 0x00001900 │ 0x00003F00 │ 19456  │ LWR/ │
│ ARCADIA │ file │ 0x00001900 │ 0x0000801F │ 1203   │ LWR/ │
└─────────┴──────┴────────────┴────────────┴────────┴──────┘
                    Free: 180,992 bytes                     

disc tree¶

Display recursive directory tree.

Accepts a COMPOUND_PATH (the in-image INNER_PATH is optional and defaults to the root).

Usage

disc tree [OPTIONS] OUTER:INNER

Arguments

OUTER:INNER

Options

--as [display|json|tsv]: Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

The standard report-output flags — --report, --no-reports, --all-reports, --header/--no-header, --detailed/--essential — are also accepted; see Output formats: --as.

Reports

tree: Hierarchical directory listing.

Examples

$ disc tree demo.adl
demo.adl
├── Code
│   └── Hello
└── Docs
    └── README

disc stat¶

Disc summary (no path) or file metadata (with path). Alias: *INFO.

With no in-partition path, summarises the disc by walking its partition structure: a disc envelope plus one block per partition on a partitioned disc, or a single block otherwise. With a path, reports that file’s metadata.

Accepts a COMPOUND_PATH (the in-image INNER_PATH is optional and defaults to the root).

Usage

disc stat [OPTIONS] OUTER:INNER

Arguments

OUTER:INNER

Options

--as [display|json|tsv]: Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

The standard report-output flags — --report, --no-reports, --all-reports, --header/--no-header, --detailed/--essential — are also accepted; see Output formats: --as.

Reports

disc: Physical envelope (geometry + total size). Emitted only on a multi-partition disc (ADFS + AFS), where it carries information distinct from each partition. Single-partition images fold this content into ``partition_1``.
partition_1: First partition’s summary. Stands alone (carrying the disc geometry) on a single-partition image; on a partitioned disc it is the host slice and ``disc`` carries the geometry.
partition_2: Second partition (AFS on a partitioned disc; also the report name when an ``afs:`` prefix scopes the view to that half).
volume_1: First volume of a multi-volume single partition — side ``:0`` of a double-sided DFS disc.
volume_2: Second volume — side ``:2`` of a double-sided DFS disc.
file: Per-file metadata when the path denotes a file.

Acorn aliases

*INFO

Examples

$ disc stat arcadians.ssd
         ACORN-DFS         
┏━━━━━━━━━━━━━┳━━━━━━━━━━━┓
┃ Title       ┃ ARC       ┃
┡━━━━━━━━━━━━━╇━━━━━━━━━━━┩
│ Size        │ 200.0 KiB │
│ Free        │ 176.8 KiB │
│ Boot option │ EXEC (3)  │
│ Files       │ 4         │
└─────────────┴───────────┘

disc find¶

Find files matching an Acorn wildcard pattern.

Accepts an OUTER_PATH (lists every file) or a COMPOUND_PATH whose INNER_PATH is the wildcard pattern.

Accepts the same adfs: / afs: / dfs: prefixes as every other command to scope the search to a single partition. Without a prefix, partitioned hard-disc images (ADFS + AFS) are searched in their entirety and each result is emitted with the partition prefix that would feed back into a follow-up command unchanged. Single-partition images emit bare paths, unchanged from earlier behaviour.

Usage

disc find [OPTIONS] OUTER:INNER

Arguments

OUTER:INNER

Options

--as [display|json|tsv]: Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

The standard report-output flags — --report, --no-reports, --all-reports, --header/--no-header, --detailed/--essential — are also accepted; see Output formats: --as.

Reports

matches: Paths matching the wildcard pattern.

Examples

$ disc find 'infinity.ssd:*Edit'
   matches   
┏━━━━━━━━━━━┓
┃ Path      ┃
┡━━━━━━━━━━━┩
│ $.MapEdit │
│ $.DefEdit │
│ $.SprEdit │
└───────────┘

disc for-each¶

Run a command for each file matching an inner-path pattern.

Use -- to separate disc’s options from the command’s, so flags meant for the command are not interpreted by for-each:

disc for-each 'img:*' -- md5sum

The --mode option picks one of four ways to present each file to the command:

--mode content (the default) pipes the file’s bytes to the command’s standard input. The shape for md5sum, sha256sum, xxd and other tools that read stdin.
--mode inner-path passes the file’s in-image path as a string — $.HELLO on DFS, Docs/Readme on a ZIP, whatever the filesystem’s syntax. For tools that want a path for logging, templating, or filtering by name.
--mode compound-path passes the full OUTER:INNER, so the rest of the disc CLI itself can act per file — disc cat, disc lock, disc set-load and so on.
--mode materialise writes the file’s bytes to a host temp file and passes that host path. For tools that only take real files (file(1), image viewers, emulators).

For every mode except content, a per-file value has to reach the command somewhere. By default it is appended as the last argument (the same rule find -exec uses). Include the literal {} token in the command’s args to put the value somewhere else — every {} is replaced per file by the value --mode selected.

The search recurses into subdirectories by default and skips directories (they have no content to operate on). The adfs: / afs: / acorn-dfs: partition selector scopes the search; without one, every identified partition is searched and each result is emitted with the selector that addresses it.

Usage

disc for-each [OPTIONS] OUTER:INNER [-- COMMAND......]

Arguments

OUTER:INNER
-- COMMAND... (nargs=-1)

Options

--mode [content|inner-path|compound-path|materialise]: How each file is presented to the command. See the command description above for what each choice does.
--as [display|json|tsv]: Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

The standard report-output flags — --report, --no-reports, --all-reports, --header/--no-header, --detailed/--essential — are also accepted; see Output formats: --as.

Reports

results: Per-file capture: path and the command’s stdout, one row per match.

Examples

--mode content (default) — each file’s bytes are piped to the command’s stdin. The shape that produces a path/output TSV for md5sum, sha256sum, xxd, and friends:

$ disc for-each 'demo.ssd:*' -- md5sum
# Path    Output
$.C       69faab6268350295550de7d587bc323d  -
$.B       08cf82251c975a5e9734699fadf5e9c0  -
$.A       5d41402abc4b2a76b9719d911017c592  -

--mode inner-path — the in-image path string is substituted into {} (or appended, find-style). For tools that take a path as a string without needing to open it — templating, logging, filtering:

$ disc for-each 'demo.ssd:*' --mode inner-path -- echo
# Path    Output
$.C       $.C
$.B       $.B
$.A       $.A

--mode compound-path — the full OUTER:INNER is substituted, so disc itself becomes the per-file action. The rest of the CLI composes without bespoke wrappers — disc cat, disc lock, disc set-load and any other addressable disc command:

$ disc for-each 'demo.ssd:*' --mode compound-path -- disc cat {}
# Path    Output
$.C       goodbye
$.B       world!
$.A       hello

--mode materialise — each file’s bytes are written to a host temp file and its path substituted, so host-native tools that only take regular files (file, image viewers, emulators) can be pointed at in-image contents without manual extraction:

$ disc for-each 'demo.ssd:*' --mode materialise -- file {}
# Path    Output
$.C       /tmp/oaknut-for-each-i1nzvd8h/0000-C: ASCII text, with no line terminators
$.B       /tmp/oaknut-for-each-i1nzvd8h/0001-B: ASCII text, with no line terminators
$.A       /tmp/oaknut-for-each-i1nzvd8h/0002-A: ASCII text, with no line terminators

disc materialise¶

Materialise one file to a host temp file, run a command on it, clean up.

The single-file primitive behind for-each --mode materialise: read the in-image file’s bytes, write them to a host temp file, substitute {} in the command’s args with that path (or append the path if no {} is present), run the command, then remove the temp file — even if the command fails.

Use it to point a host-native tool at an in-image file without extracting it manually:

disc materialise 'img:$.IMG' -- xdg-open {}
disc materialise 'img:$.PROG' -- ./run-emulator {}
disc materialise 'img:$.HELLO' -- file {}

The command’s stdout, stderr and exit code pass through unchanged.

Usage

disc materialise OUTER:INNER [-- COMMAND......]

Arguments

OUTER:INNER
-- COMMAND... (nargs=-1)

Examples

$ disc materialise 'demo.ssd:$.README' -- file {}
/tmp/oaknut-materialise-cebfcd8z/0000-README: ASCII text

disc freemap¶

Show the free-space map as a sector matrix.

Accepts a COMPOUND_PATH; a partition prefix scopes the map to that partition. Each cell is one sector — . free, █ used — laid out in rows sized to the terminal.

Usage

disc freemap OUTER:INNER

Arguments

OUTER:INNER

Examples

$ disc freemap planet.ssd
Legend: █ = used, . = free

   0 ███.........█████████████████████████████████████..........................
  75 ...........................................................................
 150 ...........................................................................
 225 ...........................................................................
 300 ...........................................................................
 375 .........................

Free: 360 of 400 sectors in 2 region(s) (largest 351 contiguous)

disc storage-order¶

List a partition’s files in physical storage order.

Files come out in the order their data lies on the medium — the sequence a sequential read encounters them, which on a seeking drive is also the fast-load order. This is the order cp reproduces and compact --order rearranges, so it is the way to confirm either.

A partition prefix (adfs: / afs: / dfs:) or a drive/side scopes the listing, like every other command. Errors on a filesystem with no defined storage order — its files have none, or are fragmented (AFS).

Usage

disc storage-order [OPTIONS] OUTER:INNER

Arguments

OUTER:INNER

Options

--as [display|json|tsv]: Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

The standard report-output flags — --report, --no-reports, --all-reports, --header/--no-header, --detailed/--essential — are also accepted; see Output formats: --as.

Reports

paths: File paths in physical (storage) order.

Examples

$ disc storage-order snapper.ssd
      storage order      
┏━━━━━━━━━━━┳━━━━━━━━━━━┓
┃ Path      ┃ Size      ┃
┡━━━━━━━━━━━╇━━━━━━━━━━━┩
│ $.!BOOT   │ 45 bytes  │
│ $.SNAP    │ 1.2 KiB   │
│ $.SNAPPER │ 1.5 KiB   │
│ $.Snap2   │ 674 bytes │
│ $.Snappe3 │ 9.9 KiB   │
└───────────┴───────────┘

disc validate¶

Check disc image structure for inconsistencies.

On a clean image, prints nothing and exits 0 — the silence-is-golden convention, so the command is composable with && in shell pipelines and CI scripts. On a damaged image, prints one Error: <description> line on stderr per defect detected, followed by an N error(s) found summary line, and exits with code 65 (EX_DATAERR).

DFS, ADFS floppies, and ADFS hard discs are supported. Defects surfaced include catalogue overflow, files extending past the end of the disc, two files claiming the same sector, duplicate filenames (DFS) and free-space-map checksum or structure problems (ADFS).

Usage

disc validate IMAGE

Arguments

IMAGE

Examples

$ disc validate clean.adl 2>&1; echo exit=$?
exit=0
$ disc validate bad.ssd 2>&1; echo exit=$?
Error: Sector 2 used by both $.A and $.B
1 error found
exit=65

disc cat¶

Dump file contents to stdout as raw bytes.

Accepts a COMPOUND_PATH.

Use disc type for Acorn text files — this command writes bytes verbatim, so files using Acorn \r line endings will render unreadably on a Unix terminal.

Usage

disc cat OUTER:INNER

Arguments

OUTER:INNER

Examples

$ disc cat 'arcadians.ssd:$.!BOOT' | xxd
00000000: 2a42 4153 4943 0d50 4147 453d 2631 3930  *BASIC.PAGE=&190
00000010: 300d 2a46 5832 310d 434c 4f53 4523 303a  0.*FX21.CLOSE#0:
00000020: 4348 4149 4e20 2241 5243 220d            CHAIN "ARC".

disc type¶

Display a text file with line endings translated for the host.

Accepts a COMPOUND_PATH.

Acorn text files terminate lines with \r (carriage return). Dumped raw to a Unix terminal each line overwrites the previous, so the file appears blank. This command translates \r, \n and \r\n to the host’s native line ending by default; override with --line-endings.

Acorn alias: *TYPE.

Usage

disc type [OPTIONS] OUTER:INNER

Arguments

OUTER:INNER

Options

--line-endings, -l [host|lf|crlf|cr|keep]: Translate line endings to: host = LF on macOS/Linux, CRLF on Windows; lf/crlf/cr = force a specific style; keep = no translation.

Acorn aliases

*TYPE

Examples

$ disc type 'arcadians.ssd:$.!BOOT'
*BASIC
PAGE=&1900
*FX21
CLOSE#0:CHAIN "ARC"

disc identify¶

Identify a disc image’s filesystem(s) by content, best guess first.

Reads the image rather than trusting its file extension, so it works even when the name is missing or wrong. Each candidate carries a confidence level — from CERTAIN (an unambiguous magic number) down to POSSIBLE — and the evidence behind it. A combined disc, such as an ADFS hard disc hosting an AFS tail partition, yields more than one row.

Usage

disc identify [OPTIONS] IMAGE_FILEPATH

Arguments

IMAGE_FILEPATH

Options

--as [display|json|tsv]: Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

The standard report-output flags — --report, --no-reports, --all-reports, --header/--no-header, --detailed/--essential — are also accepted; see Output formats: --as.

Reports

candidates: Ranked filesystem-identification candidates with evidence.

Examples

$ disc identify server.dat
                                   server.dat                                   
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Confidence ┃ Filesystem ┃ Partition ┃ Evidence                               ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ STRONG     │ adfs       │ adfs      │ old-format root directory ('Hugo');    │
│            │            │           │ old-map free-space-map checksums valid │
│ CERTAIN    │ afs        │ afs       │ AFS0 info sector (disc 'L3DATA');      │
│            │            │           │ redundant copy verified                │
└────────────┴────────────┴───────────┴────────────────────────────────────────┘

File transfer (host ↔ image)¶

disc get¶

Export a file from the image to the host filesystem.

Accepts a COMPOUND_PATH and an optional HOST_PATH.

When HOST_PATH is omitted, the file is written to the current working directory under its on-disc Acorn name. When HOST_PATH is -, the raw bytes go to stdout with no metadata sidecar — equivalent to disc cat. Otherwise HOST_PATH is the destination path on the host.

Acorn metadata (load address, exec address, access bits) is preserved alongside the data file according to --meta-format. The default inf-trad writes a traditional HOST_PATH.inf sidecar; xattr-acorn stashes the metadata in host extended attributes; filename-riscos/filename-mos encode it into the host filename; none drops it entirely. See Metadata across the host boundary for the full mapping and trade-offs.

Usage

disc get [OPTIONS] OUTER:INNER [HOST_PATH]

Arguments

OUTER:INNER
HOST_PATH (optional)

Options

--meta-format [inf-trad|inf-pieb|xattr-acorn|xattr-pieb|filename-riscos|filename-mos|none]: Metadata sidecar format.
--owner INT: Econet owner ID for PiEB formats.

Examples

$ disc get 'arcadians.ssd:$.!BOOT'
$ ls !BOOT*
!BOOT
!BOOT.inf

disc put¶

Import a host file into the image.

Accepts a COMPOUND_PATH (the in-image destination) and a HOST_PATH.

HOST_PATH is required. When it is -, the raw bytes are read from stdin with no metadata-sidecar lookup; supply --load / --exec to set the addresses, otherwise they default to 0xFFFF (the Acorn “address not meaningful” sentinel). Otherwise HOST_PATH names the host file to import.

When reading from a host file, Acorn metadata (load address, exec address, access bits) is sourced from the surroundings of the data file according to --meta-format. With --meta-format omitted, the default cascade tries — in order — a traditional HOST_PATH.inf sidecar, then host extended attributes, then a RISC-OS filename suffix, stopping at the first hit. --load and --exec always win over what the cascade finds; their number base comes from the value’s prefix (0x for hex — e.g. 0x1900 — otherwise decimal), so a bare 1900 is decimal, not hex. See Metadata across the host boundary for the full mapping and trade-offs.

Usage

disc put [OPTIONS] OUTER:INNER [HOST_PATH]

Arguments

OUTER:INNER
HOST_PATH (optional)

Options

--load TEXT: Load address; base from prefix (0x hex e.g. 0x1900, else decimal).
--exec TEXT: Exec address; base from prefix (0x hex e.g. 0x8023, else decimal).
--meta-format [inf-trad|inf-pieb|xattr-acorn|xattr-pieb|filename-riscos|filename-mos|none]: Metadata format to read from host file.

Examples

$ disc put 'demo.ssd:$.GREET' greeting.txt
$ disc ls 'demo.ssd:$'
               demo.ssd — Demo (acorn-dfs)                
┏━━━━━━━┳━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━┓
┃ Name  ┃ Type ┃ Load       ┃ Exec       ┃ Length ┃ Attr ┃
┡━━━━━━━╇━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━┩
│ GREET │ file │ 0x00000000 │ 0x00000000 │ 21     │ WR/  │
└───────┴──────┴────────────┴────────────┴────────┴──────┘
                   Free: 204,032 bytes                    

disc export¶

Bulk-export entire image to a host directory.

Usage

disc export [OPTIONS] IMAGE HOST_DIR

Arguments

IMAGE
HOST_DIR

Options

--meta-format [inf-trad|inf-pieb|xattr-acorn|xattr-pieb|filename-riscos|filename-mos|none]: Metadata sidecar format.
--owner INT: Econet owner ID for PiEB formats.
-v, --verbose: Show extraction progress.

Examples

$ disc export arcadians.ssd out
$ ls -C 'out/$'
!BOOT  !BOOT.inf  ARC  ARC.inf    ARCADIA  ARCADIA.inf  Arcadi2  Arcadi2.inf

disc import¶

Bulk-import a host directory into the image.

Usage

disc import [OPTIONS] IMAGE HOST_DIR

Arguments

IMAGE
HOST_DIR

Options

--meta-format [inf-trad|inf-pieb|xattr-acorn|xattr-pieb|filename-riscos|filename-mos|none]: Metadata format to read from host files.
-v, --verbose: Show import progress.

Examples

$ disc import demo.adl host-tree
$ disc ls demo.adl
                 demo.adl — Demo (adfs)                  
┏━━━━━━┳━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━┓
┃ Name ┃ Type ┃ Load       ┃ Exec       ┃ Length ┃ Attr ┃
┡━━━━━━╇━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━┩
│ DOC1 │ file │ 0x00000000 │ 0x00000000 │ 16     │ /    │
│ DOC2 │ file │ 0x00000000 │ 0x00000000 │ 17     │ /    │
└──────┴──────┴────────────┴────────────┴────────┴──────┘
                   Free: 653,056 bytes                   

Modification (within an image)¶

disc cp¶

Copy file(s) or a tree within or between disc images.

Acorn alias: *COPY.

Accepts two COMPOUND_PATH arguments — source and destination. Cross-image copies are the normal case; for an in-image copy, name the same image on both sides (disc cp image.adl:$.Original image.adl:$.Copy).

Source paths may contain Acorn wildcards (* = any sequence, # = any single character); when a wildcard expands to multiple matches the destination must denote a directory — either trailing / or an existing directory. -r/--recursive copies a directory and everything under it, creating intermediate destination directories as needed. Copies across DFS, ADFS, and AFS in any combination; load/exec addresses are preserved and access attributes are mapped best-effort (DFS only has the locked bit).

Usage

disc cp [OPTIONS] SRC DST

Arguments

SRC
DST

Options

-f, --force: Overwrite existing destination.
-r, --recursive: Copy directories recursively.

Acorn aliases

*COPY

Examples

$ disc cp 'arcadians.ssd:$.!BOOT' 'archive.adl:$.!BOOT'
$ disc ls archive.adl
               archive.adl — Archive (adfs)               
┏━━━━━━━┳━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━┓
┃ Name  ┃ Type ┃ Load       ┃ Exec       ┃ Length ┃ Attr ┃
┡━━━━━━━╇━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━┩
│ !BOOT │ file │ 0x00000000 │ 0x00000000 │ 44     │ LWR/ │
└───────┴──────┴────────────┴────────────┴────────┴──────┘
                   Free: 653,312 bytes                    

disc mv¶

Rename or move a file within the image (Acorn alias: *RENAME).

Accepts two COMPOUND_PATH arguments — source and destination, both of which must name the same image. mv is single-image: the library renames a directory entry in place and cannot move across filesystems.

Usage

disc mv [OPTIONS] SRC DST

Arguments

SRC
DST

Options

-f, --force: Overwrite existing destination.

Acorn aliases

*RENAME

Examples

$ disc mv 'demo.adl:$.Notes' 'demo.adl:$.Memo'
$ disc ls demo.adl
                 demo.adl — Demo (adfs)                  
┏━━━━━━┳━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━┓
┃ Name ┃ Type ┃ Load       ┃ Exec       ┃ Length ┃ Attr ┃
┡━━━━━━╇━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━┩
│ Memo │ file │ 0x0000FFFF │ 0x0000FFFF │ 8      │ WR/R │
└──────┴──────┴────────────┴────────────┴────────┴──────┘
                   Free: 653,312 bytes                   

disc rm¶

Delete file(s) from the image (Acorn alias: *DELETE).

Accepts a COMPOUND_PATH followed by zero or more bare INNER_PATH arguments — the first entry to delete travels in the COMPOUND_PATH, additional in-image paths follow. Each path may contain Acorn wildcards (*, #); -r descends into directory matches and removes children before the directory itself.

Usage

disc rm [OPTIONS] OUTER:INNER [PATHS...]

Arguments

OUTER:INNER
PATHS (optional, nargs=-1)

Options

-f, --force: Ignore missing, override locks.
-r, --recursive: Remove directories recursively.
--dry-run: Print what would be removed.

Acorn aliases

*DELETE

Examples

$ disc rm 'demo.adl:$.Drop'
$ disc ls demo.adl
                 demo.adl — Demo (adfs)                  
┏━━━━━━┳━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━┓
┃ Name ┃ Type ┃ Load       ┃ Exec       ┃ Length ┃ Attr ┃
┡━━━━━━╇━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━┩
│ Keep │ file │ 0x0000FFFF │ 0x0000FFFF │ 3      │ WR/R │
└──────┴──────┴────────────┴────────────┴────────┴──────┘
                   Free: 653,312 bytes                   

disc mkdir¶

Create a directory (ADFS/AFS only). Alias: *CDIR.

Accepts a COMPOUND_PATH. --title additionally sets the new directory’s title, which only ADFS supports — passing it for an AFS directory is an error (DFS has no directories at all).

Usage

disc mkdir [OPTIONS] OUTER:INNER

Arguments

OUTER:INNER

Options

-p: Create missing parents and do not error if the directory already exists.
--title TEXT: Set the new directory’s title (ADFS only; DFS/AFS directories have none).

Acorn aliases

*CDIR

Examples

$ disc mkdir 'demo.adl:$.Docs' --title 'My Documents'
$ disc ls 'demo.adl:$'
           demo.adl — Demo (adfs)            
┏━━━━━━┳━━━━━━┳━━━━━━┳━━━━━━┳━━━━━━━━┳━━━━━━┓
┃ Name ┃ Type ┃ Load ┃ Exec ┃ Length ┃ Attr ┃
┡━━━━━━╇━━━━━━╇━━━━━━╇━━━━━━╇━━━━━━━━╇━━━━━━┩
│ Docs │ dir  │      │      │ 0      │      │
└──────┴──────┴──────┴──────┴────────┴──────┘
             Free: 652,288 bytes             

$ disc title 'demo.adl:$.Docs'
Title: My Documents

disc chmod¶

Set file access permissions (Acorn alias: *ACCESS).

Accepts a COMPOUND_PATH and an ACCESS.

ACCESS is symbolic (e.g. LWR/R, WR/WR) or hex (0x0B, 33). DFS only supports the L (locked) bit; other flags are ignored.

PATH may contain Acorn wildcards (*, #) to apply the same access to every matching file. -r recurses into any directory match.

Usage

disc chmod [OPTIONS] OUTER:INNER ACCESS

Arguments

OUTER:INNER
ACCESS

Options

-r, --recursive: Recurse into directory matches.
--dry-run: Print what would change without modifying the image.

Acorn aliases

*ACCESS

Examples

$ disc chmod 'demo.adl:$.File' LWR/R
$ disc ls demo.adl
                  demo.adl — Demo (adfs)                  
┏━━━━━━┳━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━┓
┃ Name ┃ Type ┃ Load       ┃ Exec       ┃ Length ┃ Attr  ┃
┡━━━━━━╇━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━┩
│ File │ file │ 0x0000FFFF │ 0x0000FFFF │ 8      │ LWR/R │
└──────┴──────┴────────────┴────────────┴────────┴───────┘
                   Free: 653,312 bytes                    

disc lock¶

Lock a file.

Accepts a COMPOUND_PATH. PATH may be a wildcard; -r recurses.

Usage

disc lock [OPTIONS] OUTER:INNER

Arguments

OUTER:INNER

Options

-r, --recursive: Recurse into directory matches.
--dry-run: Print what would change without modifying the image.

Examples

$ disc lock 'demo.adl:$.File'
$ disc ls demo.adl
                  demo.adl — Demo (adfs)                  
┏━━━━━━┳━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━┓
┃ Name ┃ Type ┃ Load       ┃ Exec       ┃ Length ┃ Attr  ┃
┡━━━━━━╇━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━┩
│ File │ file │ 0x0000FFFF │ 0x0000FFFF │ 8      │ LWR/R │
└──────┴──────┴────────────┴────────────┴────────┴───────┘
                   Free: 653,312 bytes                    

disc unlock¶

Unlock a file.

Accepts a COMPOUND_PATH. PATH may be a wildcard; -r recurses.

Usage

disc unlock [OPTIONS] OUTER:INNER

Arguments

OUTER:INNER

Options

-r, --recursive: Recurse into directory matches.
--dry-run: Print what would change without modifying the image.

Examples

$ disc unlock 'demo.adl:$.File'
$ disc ls demo.adl
                 demo.adl — Demo (adfs)                  
┏━━━━━━┳━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━┓
┃ Name ┃ Type ┃ Load       ┃ Exec       ┃ Length ┃ Attr ┃
┡━━━━━━╇━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━┩
│ File │ file │ 0x0000FFFF │ 0x0000FFFF │ 8      │ WR/R │
└──────┴──────┴────────────┴────────────┴────────┴──────┘
                   Free: 653,312 bytes                   

Metadata¶

disc title¶

Read or set a disc or directory title (Acorn alias: *TITLE).

Accepts a COMPOUND_PATH. With no in-image path it reads or sets the disc-level title (the DFS disc title, the ADFS root title, or the AFS partition’s disc name). With a directory path it reads or sets that directory’s title — an ADFS-only capability, since DFS and AFS directories have no title field. Targeting a DFS or AFS directory fails with a “no title” error.

Usage

disc title [OPTIONS] OUTER:INNER [NEW_TITLE]

Arguments

OUTER:INNER
NEW_TITLE (optional)

Options

--as [display|json|tsv]: Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

The standard report-output flags — --report, --no-reports, --all-reports, --header/--no-header, --detailed/--essential — are also accepted; see Output formats: --as.

Reports

title: Current title (when no new title is supplied).

Acorn aliases

*TITLE

Examples

$ disc title demo.ssd
Title: OldName

$ disc title demo.ssd NewName
$ disc title demo.ssd
Title: NewName

$ disc title 'games.adl:$.Elite' Frontier
$ disc title 'games.adl:$.Elite'
Title: Frontier

disc opt¶

Read or set boot option (Acorn alias: *OPT4).

Omit BOOT_OPTION to report the current setting.

Values:

/ OFF   No action
/ LOAD  *LOAD $.!BOOT
/ RUN   *RUN $.!BOOT
/ EXEC  *EXEC $.!BOOT

Usage

disc opt [OPTIONS] IMAGE [BOOT_OPTION]

Arguments

IMAGE
BOOT_OPTION (optional)

Options

--as [display|json|tsv]: Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

The standard report-output flags — --report, --no-reports, --all-reports, --header/--no-header, --detailed/--essential — are also accepted; see Output formats: --as.

Reports

boot_option: Current boot option (0/OFF, 1/LOAD, 2/RUN, 3/EXEC) when no value is supplied.

Acorn aliases

*OPT4

Examples

Reading the current value:

$ disc opt boot.ssd
Boot option: 0 (OFF)

Setting numerically:

$ disc opt boot.ssd 2
$ disc opt boot.ssd
Boot option: 2 (RUN)

Setting with a symbolic name:

$ disc opt boot.ssd EXEC
$ disc opt boot.ssd
Boot option: 3 (EXEC)

disc get-load¶

Print a file’s load address.

Accepts a COMPOUND_PATH.

Usage

disc get-load [OPTIONS] OUTER:INNER

Arguments

OUTER:INNER

Options

--as [display|json|tsv]: Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

The standard report-output flags — --report, --no-reports, --all-reports, --header/--no-header, --detailed/--essential — are also accepted; see Output formats: --as.

Reports

load: File load address: a ``0x``-prefixed 8-hex-digit string for humans, a raw integer for machine formatters.

Examples

$ disc get-load 'arcadians.ssd:$.ARC'
Load: 0x00001900

disc set-load¶

Set a file’s load address.

Accepts a COMPOUND_PATH and an ADDR.

ADDR’s number base comes from its prefix: 0x for hex (the usual form for Acorn addresses — e.g. 0x1900), 0o for octal, 0b for binary, or no prefix for decimal. A bare 1900 is therefore decimal, not hex; write 0x1900 for the hex value. The Acorn &1900 notation is not accepted.

PATH may contain Acorn wildcards; -r recurses into directory matches (directories themselves are skipped — they have no load address field).

Usage

disc set-load [OPTIONS] OUTER:INNER ADDR

Arguments

OUTER:INNER
ADDR

Options

-r, --recursive: Recurse into directory matches.
--dry-run: Print what would change without modifying the image.

Examples

$ disc set-load 'demo.ssd:$.FILE' 0x1900
$ disc get-load 'demo.ssd:$.FILE'
Load: 0x00001900

disc get-exec¶

Print a file’s exec address.

Accepts a COMPOUND_PATH.

Usage

disc get-exec [OPTIONS] OUTER:INNER

Arguments

OUTER:INNER

Options

--as [display|json|tsv]: Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

The standard report-output flags — --report, --no-reports, --all-reports, --header/--no-header, --detailed/--essential — are also accepted; see Output formats: --as.

Reports

exec: File exec address: a ``0x``-prefixed 8-hex-digit string for humans, a raw integer for machine formatters.

Examples

$ disc get-exec 'arcadians.ssd:$.ARC'
Exec: 0x00001900

disc set-exec¶

Set a file’s exec address.

Accepts a COMPOUND_PATH and an ADDR.

ADDR’s number base comes from its prefix: 0x for hex (the usual form for Acorn addresses — e.g. 0x8023), 0o for octal, 0b for binary, or no prefix for decimal. A bare 8023 is therefore decimal, not hex; write 0x8023 for the hex value. The Acorn &8023 notation is not accepted.

PATH may contain Acorn wildcards; -r recurses into directory matches (directories themselves are skipped — they have no exec address field).

Usage

disc set-exec [OPTIONS] OUTER:INNER ADDR

Arguments

OUTER:INNER
ADDR

Options

-r, --recursive: Recurse into directory matches.
--dry-run: Print what would change without modifying the image.

Examples

$ disc set-exec 'demo.ssd:$.FILE' 0x8023
$ disc get-exec 'demo.ssd:$.FILE'
Exec: 0x00008023

Whole-image operations¶

disc create¶

Create a new empty disc image.

The filesystem and geometry are inferred from HOST_PATH’s extension — .ssd → Acorn DFS 80T single-sided, .adl → ADFS-L, and so on — with --filesystem and --geometry to override. An ambiguous extension (.adf: ADFS-S or -M?) or an open-ended one (.dat: a hard disc) has no default geometry and requires --geometry.

Run disc list-filesystems to see the filesystems available, and disc describe-filesystem NAME for the geometries each accepts (its presets and parameterised forms).

Usage

disc create [OPTIONS] HOST_PATH

Arguments

HOST_PATH

Options

--filesystem TEXT: Filesystem to create. Inferred from the filename extension when omitted (.ssd/.dsd → acorn-dfs; .ads/.adm/.adl/.adf/.dat → adfs). Name a filesystem to override (e.g. watford-dfs); run `disc list-filesystems` to see them all.
--geometry TEXT: Physical geometry. Inferred from the extension when omitted; an ambiguous (.adf) or open-ended (.dat hard disc) extension needs it. A preset (e.g. l, 80t-ds) or parameterised form (capacity=10MB, cylinders=296,heads=4,spt=33). Run `disc describe-filesystem NAME` to list a filesystem’s geometries.
--title TEXT: Disc title.

Examples

$ disc create demo.ssd --title Demo
$ disc stat demo.ssd
         ACORN-DFS         
┏━━━━━━━━━━━━━┳━━━━━━━━━━━┓
┃ Title       ┃ Demo      ┃
┡━━━━━━━━━━━━━╇━━━━━━━━━━━┩
│ Size        │ 200.0 KiB │
│ Free        │ 199.5 KiB │
│ Boot option │ OFF (0)   │
│ Files       │ 0         │
└─────────────┴───────────┘

disc compact¶

Defragment a disc image, consolidating free space.

With --order, the named files are placed first (in the lowest sectors), which only filesystems with a defined on-disc order accept.

Usage

disc compact [OPTIONS] IMAGE

Arguments

IMAGE

Options

--order TEXT: Comma-separated paths to lay down first, in the lowest sectors (repeatable). Remaining files follow in their current order — so --order $.!BOOT,$.LOADER puts the boot files where they load fastest.

Examples

$ disc freemap demo.ads
Legend: █ = used, . = free

███████████████████████████...████████...............█████.................
...██...........██████..................████.........██████████████████████
███.......█████████████.████████████████...████████...............█████....
................██...........██████..................████.........█████████
████████████████.......█████████████.████████████████...████████...........
....█████....................██...........██████..................████.....
....█████████████████████████.......█████████████.████████████████...██████
██...............█████....................██...........██████..............
....████................................

Free: 351 of 640 sectors in 30 region(s) (largest 32 contiguous)
$ disc compact demo.ads
$ disc freemap demo.ads
Legend: █ = used, . = free

███████████████████████████████████████████████████████████████████████████
███████████████████████████████████████████████████████████████████████████
███████████████████████████████████████████████████████████████████████████
████████████████████████████████████████████████████████████████...........
...........................................................................
...........................................................................
...........................................................................
...........................................................................
........................................

Free: 351 of 640 sectors in 1 region(s) (largest 351 contiguous)

disc dfs expand¶

Expand a truncated disc image to its canonical format size.

Truncated images (e.g. produced by BeebAsm) omit trailing empty sectors. This command appends zero bytes to bring the file up to the full format size.

Usage

disc dfs expand [OPTIONS] IMAGE

Arguments

IMAGE

Options

--format [ssd|dsd]: Target disc format. Inferred from file extension if omitted.

Examples

$ wc -c < demo.ssd
1024
$ disc dfs expand demo.ssd
$ wc -c < demo.ssd
204800

AFS (Acorn Level 3 File Server)¶

disc afs plan¶

Show what afs init would do, without modifying the image.

By default, plans using the existing tail free extent (matching WFSINIT behaviour). With –compact, plans a compaction-first layout that reclaims the maximum space. With –cylinders N, shows the plan for that specific size. Reports disc geometry, current ADFS occupancy, whether compaction is needed, and the resulting partition layout.

Use --as json to emit a machine-readable document instead of the human-readable display report.

Usage

disc afs plan [OPTIONS] IMAGE

Arguments

IMAGE

Options

--cylinders INT: Proposed AFS region size in cylinders.
--compact: Plan with ADFS compaction to maximise AFS space.
--as [display|json|tsv]: Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

The standard report-output flags — --report, --no-reports, --all-reports, --header/--no-header, --detailed/--essential — are also accepted; see Output formats: --as.

Reports

geometry: Disc geometry.
adfs_state: ADFS occupancy.
existing_afs: Existing AFS partition (only when one is already installed).
plan: Proposed new AFS partition (only when computable).

Examples

$ disc afs plan scsi0.dat
                   Disc geometry                    
┏━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Shape ┃ 296 cylinders, 4 heads, 33 sectors/track ┃
┡━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Total │ 39072 sectors (10,002,432 bytes)         │
└───────┴──────────────────────────────────────────┘


       ADFS occupancy        
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ Used sectors ┃ 7          ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ Free sectors │ 39065      │
│ Free bytes   │ 10,000,640 │
└──────────────┴────────────┘


                             Proposed AFS partition                             
┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ AFS region        ┃ 295 cylinders (38940 sectors, 9,968,640 bytes)           ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Start cylinder    │ 1                                                        │
│ ADFS retained     │ 1 cylinders                                              │
│ Compaction        │ not required                                             │
│ Suggested command │ disc afs init scsi0.dat --disc-name NAME --cylinders 295 │
└───────────────────┴──────────────────────────────────────────────────────────┘

disc afs init¶

Initialise an AFS partition on an ADFS hard disc image.

Usage

disc afs init [OPTIONS] IMAGE

Arguments

IMAGE

Options

--disc-name TEXT: AFS disc name.
--cylinders INT: AFS region size in cylinders (default: use existing free space).
--compact: Compact the ADFS partition first to maximise AFS space.
--user TEXT: User spec as NAME, NAME:S (system), NAME:QUOTA, or NAME:S:QUOTA. Quota accepts e.g. 2MiB. Repeat for multiple. A NAME matching a built-in (Syst, Boot, Welcome) overrides that built-in’s quota; Syst requires :S. Set passwords with --user-password, not here.
--user-password TEXT: Set a user’s password as NAME=VALUE, split once on the first ‘=’ so the password may itself contain ‘:’ or ‘=’. NAME must match a --user or a built-in (Syst, Boot, Welcome). Repeat for multiple. Passwords are stored as cleartext (max 6 ASCII chars).
--default-quota TEXT: Default quota for users without an explicit quota (e.g. 256KiB).
--omit-user TEXT: Suppress a built-in account (Syst, Boot, or Welcome). Repeat for multiple.
--emplace TEXT: Emplace a library: a shipped name (Library, Library1, ArthurLib, Utils), the literal ‘all’ to emplace every shipped library, or a path to an ADFS .adl image. Repeat for multiple.

Examples

Passwords are set with --user-password NAME=VALUE, not inside the --user spec: a password may contain a colon, which the colon-delimited spec cannot represent, so the value is split once on the first = and the rest taken verbatim. NAME matches a --user or a built-in (Syst, Boot, Welcome). No account has a password unless you give one — to ship a disc with the system account already protected, initialise with --user-password Syst=secret.

$ disc afs init scsi0.dat --disc-name Server
$ disc stat scsi0.dat
                          Disc                           
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Geometry ┃ 296 cylinders × 4 heads × 33 sectors/track ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Size     │ 9.5 MiB                                    │
└──────────┴────────────────────────────────────────────┘


       Partition 1: ADFS       
┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
┃ Title       ┃ Server        ┃
┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
│ Range       │ cylinders 0-0 │
│ Size        │ 33.0 KiB      │
│ Free        │ 31.2 KiB      │
│ Boot option │ OFF (0)       │
└─────────────┴───────────────┘


     Partition 2: AFS      
┏━━━━━━━┳━━━━━━━━━━━━━━━━━┓
┃ Title ┃ Server          ┃
┡━━━━━━━╇━━━━━━━━━━━━━━━━━┩
│ Range │ cylinders 1-295 │
│ Size  │ 9.5 MiB         │
│ Free  │ 9.4 MiB         │
└───────┴─────────────────┘

disc afs users¶

List AFS users with quota and flags.

Usage

disc afs users [OPTIONS] IMAGE

Arguments

IMAGE

Options

--as [display|json|tsv]: Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

The standard report-output flags — --report, --no-reports, --all-reports, --header/--no-header, --detailed/--essential — are also accepted; see Output formats: --as.

Reports

users: Users with system flag and quota.

Examples

$ disc afs users scsi0.dat
             users              
┏━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━┓
┃ User    ┃ System ┃ Quota     ┃
┡━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━┩
│ Syst    │ yes    │ 257.0 KiB │
│ Boot    │        │ 257.0 KiB │
│ Welcome │        │ 257.0 KiB │
└─────────┴────────┴───────────┘

disc afs useradd¶

Add a user to the AFS passwords file.

Usage

disc afs useradd [OPTIONS] IMAGE NAME

Arguments

IMAGE
NAME

Options

--system: System user flag.
--quota INT: Quota in bytes.
--password TEXT: Initial password.

Examples

$ disc afs useradd scsi0.dat ALICE --quota 1048576
$ disc afs users scsi0.dat
             users              
┏━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━┓
┃ User    ┃ System ┃ Quota     ┃
┡━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━┩
│ Syst    │ yes    │ 257.0 KiB │
│ Boot    │        │ 257.0 KiB │
│ Welcome │        │ 257.0 KiB │
│ ALICE   │        │ 1.0 MiB   │
└─────────┴────────┴───────────┘

disc afs userdel¶

Remove a user from the AFS passwords file.

Usage

disc afs userdel IMAGE NAME

Arguments

IMAGE
NAME

Examples

$ disc afs userdel scsi0.dat ALICE
$ disc afs users scsi0.dat
             users              
┏━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━┓
┃ User    ┃ System ┃ Quota     ┃
┡━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━┩
│ Syst    │ yes    │ 257.0 KiB │
│ Boot    │        │ 257.0 KiB │
│ Welcome │        │ 257.0 KiB │
└─────────┴────────┴───────────┘

disc afs passwd¶

Change an existing AFS user’s login password.

The Level 3 File Server stores passwords as up to six cleartext ASCII characters; there is no encryption. Unlike afs useradd this only rewrites an existing record in place, so it never grows the passwords file.

Usage

disc afs passwd [OPTIONS] IMAGE NAME

Arguments

IMAGE
NAME

Options

--password TEXT: New password (max 6 ASCII chars).

Examples

$ disc afs passwd scsi0.dat ALICE --password sw0rd

disc afs merge¶

Bulk-copy the AFS file tree from one image into another.

Walks the source AFS partition recursively and recreates every directory and file under the target’s AFS partition, preserving each entry’s access byte, load address, exec address, and date. The source image is opened read-only; only the target is mutated.

Typical uses:

- layering a shipped library image (Library, ArthurLib,

Library1) onto a server disc after the fact, when

afs init --emplace was not used at creation time;

- consolidating two Level 3 File Server discs onto one image,

either at the AFS root or — with --target-path — under a

chosen subdirectory of the target’s namespace.

The Passwords file is always excluded so the target’s own user records survive intact.

The --on-conflict policy chooses what happens when a source entry’s name already exists on the target:

- error (default): abort the whole merge before writing

anything, so no partial state lands on disc;

- skip: keep the target’s existing entry, drop the source’s;

- overwrite: replace the target’s entry with the source’s

(the old bytes are released back to the allocator).

Usage

disc afs merge [OPTIONS] IMAGE

Arguments

IMAGE

Options

--source PATH: Source AFS image to merge from.
--target-path TEXT: Target AFS path for merge root.
--on-conflict [error|skip|overwrite]: Policy when a source entry’s name already exists on the target.

Examples

The recipe initialises a small source disc with an emplaced Library, then merges its AFS tree into a separate empty target. The source’s Library lands under the target’s $ root; the target’s own freshly-created Passwords file is left in place (it would have been excluded even if the source had carried one).

$ disc afs merge target.dat --source source.dat
$ disc tree target.dat
target.dat
├── adfs
└── afs
    ├── Library
    │   ├── CLOSE
    │   ├── CopyFiles
    │   ├── Date
    │   ├── Discs
    │   ├── FindLib
    │   ├── FLIP
    │   ├── Free
    │   ├── FS
    │   ├── LCAT
    │   ├── LEX
    │   ├── NETMON
    │   ├── NOTIFY
    │   ├── PROT
    │   ├── PS
    │   ├── RDFREE
    │   ├── REMOTE
    │   ├── SETFREE
    │   ├── SetStation
    │   ├── TIME
    │   ├── TreeCopy
    │   ├── UNPROT
    │   ├── USERS
    │   └── VIEW
    └── Passwords

ROMFS (Acorn ROM Filing System)¶

These query and tweak the paged-ROM header properties of an existing ROMFS image; the image itself is made with disc create.

disc romfs get-copyright¶

Print the paged-ROM copyright string of IMAGE.

Usage

disc romfs get-copyright IMAGE

Arguments

IMAGE

Examples

$ disc romfs get-copyright demo.rom
(C) oaknut

disc romfs set-copyright¶

Set the paged-ROM copyright string of IMAGE (must begin “(C)”).

A same-length string is written in place. A different length moves the service handler, so the ROM is rebuilt — done only for a created-style ROM (no language entry, nothing after the filing system); other ROMs are refused to avoid disturbing their code.

Usage

disc romfs set-copyright IMAGE COPYRIGHT

Arguments

IMAGE
COPYRIGHT

Examples

A same-length copyright is written in place. A different length moves the service handler, so the ROM is rebuilt — done only for a created-style ROM (no language entry, nothing after the filing system); other ROMs are refused to protect their code.

$ disc romfs set-copyright demo.rom '(C) 1984 Acornsoft'
$ disc romfs get-copyright demo.rom
(C) 1984 Acornsoft

disc romfs get-version¶

Print the paged-ROM binary version byte of IMAGE.

Usage

disc romfs get-version IMAGE

Arguments

IMAGE

Examples

$ disc romfs get-version demo.rom
1

disc romfs set-version¶

Set the paged-ROM binary version byte of IMAGE (0-255).

VERSION honours a base prefix, like the address commands: 0x hex (e.g. 0x80), 0o octal, 0b binary, or a plain decimal value.

Usage

disc romfs set-version IMAGE VERSION

Arguments

IMAGE
VERSION

Examples

$ disc romfs set-version demo.rom 2
$ disc romfs get-version demo.rom
2

Diagnostics¶

disc adfs generate-dsc¶

Write a .dsc geometry sidecar for an ADFS hard-disc .dat.

The total disc size is read from the ADFS Old Map at the head of the image. Cylinders are derived as total_sectors / (heads × spt) and the resulting geometry is written to a 22-byte .dsc next to the image so that subsequent disc commands (ls, cat, …) can open the image via ADFS.from_file.

Defaults to the RetroClinic Data Centre IDE geometry (--heads 4 --sectors-per-track 64); override for SCSI or other interfaces.

Usage

disc adfs generate-dsc [OPTIONS] IMAGE

Arguments

IMAGE

Options

--heads int [1..16]: Number of heads in the synthesised geometry.
--sectors-per-track int [1..255]: Sectors per track in the synthesised geometry.
--force: Overwrite an existing .dsc next to the image.

Examples

$ disc adfs generate-dsc scsi0.dat --heads 4 --sectors-per-track 33
Wrote scsi0.dsc (cylinders=296, heads=4, sectors_per_track=33, total=39072 sectors / 10,002,432 bytes)
$ ls scsi0.*
scsi0.dat
scsi0.dsc

Filesystem identification¶

These introspect the filesystems disc identify can recognise — one registered detector per filesystem. The set grows as filesystem packages are installed.

disc list-filesystems¶

List the filesystems this build can recognise.

Usage

disc list-filesystems [OPTIONS]

Options

--as [display|json|tsv]: Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

The standard report-output flags — --report, --no-reports, --all-reports, --header/--no-header, --detailed/--essential — are also accepted; see Output formats: --as.

Reports

filesystems: Filesystems this build can recognise.

Examples

$ disc list-filesystems
                             Recognised filesystems                             
┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name        ┃ Description                                                    ┃
┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ acorn-dfs   │ Acorn DFS — the standard flat-catalogue BBC floppy format.     │
│ acorn-romfs │ Acorn ROM Filing System — the cassette filing system on a      │
│             │ paged ROM.                                                     │
│ adfs        │ ADFS — Acorn's hierarchical filing system (floppies and hard   │
│             │ discs).                                                        │
│ afs         │ AFS — the Acorn Level 3 File Server's private on-disc format.  │
│ watford-dfs │ Watford DFS — the 62-file extended-catalogue BBC floppy        │
│             │ format.                                                        │
│ zip         │ ZIP — archives that may carry Acorn files (SparkFS extras,     │
│             │ RISC OS types).                                                │
└─────────────┴────────────────────────────────────────────────────────────────┘

disc describe-filesystem¶

Describe one recognised filesystem in detail.

Includes the geometries it accepts for disc create --geometry — the named presets and any parameterised (capacity / CHS / floppy) forms.

Usage

disc describe-filesystem [OPTIONS] NAME

Arguments

NAME

Options

--as [display|json|tsv]: Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

The standard report-output flags — --report, --no-reports, --all-reports, --header/--no-header, --detailed/--essential — are also accepted; see Output formats: --as.

Reports

filesystem: The full description of one recognised filesystem.
geometries: The geometries it accepts for `disc create --geometry`.

Examples

$ disc describe-filesystem adfs
adfs: ADFS — Acorn's hierarchical filing system (floppies and hard discs).

Detects the old-map layout by its root-directory signature ('Hugo'
at 0x201, 'Nick' at 0x401), corroborated by the free-space-map
checksums. A reserved tail region — where an AFS (Level 3 File
Server) or DRDOS FAT filesystem may live — is reported for the
coordinator to recurse into; ADFS itself stays ignorant of it.

Wildcards: * (any sequence of characters), # (exactly one character)


                            Geometries (--geometry)                             
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ --geometry                                    ┃ Result                       ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ s                                             │ 160.0 KiB                    │
│ m                                             │ 320.0 KiB                    │
│ l                                             │ 640.0 KiB                    │
│ capacity=SIZE                                 │ hard disc of the given size  │
│ cylinders=N,heads=N,spt=N                     │ hard disc, explicit geometry │
│ tracks=N,sides=N[,interleave=interleaved|seq… │ custom floppy                │
└───────────────────────────────────────────────┴──────────────────────────────┘

Meta-commands¶

These describe the CLI itself rather than acting on a disc image: they introspect the reports each command produces and the output formatters available to --as. See Output formats: --as for the concepts behind them.

disc list-reports¶

List the named reports produced by a command and selectable with --report.

If no command is specified, the named reports of all commands are listed.

Usage

disc list-reports [OPTIONS] [COMMAND]

Arguments

COMMAND (optional)

Options

--as [display|json|tsv]: Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

The standard report-output flags — --report, --no-reports, --all-reports, --header/--no-header, --detailed/--essential — are also accepted; see Output formats: --as.

Reports

reports: Hierarchical listing of CLI commands and their declared reports.

Examples

$ disc list-reports
                                    Reports                                     
┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name                   ┃ Description                                         ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ list-report-formats    │ List the available report output formatters.        │
│ └── formatters         │ Registered report-output formatters with one-line   │
│                        │ descriptions.                                       │
│ describe-report-format │ Describe a specific report output formatter.        │
│ └── formatter          │ The full description of one registered formatter.   │
│ identify               │ Identify a disc image's filesystem(s) by...         │
│ └── candidates         │ Ranked filesystem-identification candidates with    │
│                        │ evidence.                                           │
│ list-filesystems       │ List the filesystems this build can...              │
│ └── filesystems        │ Filesystems this build can recognise.               │
│ describe-filesystem    │ Describe one recognised filesystem in detail.       │
│ ├── filesystem         │ The full description of one recognised filesystem.  │
│ └── geometries         │ The geometries it accepts for `disc create          │
│                        │ --geometry`.                                        │
│ ls                     │ List directory contents (Acorn alias: *CAT).        │
│ └── entries            │ Directory entries with load/exec/length/attributes. │
│ tree                   │ Display recursive directory tree.                   │
│ └── tree               │ Hierarchical directory listing.                     │
│ stat                   │ Disc summary (no path) or file metadata...          │
│ ├── disc               │ Physical envelope (geometry + total size). Emitted  │
│ │                      │ only on a multi-partition disc (ADFS + AFS), where  │
│ │                      │ it carries information distinct from each           │
│ │                      │ partition. Single-partition images fold this        │
│ │                      │ content into ``partition_1``.                       │
│ ├── file               │ Per-file metadata when the path denotes a file.     │
│ ├── partition_1        │ First partition's summary. Stands alone (carrying   │
│ │                      │ the disc geometry) on a single-partition image; on  │
│ │                      │ a partitioned disc it is the host slice and         │
│ │                      │ ``disc`` carries the geometry.                      │
│ ├── partition_2        │ Second partition (AFS on a partitioned disc; also   │
│ │                      │ the report name when an ``afs:`` prefix scopes the  │
│ │                      │ view to that half).                                 │
│ ├── volume_1           │ First volume of a multi-volume single partition —   │
│ │                      │ side ``:0`` of a double-sided DFS disc.             │
│ └── volume_2           │ Second volume — side ``:2`` of a double-sided DFS   │
│                        │ disc.                                               │
│ find                   │ Find files matching an Acorn wildcard...            │
│ └── matches            │ Paths matching the wildcard pattern.                │
│ for-each               │ Run a command for each file matching an...          │
│ └── results            │ Per-file capture: path and the command's stdout,    │
│                        │ one row per match.                                  │
│ storage-order          │ List a partition's files in physical...             │
│ └── paths              │ File paths in physical (storage) order.             │
│ get-load               │ Print a file's load address.                        │
│ └── load               │ File load address: a ``0x``-prefixed 8-hex-digit    │
│                        │ string for humans, a raw integer for machine        │
│                        │ formatters.                                         │
│ get-exec               │ Print a file's exec address.                        │
│ └── exec               │ File exec address: a ``0x``-prefixed 8-hex-digit    │
│                        │ string for humans, a raw integer for machine        │
│                        │ formatters.                                         │
│ title                  │ Read or set a disc or directory title...            │
│ └── title              │ Current title (when no new title is supplied).      │
│ opt                    │ Read or set boot option (Acorn alias: *OPT4).       │
│ └── boot_option        │ Current boot option (0/OFF, 1/LOAD, 2/RUN, 3/EXEC)  │
│                        │ when no value is supplied.                          │
│ afs plan               │ Show what ``afs init`` would do, without...         │
│ ├── adfs_state         │ ADFS occupancy.                                     │
│ ├── existing_afs       │ Existing AFS partition (only when one is already    │
│ │                      │ installed).                                         │
│ ├── geometry           │ Disc geometry.                                      │
│ └── plan               │ Proposed new AFS partition (only when computable).  │
│ afs users              │ List AFS users with quota and flags.                │
│ └── users              │ Users with system flag and quota.                   │
└────────────────────────┴─────────────────────────────────────────────────────┘
                     Commands and the reports they produce.                     

disc describe-report¶

Describe a specific declared report.

Usage

disc describe-report [OPTIONS] COMMAND REPORT

Arguments

COMMAND
REPORT

Options

--as [display|json|tsv]: Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

The standard report-output flags — --report, --no-reports, --all-reports, --header/--no-header, --detailed/--essential — are also accepted; see Output formats: --as.

Reports

description: The declared description of one report.

Examples

$ disc describe-report ls entries
ls.entries: Directory entries with load/exec/length/attributes.

disc list-report-formats¶

List the available report output formatters.

Usage

disc list-report-formats [OPTIONS]

Options

--as [display|json|tsv]: Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

The standard report-output flags — --report, --no-reports, --all-reports, --header/--no-header, --detailed/--essential — are also accepted; see Output formats: --as.

Reports

formatters: Registered report-output formatters with one-line descriptions.

Examples

$ disc list-report-formats
                     Formatters for use with --as                      
┏━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name    ┃ Description                                               ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ display │ Human-oriented presentation formatter.                    │
│ json    │ JSON formatter for structured data output.                │
│ tsv     │ Tab-separated values formatter for UNIX-style processing. │
└─────────┴───────────────────────────────────────────────────────────┘

disc describe-report-format¶

Describe a specific report output formatter.

Usage

disc describe-report-format [OPTIONS] NAME

Arguments

NAME

Options

--as [display|json|tsv]: Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

The standard report-output flags — --report, --no-reports, --all-reports, --header/--no-header, --detailed/--essential — are also accepted; see Output formats: --as.

Reports

formatter: The full description of one registered formatter.

Examples

$ disc describe-report-format json
json: JSON formatter for structured data output.

Outputs data as a JSON object with a top-level ``"reports"`` key
containing named reports. Each report carries its own ``"metadata"``
(including a ``"kind"`` discriminator of ``"table"``, ``"tree"``,
or ``"scalar"``) and a shape-specific payload:

- table: ``"columns"`` schema + ``"rows"``
- tree:  ``"columns"`` schema + ``"roots"`` (nested nodes)
- scalar: just ``"value"``

Consumers differentiate the shapes via ``metadata.kind`` or
structurally by which of ``rows`` / ``roots`` / ``value`` is
present.

JSON always emits full metadata regardless of the ``header`` flag,
since the format is self-describing by nature.