CLI Reference¶
Full command-line reference generated from the Click command definitions.
disc¶
Work with Acorn DFS, ADFS, and AFS disc images.
Usage
disc [OPTIONS] COMMAND [ARGS]...
Options
- --version¶
Show the version and exit.
afs-init¶
Initialise an AFS partition on an ADFS hard disc image.
Usage
disc afs-init [OPTIONS] IMAGE
Options
- --disc-name <disc_name>¶
Required AFS disc name.
- --cylinders <cylinders>¶
AFS region size in cylinders (default: use existing free space).
- --compact¶
Compact the ADFS partition first to maximise AFS space.
- --user <users>¶
User spec as NAME, NAME:S (system), NAME:QUOTA, or NAME:S:QUOTA. Quota accepts e.g. 2MiB. Repeat for multiple.
- --default-quota <default_quota>¶
Default quota for users without an explicit quota (e.g. 256KiB).
- --omit-user <omit_users>¶
Suppress a built-in account (Syst, Boot, or Welcome). Repeat for multiple.
- --emplace <emplacements>¶
Emplace a library: a shipped name (Library, Library1, ArthurLib) or a path to an ADFS .adl image. Repeat for multiple.
Arguments
- IMAGE¶
Required argument
afs-merge¶
Merge a source AFS tree into the target image.
Usage
disc afs-merge [OPTIONS] IMAGE
Options
- --source <source>¶
Required Source AFS image to merge from.
- --target-path <target_path>¶
Target AFS path for merge root.
Arguments
- IMAGE¶
Required argument
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 text report.
Usage
disc afs-plan [OPTIONS] IMAGE
Options
- --cylinders <cylinders>¶
Proposed AFS region size in cylinders.
- --compact¶
Plan with ADFS compaction to maximise AFS space.
- --as <output_format>¶
Output format (default: text).
- Options:
text | json
Arguments
- IMAGE¶
Required argument
afs-useradd¶
Add a user to the AFS passwords file.
Usage
disc afs-useradd [OPTIONS] IMAGE NAME
Options
- --system¶
System user flag.
- --quota <quota>¶
Quota in bytes.
- --password <password>¶
Initial password.
Arguments
- IMAGE¶
Required argument
- NAME¶
Required argument
afs-userdel¶
Remove a user from the AFS passwords file.
Usage
disc afs-userdel [OPTIONS] IMAGE NAME
Arguments
- IMAGE¶
Required argument
- NAME¶
Required argument
afs-users¶
List AFS users with quota and flags.
Usage
disc afs-users [OPTIONS] IMAGE
Arguments
- IMAGE¶
Required argument
cat¶
Dump file contents to stdout (Acorn alias: *TYPE).
Usage
disc cat [OPTIONS] IMAGE PATH
Arguments
- IMAGE¶
Required argument
- PATH¶
Required argument
chmod¶
Set file access permissions (Acorn alias: *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.
Usage
disc chmod [OPTIONS] IMAGE PATH ACCESS
Arguments
- IMAGE¶
Required argument
- PATH¶
Required argument
- ACCESS¶
Required argument
compact¶
Defragment a disc image, consolidating free space.
Usage
disc compact [OPTIONS] IMAGE
Arguments
- IMAGE¶
Required argument
cp¶
Copy a file within or between disc images (Acorn alias: *COPY).
Copies across DFS, ADFS, and AFS in any combination. Load and exec addresses are preserved; access attributes are mapped best-effort (DFS only has the locked bit).
Usage
disc cp [OPTIONS] ARGS...
Options
- -f, --force¶
Overwrite existing destination.
Arguments
- ARGS¶
Required argument(s)
create¶
Create a new empty disc image.
Usage
disc create [OPTIONS] HOST_PATH
Options
- --format <fmt>¶
Required Disc image format.
- Options:
ssd | dsd | adfs-s | adfs-m | adfs-l | adfs-hard
- --title <disc_title>¶
Disc title.
- --capacity <capacity>¶
Capacity (hard disc). Accepts e.g. 10MB, 40MiB, 1024kB, or plain bytes.
Arguments
- HOST_PATH¶
Required argument
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 expand [OPTIONS] IMAGE
Options
- --format <fmt>¶
Target disc format. Inferred from file extension if omitted.
- Options:
ssd | dsd
Arguments
- IMAGE¶
Required argument
export¶
Bulk-export entire image to a host directory.
Usage
disc export [OPTIONS] IMAGE HOST_DIR
Options
- --meta-format <meta_format>¶
Metadata sidecar format.
- Options:
inf-trad | inf-pieb | xattr-acorn | xattr-pieb | filename-riscos | filename-mos | none
- --owner <owner>¶
Econet owner ID for PiEB formats.
- -v, --verbose¶
Show extraction progress.
Arguments
- IMAGE¶
Required argument
- HOST_DIR¶
Required argument
find¶
Find files matching an Acorn wildcard pattern.
Usage
disc find [OPTIONS] IMAGE PATTERN
Arguments
- IMAGE¶
Required argument
- PATTERN¶
Required argument
freemap¶
Show free-space map with ASCII fragmentation bar.
Usage
disc freemap [OPTIONS] IMAGE [PATH]
Arguments
- IMAGE¶
Required argument
- PATH¶
Optional argument
get¶
Export a file from the image.
Usage
disc get [OPTIONS] IMAGE PATH [HOST_PATH]
Options
- --meta-format <meta_format>¶
Metadata sidecar format.
- Options:
inf-trad | inf-pieb | xattr-acorn | xattr-pieb | filename-riscos | filename-mos | none
- --owner <owner>¶
Econet owner ID for PiEB formats.
Arguments
- IMAGE¶
Required argument
- PATH¶
Required argument
- HOST_PATH¶
Optional argument
get-exec¶
Print a file’s exec address.
Usage
disc get-exec [OPTIONS] IMAGE PATH
Arguments
- IMAGE¶
Required argument
- PATH¶
Required argument
get-load¶
Print a file’s load address.
Usage
disc get-load [OPTIONS] IMAGE PATH
Arguments
- IMAGE¶
Required argument
- PATH¶
Required argument
import¶
Bulk-import a host directory into the image.
Usage
disc import [OPTIONS] IMAGE HOST_DIR
Options
- --meta-format <meta_format>¶
Metadata format to read from host files.
- Options:
inf-trad | inf-pieb | xattr-acorn | xattr-pieb | filename-riscos | filename-mos | none
- -v, --verbose¶
Show import progress.
Arguments
- IMAGE¶
Required argument
- HOST_DIR¶
Required argument
lock¶
Lock a file.
Usage
disc lock [OPTIONS] IMAGE PATH
Arguments
- IMAGE¶
Required argument
- PATH¶
Required argument
ls¶
List directory contents (Acorn alias: *CAT).
Usage
disc ls [OPTIONS] IMAGE [PATH]
Arguments
- IMAGE¶
Required argument
- PATH¶
Optional argument
mkdir¶
Create a directory (ADFS/AFS only). Alias: *CDIR.
Usage
disc mkdir [OPTIONS] IMAGE PATH
Options
- -p¶
No error if directory already exists.
Arguments
- IMAGE¶
Required argument
- PATH¶
Required argument
mv¶
Rename or move a file within the image (Acorn alias: *RENAME).
Usage
disc mv [OPTIONS] IMAGE SRC DST
Options
- -f, --force¶
Overwrite existing destination.
Arguments
- IMAGE¶
Required argument
- SRC¶
Required argument
- DST¶
Required argument
opt¶
Read or set boot option (Acorn alias: *OPT4).
Omit BOOT_OPTION to report the current setting.
Usage
disc opt [OPTIONS] IMAGE [BOOT_OPTION]
Arguments
- IMAGE¶
Required argument
- BOOT_OPTION¶
Optional argument
put¶
Import a file into the image.
Usage
disc put [OPTIONS] IMAGE PATH [HOST_PATH]
Options
- --load <load_addr>¶
Load address (hex).
- --exec <exec_addr>¶
Exec address (hex).
- --meta-format <meta_format>¶
Metadata format to read from host file.
- Options:
inf-trad | inf-pieb | xattr-acorn | xattr-pieb | filename-riscos | filename-mos | none
Arguments
- IMAGE¶
Required argument
- PATH¶
Required argument
- HOST_PATH¶
Optional argument
rm¶
Delete file(s) from the image (Acorn alias: *DELETE).
Usage
disc rm [OPTIONS] IMAGE PATHS...
Options
- -f, --force¶
Ignore missing, override locks.
- -r, --recursive¶
Remove directories recursively.
- --dry-run¶
Print what would be removed.
Arguments
- IMAGE¶
Required argument
- PATHS¶
Required argument(s)
set-exec¶
Set a file’s exec address.
Usage
disc set-exec [OPTIONS] IMAGE PATH ADDR
Arguments
- IMAGE¶
Required argument
- PATH¶
Required argument
- ADDR¶
Required argument
set-load¶
Set a file’s load address.
Usage
disc set-load [OPTIONS] IMAGE PATH ADDR
Arguments
- IMAGE¶
Required argument
- PATH¶
Required argument
- ADDR¶
Required argument
stat¶
Disc summary (no path) or file metadata (with path). Alias: *INFO.
Usage
disc stat [OPTIONS] IMAGE [PATH]
Arguments
- IMAGE¶
Required argument
- PATH¶
Optional argument
title¶
Read or set disc title (Acorn alias: *TITLE).
Usage
disc title [OPTIONS] IMAGE [NEW_TITLE]
Arguments
- IMAGE¶
Required argument
- NEW_TITLE¶
Optional argument
tree¶
Display recursive directory tree.
Usage
disc tree [OPTIONS] IMAGE [PATH]
Arguments
- IMAGE¶
Required argument
- PATH¶
Optional argument
unlock¶
Unlock a file.
Usage
disc unlock [OPTIONS] IMAGE PATH
Arguments
- IMAGE¶
Required argument
- PATH¶
Required argument
validate¶
Validate disc image structure.
Usage
disc validate [OPTIONS] IMAGE
Arguments
- IMAGE¶
Required argument