@bixu/zfs

v2026.04.23.1

ZFS pool management for swamp — import/export pools, sync health status, snapshot datasets, prune retention, scrub, and TRIM

Repository

https://github.com/bixu/swamp-extensions

Platforms

darwin-aarch64 darwin-x86_64 linux-x86_64 linux-aarch64

Labels

zfsstoragemacoslinux

models

Quality score

How well-documented and verifiable this extension is.

Grade A

Has README or module doc2/2earned
README has a code example1/1earned
README is substantive1/1earned
Most symbols documented1/1earned
No slow types1/1earned
Has description1/1earned
At least one platform tag (or universal)1/1earned
Two or more platform tags (or universal)1/1earned
License declared1/1earned
Verified public repository2/2earned

Install

$ swamp extension pull @bixu/zfs

@bixu/zfsv2026.04.23.1zfs.ts

Global Arguments

Argument	Type	Required	Description
pool?	string	no	ZFS pool name (e.g. tank). Required for sync, snapshot, scrub, and trim. Leave unset to import all discovered pools on attach.
zpoolBin	string	yes	Path to zpool binary
zfsBin	string	yes	Path to zfs binary

importImport ZFS pools from attached devices. Uses 'zpool import -a' when no pool is configured — designed for IOKit launchd triggers on device attach. If a pool requires forced import, a native macOS dialog is shown and the user must confirm before proceeding.

Argument	Type	Required	Description
deviceDir?	string	no	Search for devices in this directory instead of the default (e.g. /dev)

exportExport the ZFS pool — unmounts all datasets and prepares drives for safe removal. Requires globalArguments.pool to be set.

Argument	Type	Required	Description
force	boolean	yes	Force export even if pool is busy (will terminate active I/O)

syncFetch pool status, dataset list, and snapshot list — safe for periodic launchd runs

snapshotCreate a ZFS snapshot

Argument	Type	Required	Description
dataset?	string	no	Dataset to snapshot (e.g. tank/data). Omit to snapshot the pool root.
name	string	yes	Snapshot name (e.g. manual-2026-04-05). Will be suffixed to dataset@
recursive	boolean	yes	Recursively snapshot all descendant datasets

autoSnapshotCreate timestamped snapshots of all datasets in the pool — designed for scheduled launchd runs

Argument	Type	Required	Description
prefix	string	yes	Snapshot name prefix (e.g. daily, hourly, weekly). Timestamp appended automatically.
datasets?	array	no	Specific datasets to snapshot (default: all filesystems in pool)
recursive	boolean	yes	Recursively snapshot each dataset's descendants

destroySnapshotDestroy a specific ZFS snapshot

Argument	Type	Required	Description
snapshot	string	yes	Full snapshot name including dataset (e.g. tank/data@daily-2026-04-01-09-00)

pruneSnapshotsDestroy snapshots matching a prefix that are older than keepDays — designed for scheduled launchd retention runs

Argument	Type	Required	Description
dataset?	string	no	Dataset to prune (e.g. tank/data). Omit for pool root.
prefix	string	yes	Only prune snapshots whose name starts with this prefix (e.g. daily)
keepDays	number	yes	Retain snapshots newer than this many days; destroy older ones
keepCount	number	yes	Always keep at least this many matching snapshots regardless of age
dryRun	boolean	yes	List snapshots that would be destroyed without actually destroying them

scrubStart a ZFS pool scrub to verify data integrity

trimStart a ZFS pool TRIM to reclaim freed space on SSDs

Resources

status(infinite)— ZFS pool status, health, capacity, and device states

datasets(infinite)— ZFS datasets (filesystems and volumes) in the pool

snapshots(infinite)— ZFS snapshots in the pool

snapshotResult(7d)— Result of a snapshot create, destroy, or prune operation

scrubResult(7d)— Result of a scrub or trim operation

importResult(7d)— Result of a pool import or export operation