Status: implemented 1.0.0 command surface. Every command the parser declares is implemented: devices, the --json dashboard, alerts check, scan, explore, snapshots list|diff, clean, clean plan, clean apply, history, undo, find duplicates|stale|empty|broken, timer install|uninstall, report, and completion bash|zsh|fish. The JSON output contract in schemas/cli/v1/ is normative and is validated by tests/contract/cli-schema.test.mjs against examples and by tests/integration/cli-output.test.mjs against what the CLI actually writes on a running host. The parser, the generated help, and the generated completions are normative. See PLAN.md.
| Command | Behaviour |
|---|---|
disktop |
Opens the terminal UI when stdin and stdout are both terminals and TERM can address the cursor, and prints the text dashboard otherwise (a pipe, TERM=dumb, or no TERM). |
disktop --json |
One dashboard.json envelope: capability, filesystems, and alerts. |
disktop devices [--json] |
All connected persistent disks (including separate SSDs, USB storage, memory cards and optical drives), their partitions and logical volumes (volumes), and every readable mounted filesystem. Firmware, recovery, reserved, swap and partitions with unknown filesystem signatures remain visible. RAID/LVM volumes name every backing disk. Usage is unknown without a readable mount; nothing is mounted or unlocked automatically. The legacy unmounted array remains the data-only subset. |
disktop alerts check [--threshold PERCENT] [--notify] [--json] |
Space and inode thresholds. Exits 1 when one is reached. --notify, or alerts.notify in the configuration, also sends one desktop notification; one that could not be sent is a warning and never changes the exit status. |
disktop scan [PATH] [--json] |
Walks PATH (the working directory by default) through the helper, writes the detailed index, and saves a snapshot. --accounting allocated|apparent, --cross-filesystems, --throttle RATE, --max-depth DEPTH, --sudo. Ctrl+C stops it at a directory boundary and still reports what was measured. |
disktop explore [PATH] [--json] |
One page of PATH and everything below it, from the most recent scan covering it. --sort, --order, --kind, --min-size, --max-size, --ext, --name, --older-than DAYS, --limit, --cursor, --type-totals, --owners. |
disktop snapshots list|diff [--json] |
Lists saved snapshots, or compares two of them (--from, --to; the two most recent by default). |
disktop clean [--json] |
Lists what every detector found, and changes nothing. --dry-run is accepted and redundant. --category CATEGORY narrows the list, --limit COUNT shortens it, and --no-sizes skips footprint measurement; known stat or manager-reported sizes remain available. |
disktop clean plan [FINDING_ID] [--path PATH] [--operation trash|permanent|empty-trash|move|compress|hardlink|manager] [--json] |
Reviews one finding or path into a stored, expiring plan. Changes nothing. --operation empty-trash needs no subject and can name only this user's own Trash. A managers: finding is planned as a manager action without naming the operation. |
disktop clean apply PLAN_ID --yes [--permanent] [--json] |
Applies an already-reviewed plan, revalidating every item against the identity the plan recorded. |
disktop history [--cursor CURSOR] [--limit COUNT] [--json] |
The durable action journal, newest first, with interrupted records resolved as it is read. A cursor the journal did not issue is an input error. A record lists at most 1000 of its items and says how many it left out in itemsOmitted; its counts still cover every item, and undo reads the whole record. |
disktop timer install|uninstall [--json] |
The opt-in hourly systemd user timer that runs only alerts check --notify. |
disktop undo ACTION_ID --yes [--json] |
Puts back what one Trash action moved. |
disktop report --format json|csv|html [--output FILE] [--path PATH] [--limit COUNT] [--findings] [--json] |
One standalone report: capacity, and optionally a stored scan and what the detectors found. Written to stdout, or to a new file that is never put over an existing one. See Reports. |
disktop completion bash|zsh|fish |
Prints a completion script generated from the same command table the parser reads. See Shell completions. |
disktop find empty|broken [--path PATH] [--limit COUNT] [--json] |
Empty directories and dangling symlinks, read out of the most recent scan covering the path. |
disktop find duplicates [--path PATH] [--min-size SIZE] [--keep oldest|newest|in-path] [--keep-under PATH] [--limit COUNT] [--json] |
Groups of files holding the same bytes, with the copy a keep rule would keep. Reads content; changes nothing. |
disktop find stale [--path PATH] [--older-than DAYS] [--limit COUNT] [--json] |
Files not modified for a threshold, with a statement of what that measures on this mount. |
disktop --units iec|si |
Switches human-readable units. Byte values in JSON never change. |
disktop --help, disktop --version |
Generated from the one command table in src/cli/parser.ts. |
A command declared in the table before it is built is marked [planned] in the help, parses and validates its options, and then refuses with not-implemented and exit 2, in the same envelope shape a working command uses. None is at present.
scan does not delete or move anything. It walks the tree through the Rust helper, which opens every directory with openat2 containment: it never follows a symlink, and without --cross-filesystems it stays on the filesystem the root is on. That filesystem includes its other mounts below the root that show a part of it nothing else in the scan reaches — Btrfs subvolumes mounted at /home, /var/log, or /.snapshots are the common case, and a scan of / that stopped at them would account for a fraction of what df reports as used. A mount of a different filesystem (/boot, /proc, a USB disk) is refused, and so is a bind mount repeating a tree the scan already reaches, so nothing is counted twice; each refused mount is listed in excludedMounts with a warning saying which of the two it was. A directory it cannot open is counted and named, never treated as empty, and any scan that missed something reports complete: false with at least one warning.
--sudo then measures the directories the scan could not read, with administrator rights: the system's own root-owned du runs read-only through pkexec (a desktop password dialog) or sudo (a password prompt on the terminal), with fixed flags and the absolute paths as its only arguments. This --sudo step elevates only the system du; the normal CLI and helper stay unprivileged. The sizes are kept beside the scan, one level deep, and are never added into its totals; the scan stays incomplete because the index still cannot browse inside those directories. scan --json reports them under elevated (common.json#/$defs/elevatedMeasurement); a refused or cancelled password prompt is status: "denied", and a machine where nothing can ask for administrator rights is unavailable. explore and report show the measured sizes where they apply, and the TUI does the same from Explore with A.
On WSL, /mnt/c and /mnt/wsl are excluded by default, even when named as the scan
root. Naming a path or adding --cross-filesystems does not override excludes.
To scan a selected Windows directory, set this in
$XDG_CONFIG_HOME/disktop/config.toml (normally ~/.config/disktop/config.toml):
[scan]
exclude_windows_mounts = falseThen use disktop scan /mnt/c/path/to/test-directory --json. Other configured
excludes still apply. The WSL diagnostic offers no Windows cleanup; actual WSL
validation remains tester follow-up.
Bytes are counted once per inode. A second hardlink to an inode the scan already counted is listed with shared: true, and its bytes are reported as sharedBytes rather than added to the totals, because deleting that path frees nothing.
A directory's allocatedBytes and apparentBytes are the totals for its whole subtree; a file's are its own. Per-extension totals cover regular files only, for the same reason: adding directory rows to them would count the same bytes twice.
explore never scans. It reads the index a previous scan wrote, and the path narrows the listing to that directory and everything below it, so exploring ~/Downloads after scanning ~ answers about Downloads. If no stored scan reaches the path — none has a root above it, or every one that does stayed out of a mount or exclude between the two — it says so and names the command that would produce one. A directory the scan never went inside is listed with ? for its size and says why (another mount, not scanned, or unreadable, size unknown), or with its size measured as root when --sudo measured it; its own few bytes are never printed as though it were nearly empty.
A scan of a tree with many unreadable directories reports every one of them in inaccessibleDirectories, but lists at most a few hundred individually and then summarises the rest as a warnings-truncated warning giving the count per code. Nothing is hidden; the list is bounded so that the output, the index, and every stored snapshot do not grow with the filesystem.
snapshots diff compares two snapshots only when they measured the same thing: same roots, same excludes, same accounting mode, same mount policy, same depth limit, and the same filesystems — the ones the walk actually read, which is not the same as the ones the roots sit on once a scan is allowed to cross a mount. The comparison reports the column the scan measured, so an apparent-accounting history shows apparent growth; a sparse image that grows by gigabytes without allocating a block is exactly why that matters. Anything else is refused, because subtracting a scan that excluded a directory from one that did not produces a number indistinguishable from real growth. A diff is marked uncertain whenever either scan was partial or a directory appears on only one side, since that is also what a rename looks like.
disktop scan --json reports allocatedBytes on the same basis as du -x --block-size=1: st_blocks × 512, each inode counted once, no other filesystem entered. The two agree exactly on the same tree, and tests/integration/scan.test.mjs asserts it. On Btrfs they differ by design: du -x stops wherever the device number changes, which is at every subvolume, mounted or not, while Disktop walks the subvolumes of the filesystem it is scanning.
sharedBytes is reported in the same unit as the totals beside it, so the two can be compared directly.
Apparent bytes are not comparable against du. du --apparent-size leaves the directories' own st_size out of its total and Disktop includes it, so the two are answering different questions. Neither figure is what df reports either: reflinks, compression, snapshots, and open-but-deleted files all make a tree's size differ from a filesystem's free space.
disktop Open the TUI
disktop --json Dashboard without a TTY
disktop devices --json
disktop scan [PATH] --accounting allocated|apparent --cross-filesystems --sudo --json
disktop explore [PATH] --sort allocated --min-size 1GiB --ext log --json
disktop find duplicates|stale|empty|broken [--path PATH] --json
disktop snapshots list|diff --json
disktop clean --dry-run --json
disktop clean plan FINDING_ID --operation trash|permanent|move|compress|hardlink --json
disktop clean plan --path PATH --operation trash --json
disktop clean apply PLAN_ID --yes --json
disktop clean apply PLAN_ID --yes --permanent --json
disktop history --json
disktop undo ACTION_ID --yes --json
disktop report --format json|csv|html [--output FILE] [--path PATH] [--findings]
disktop alerts check --threshold 90 --json
disktop timer install|uninstall
disktop completion bash|zsh|fish
The parser in src/cli/parser.ts defines commands and options once, and drives help plus completions. The CLI and TUI invoke the same application use cases. Any command that scans shows progress on stderr, and only when stderr is a terminal: redirected into a log or a pipe, a carriage-return progress line is noise, and --json never draws one. It can be cancelled, and reports an incomplete result when it could not inspect the full selected scope. Disktop does not use an interactive prompt when --json is requested or stdout is not a TTY.
disktop clean runs every detector and prints what they found. It applies
nothing, and no detector can delete; acting on a finding is clean plan and
clean apply.
Four rules shape the output. Every detector appears in providers with its
capability, including the ones that could not look; ran is false when it
never answered, whether it was absent, denied, or it threw. A detector that is
permission-denied makes the whole result incomplete — the data is there and
Disktop could not read it — and the command exits 3; a missing-tool
detector does not, because the feature is genuinely absent. Every size carries
a basis: a footprint nothing measured is unknown and carries no number,
never zero. And a categoryTotal counts each byte once: nested is how many
findings in that category sit inside another one, so a browser profile and the
cache directories inside it do not add up to more than the filesystem holds.
Sizes are measured in one pass after discovery, by the same scan index scan
and explore read, so every number in one result shares an accounting mode.
Asking for sizes and getting none is an incomplete result, not a complete one.
--no-sizes skips the pass on purpose, which is much faster, leaves directory
footprints unknown, and does not itself make discovery incomplete.
Detectors inspect known directory structures within a 4,096-entry listing bound.
A directory above that bound produces an explicit warning and an incomplete result,
never a sampled count presented as exact. Package-cache discovery also inspects at
most 10,000 entries across all of a manager's cache directories. An affected manager
preview is refused when either bound is exceeded.
Use scan and explore for larger directories; their native index streams entries
without this discovery limit.
Ctrl+C stops discovery at the next detector boundary. clean writes nothing
while it runs; measuring sizes over a large home directory can take a while,
and --no-sizes is the quick look. The TUI shows the same discovery with a
spinner and Esc to stop it.
clean --dry-run lists eligible findings and actions. clean plan creates an expiring immutable plan for a finding or explicitly selected path. The plan contains its operation, scope, exact or estimated totals, warnings, reversibility, and required permission. Move and compression plans will also fix the destination and whether the original source goes to Trash or is permanently removed. Large manifests remain disk-backed.
clean apply PLAN_ID --yes applies the already-reviewed operation after live revalidation. --yes does not skip planning. --permanent only acknowledges a plan that already contains irreversible removal; applying it to a Trash plan is refused rather than taken as an upgrade. CLI cleanup defaults to dry-run. undo uses the action journal and refuses destination collisions or changed outputs. Manager actions will expose estimated or unknown scope honestly when a manager cannot preview exact counts.
A plan expires: past expiresAt it describes a filesystem that may have moved on, and
applying it is refused rather than retried against whatever is there now. The expiry
is cleanup.plan_expiry_minutes in config.toml, sixty minutes by default.
An apply reports three numbers and never folds them into one. Selected bytes is
what the plan reviewed. Bytes moved to Trash is the reviewed size of what actually
moved, which on one filesystem is not space anybody got back until Trash is emptied.
Observed free-space change is statfs before and after; it is absent rather than
zero when either reading failed, and other processes write to the same filesystem, so
it is never presented as this action's doing alone.
An action that skipped or failed anything exits 3, so a script that never reads the
JSON still learns that what was reviewed is not what happened.
--operation move and --operation compress fix two more things that apply time may
not change: --destination PATH, the directory the output is published into, and
--source trash|permanent, what becomes of the original once that output is verified.
A move has to name a destination — "somewhere else" is the whole point of one and
there is no disk Disktop may pick on somebody's behalf — while a compress publishes
beside the source unless told otherwise. A move onto the source's own filesystem is
refused: it frees nothing, and mv already does it.
A destination is judged by its own policy rather than by the one that bounds what
Disktop may remove, because a cross-disk move means writing outside the user's roots by
definition. /mnt/archive is a legitimate destination and an illegitimate target. What
still applies is everything that says "not yours to write into": the protected system
roots, the shared container roots themselves, and Trash and Disktop's own state.
--operation hardlink replaces one copy of a file with a second name for another copy,
freeing the replaced copy's bytes. It is irreversible, so it needs --permanent at apply
time like any other irreversible plan. From an explicit path it takes a pair: --path is
the copy that survives and --replace PATH is the copy that becomes a name for it. The
plan records which one is kept rather than leaving it to the order of its entries. Before
anything is linked, the helper reads both files in full and refuses unless they hold
exactly the same bytes, and refuses again if their owner, group, or permissions differ —
one inode has one set of those, and linking would silently change the replaced file's.
--source permanent makes the whole plan irreversible and carries the warning that
says so, because publishing a copy and then releasing the original's bytes is a
permanent removal with an extra step.
--operation compress writes <name>.zst for a file and <name>.tar.zst for a
directory, beside the source unless --destination says otherwise. The archive is
verified by decompressing it and comparing what comes out against what went in, before
it is published and before the source is touched.
A move is carried out as a staged copy, not a rename: the bytes are written under a partial name in the destination, read back off the device and compared against what was read from the source, and only then published with a rename that refuses to overwrite. The source is not touched until that has happened, so a move that fails at any point leaves it exactly where it was.
A plan built from one of your own [[rules]] records that rule's identity. If you edit
the rule before applying the plan, the apply is refused and asks you to review it again:
what you confirmed was the selection the old rule described. See
providers.md and
config.example.toml.
Planning by FINDING_ID rediscovers first, so it takes as long as disktop clean
does. Planning --path does not. A path whose bytes are not valid UTF-8 cannot be
given as --path, because process arguments are UTF-8; such a path is still
discovered, planned from its finding, moved, and restored byte for byte.
find empty and find broken read the index a previous scan wrote; neither scans.
The walk counted each directory's entries as it read them and asked once per symlink
whether its target resolved, so both answers are already in the index. A directory the
scan could not open carries no child count at all and therefore never answers a search
for empty ones — "nobody looked" and "nothing is there" are different answers.
The question people ask is "what have I not opened in six months?" and on a normal
Linux system that question has no answer. Mounts are relatime by default, which
updates a file's access time at most once a day and only when it is already older than
the modification time; many are noatime, which never updates it at all. A listing
built on that and labelled "not opened since" would be confidently wrong about files
somebody uses every day.
So find stale measures the modification time — when the contents last changed —
and says so. Every answer carries a basis, whose field is always modified and
whose confidence comes from the options of the mount holding the search path:
absent for noatime, coarse for relatime, maintained otherwise, and unknown
when the mount table could not be read. unknown is deliberately not maintained: a
reading that did not happen is not a reassuring one. The mount's options change the
sentence, never the measurement, because no column in the scan index holds an access
time to measure instead.
The threshold is --older-than DAYS, defaulting to find.stale_after_days in the
configuration, which is 183 days. The listing covers regular files only.
find duplicates reads the same index to decide what is worth opening, then reads
content, so it costs more than the other three and answers a different kind of
question. It starts from the sizes more than one regular file shares, narrows those by
a digest of each file's first and last 64 KiB, and narrows what is left by a digest of
every byte. A file with no possible twin is never opened.
The answer is a list of groups rather than a page of rows, because which copy pairs
with which is the only thing anybody reading it is deciding about. Each group carries
reclaimableBytes — the group's size times one fewer than its members, because one
copy always stays — and the result's own reclaimableBytes is the sum over the groups
that have a keeper.
Two names for one inode are one member of a group, not two: removing the second frees
nothing. --min-size defaults to 1 MiB; without it the listing fills with small files
whose duplication costs nothing to keep.
--keep says which copy survives. oldest and newest read the modification
time, which is when a file's contents last changed; nothing here reads an access time,
because no column in the index holds one and on a relatime or noatime mount it
would not mean what a reader would take it to mean. When copies share a timestamp the
first path in byte order is kept and the decision says arbitrary: true rather than
presenting a coin toss as a judgement. --keep in-path PATH requires --keep-under
and keeps the single copy under that directory; if no copy is there, or more than one
is, the group is reported undecidable with its reason and contributes nothing to the
reclaimable total. It never falls back to another rule — somebody who asked to keep
what is under ~/Pictures is not asking to keep the oldest instead.
The digests group candidates and authorise nothing. Acting on a group goes through
clean plan and clean apply like everything else, and the helper re-opens both files
and compares them byte for byte before it touches either. See
adr/0006.
A search that hits a cap, cannot read a file, or is cancelled reports
status: incomplete with a warning saying so, and exits 3. A scan the index has
pruned is refused by name with the command that would make a new one; it is never
answered with no duplicates.
disktop report exports what Disktop knows as one document a person or a program can
keep: a JSON document, a CSV table, or a standalone HTML page. It reads; it changes
nothing, and it adds no reading of its own — every number in it comes from the same
services disktop --json, explore, and clean use.
disktop report --format json|csv|html [--output FILE] [--path PATH] [--limit COUNT]
[--findings] [--units iec|si] [--json]
A report has up to three sections, and each one says whether it is complete:
- Capacity, always: every filesystem with its size, available bytes, the share used
counted the way
dfcounts it, the share of inodes used where the filesystem reports inodes, every alert, every block device, and the partitions holding data that nothing has mounted, whose usage is unknown. This is the dashboard's joined view. - Scan, with
--path PATH: the newest stored scan that reached the path — its scope, totals, completeness, and warnings — plus, each cut at--limit(50 by default, at most 1000) and ranked by allocated bytes: what is directly inside the path (children, which do not overlap and so add up to the path's size), the largest files anywhere under it (largestFiles), and every entry under it (entries, where a directory is ranked beside its own ancestors), with the bytes per file extension under it. Unreadable directories under the path that were measured as root afterwards (scan --sudo, orAin the TUI) are listed underelevated, never added to the totals. A scan that stayed out of a mount or exclude between its root and the path does not count as reaching it. The totals are the whole scan's; the entries and type totals are the path's. Without--paththere is no scan section, and the report says so: the working directory is never assumed, so a report run from a timer or a script does not quietly depend on where it was started. A path no stored scan covers is an input error naming thedisktop scanthat would cover it. When the scan's index has been pruned or cannot be read, the section keeps the stored summary, leaves out the entries rather than listing none, and is incomplete. - Findings, with
--findings: what every detector found, with sizes measured, asdisktop cleanlists it — every detector with its capability, including the ones that could not look, and per-category totals that count each byte once. A denied detector makes the section incomplete exactly as it makescleanexit3.
An unknown size is reported as unknown in every format, never as zero, and a short section carries its warnings into every format.
Without --output the report is the whole of stdout, so it can be piped or redirected;
warnings go to stderr. With --output FILE it is written to a new file:
- the content is written to a staging file Disktop creates exclusively, with mode
0600, in the same directory; - it is flushed to the device;
- it is published under
FILEwithlink, which fails rather than replace anything already there — a file, a directory, or a symlink, dangling or not — and the staging name is removed; - the directory is flushed, so the new name survives a power cut as well as a crash.
A crash leaves at most a hidden .disktop-report-*.partial staging file, never a
truncated report under the name you asked for. On a filesystem that has no hard links,
such as vfat or exFAT on a USB stick, Disktop refuses report publication with an
actionable unsupported error. Choose an output directory on ext4, Btrfs or another
filesystem supporting hard links. A placeholder followed by an ordinary rename cannot
guarantee that a concurrently replaced destination remains untouched.
An existing FILE is refused with exit 2 before anything slow runs, and there is no
option to overwrite one: move the old report away or name a new one. Run as root,
Disktop writes no file itself, so --output is refused; redirect stdout instead,
disktop report --format html > report.html, and the shell you chose does the writing.
With --json, stdout carries one report.json envelope
describing what was written — the format, the output path with its bytes, the bytes
written, and the sections included — so the report itself needs --output; --json
without it is refused as ambiguous. The exit status is 0 when every included section
is complete, 3 when any is not (or the file was written but its directory could not be
flushed), 2 for an input or operational error, and 130 when Ctrl+C stopped the report
before it was written, in which case nothing is written at all.
--format json writes one report-document.json
document. It is not a CLI envelope: it is versioned on its own (schemaVersion), names
the document it is (disktop-report), when it was generatedAt, and the
generator's name and version. Its status is incomplete when any section is, and
each section carries its own complete and warnings. A section that was not asked for
is { "included": false, "reason": "..." }. Filesystems, devices, alerts, entries, type
totals, and findings use the same shapes as --json output, so every integer that can
exceed 2^53 is a decimal string and every path carries bytesBase64 beside its
sanitized display.
--format csv writes RFC 4180: UTF-8 with no byte-order mark, every record ending in
CRLF, a field quoted when it holds a comma, a quote, or a line break, and every quote
inside it doubled. Every row has the same columns, so the file loads as one table:
section,id,kind,path_display,path_bytes_base64,allocated_bytes,apparent_bytes,shared_bytes,
size_bytes,size_basis,total_bytes,free_bytes,available_bytes,used_percent,
inodes_used_percent,threshold_percent,entries,modified_at,status,detail
section says what a row is, and a row fills only the columns that apply to it. An
empty cell means "does not apply" or "not known", never zero: an unmeasured finding has
an empty size_bytes beside size_basis unknown, and a filesystem that reports no
inode counts has an empty inodes_used_percent. Byte columns are exact decimal integers;
a spreadsheet may display a large one rounded, and the file still holds it exactly.
section |
One row per | Columns it fills |
|---|---|---|
report |
fact about the report: id is schema-version, generated-at, generator, status, or a section name with kind section |
status (complete, incomplete, or omitted), detail |
capability |
capability of the capacity reading (id capacity) and of the detectors (id findings) |
status, detail |
filesystem |
filesystem, with its first mount point | id, kind (type), path, total_bytes, free_bytes, available_bytes, used_percent, inodes_used_percent, status (read-only or read-write), detail |
mount |
further mount point of a filesystem | id, path |
device |
block device | id, kind (ssd, hdd, unknown), total_bytes, entries (partitions), detail |
volume |
every persistent partition or logical volume | id, kind (filesystem signature or unknown), path_display, total_bytes, status, detail |
unmounted |
partition with data that nothing has mounted | id, kind (filesystem type), path_display (the device node), total_bytes, status (unmounted or locked), detail |
alert |
alert | id (filesystem), kind, used_percent, threshold_percent, detail |
scan |
included scan | id (scan), kind (accounting), path (the --path), allocated_bytes, apparent_bytes, shared_bytes (whole scan), entries (scanned), modified_at (when scanned), status, detail |
scan-root, excluded-mount |
root of the scan, mount it did not enter | id (scan), path |
child, largest-file |
entry directly inside the path; largest file under it | id, kind, path, allocated_bytes, apparent_bytes (both empty with status not-entered for a directory the scan never went inside), entries, modified_at, status |
measured-as-root |
unreadable directory measured afterwards with administrator rights | id (scan), path, size_bytes, size_basis, modified_at (when measured), detail |
entry |
listed entry, largest first | id, kind, path, allocated_bytes, apparent_bytes, entries (a directory's children), modified_at, status (shared-hardlink, broken-symlink) |
entry-limit |
listing cut at --limit |
entries (the limit), detail |
type-total |
file extension, id empty for none |
id, allocated_bytes, apparent_bytes, entries |
finding |
finding | id, kind (category), size_bytes, size_basis, entries (paths), status (capability), detail |
finding-path |
path of a finding, so a finding's size is counted on one row | id (finding), path |
provider |
detector asked | id, kind (ran, did-not-run), entries (findings), status (capability), detail |
category-total |
finding category | id, size_bytes, entries (findings), detail |
warning |
warning | id (code), kind (the section it belongs to), path, detail |
"Path" is the pair path_display and path_bytes_base64. path_display is the
sanitized form, safe to show; path_bytes_base64 is the name's exact bytes and the only
column a program should treat as the name.
Every cell is sanitized first, so no control character survives into one: a newline in a
filename is its Control Picture ␊, not a record break. A cell that would then begin
with =, +, -, or @ — =cmd|' /C calc'!A0, @SUM(A1), +1, -1 — is prefixed
with an apostrophe so a spreadsheet shows it as text rather than evaluating it; tab and
carriage return are covered by the same rule, though sanitizing has already turned them
into ␉ and ␍. A cell that already begins with an apostrophe gains one more. To get a
cell's original text back, remove exactly one leading apostrophe from any cell that has
one; nothing else changes. Base64 of an absolute path always begins with L, so the
bytes column is never touched.
--format html writes one standalone page: no script, no external stylesheet, font, or
image, and no link that leaves the page. Its first element after the character set is a
Content-Security-Policy of default-src 'none'; style-src 'unsafe-inline', so even a
mistake in escaping could neither run a script nor fetch anything; inline styles are the
only thing it allows. Every value on the page — names, mount sources, device models,
finding titles, explanations, warnings — is sanitized and then has &, <, >, ",
and ' escaped, in text and in attributes alike. A name shown with substitutions,
because it was not valid UTF-8 or held a character that had to be replaced, is marked
†, and its exact bytes in base64 are in its tooltip, because two different names can
be shown the same.
Sizes are shown in the --units you chose with the exact byte count in a tooltip;
capacity is drawn as bars whose width is the used percentage, red where an alert has
been raised; a page follows the reader's light or dark preference. Incomplete sections
are badged and their warnings listed at the top, one line per kind of warning that opens
(an HTML details element, no script) to every path it names. The scan section shows
what is directly inside the path with each entry's share of it, then the largest files,
then the file types; a directory the scan never went inside shows unknown and why,
rather than a size.
disktop completion bash|zsh|fish prints a completion script to stdout and installs
nothing. The script is generated from the command table in src/cli/parser.ts — the
same table the parser validates against and the help is rendered from — so it offers
exactly the commands, subcommand words, options, and option values this version
accepts. It completes:
- command words, including the words that lead to one (
alertsthencheck,cleanthenplanorapply); - operand keywords:
find duplicates|stale|empty|broken,snapshots list|diff,timer install|uninstall, andcompletion bash|zsh|fish; - each command's own options,
--help, and--versionat the top level; - an option's fixed values, such as
--format json|csv|htmlor--units iec|si; - file names wherever a path belongs: the
PATHoperand ofscanandexplore, and every option whose value is aPATHorFILE, such as--outputand--path.
An option's value is never mistaken for a command word, wherever it sits, which is the
same rule the parser follows; a plan or action ID, a count, or a size completes nothing
rather than offering file names that would be wrong. An unknown shell is refused with
exit 2. Regenerate the script after upgrading Disktop.
bash (needs bash 4 or later, which every supported distribution ships). For your
account, with the bash-completion package installed:
mkdir -p ~/.local/share/bash-completion/completions
disktop completion bash > ~/.local/share/bash-completion/completions/disktopWithout bash-completion, add source <(disktop completion bash) to ~/.bashrc.
zsh. Put the script in a directory on $fpath under the name _disktop, before
compinit runs:
mkdir -p ~/.zfunc
disktop completion zsh > ~/.zfunc/_disktop
# in ~/.zshrc, before compinit:
fpath=(~/.zfunc $fpath)
autoload -Uz compinit && compinitAlternatively, add source <(disktop completion zsh) to ~/.zshrc after compinit.
zsh shows each command's and option's summary beside it.
fish:
disktop completion fish > ~/.config/fish/completions/disktop.fishfish loads it the next time disktop is completed.
- Every
--jsoncommand writes exactly oneenvelope.jsonobject to stdout:schemaVersion,command,generatedAt,status,exitCode, optionalwarnings, and thendataor, when the status iserror,error. An incomplete result must carry at least one warning. - Filesystem identities, counts, byte values, and nanosecond timestamps are decimal strings, never JSON numbers. A path is
{bytesBase64, display, utf8?}; onlybytesBase64is lossless, anddisplaycarries no character that can command a terminal or reorder what follows it. Two different names can still display the same, so nothing resolves a target fromdisplay. See adr/0005. - Objects are closed to unknown fields, so new output requires a schema change in the same commit.
- Structured output goes to stdout. Progress, diagnostics, and permission messages go to stderr. A failed JSON command still emits a schema-compatible error object when possible.
- Every scan result includes scope, completeness, scanned entry count, inaccessible directory count, excluded mounts, and warnings. A missing optional tool or denied permission is a capability state, not an empty successful result.
- CSV export quotes and escapes fields and prefixes an apostrophe to any cell a spreadsheet would evaluate (one starting
=,+,-,@, tab, or carriage return) and to one already starting with an apostrophe, so the rule can be undone. HTML export escapes all file and provider text and can neither run a script nor load anything. Export formats label allocated versus apparent bytes, estimates, and partial results. See Reports. - Human-readable units can switch between SI and IEC; the underlying byte values do not change.
| Code | Meaning |
|---|---|
0 |
Requested operation completed. |
1 |
alerts check reached its capacity or inode threshold. |
2 |
Invalid input, unavailable capability, permission failure, an unimplemented command, or another operational error. |
3 |
Scan or action ended incomplete, including partial results. |
130 |
Interrupted: Ctrl+C, SIGTERM, or a hangup stopped the command before it finished. |
Ctrl+C asks scan, clean, clean plan, clean apply, undo, and find to stop at their next safe boundary — a directory, a detector, an item. Each still reports and journals what it did, marked incomplete with a warning, and exits 130; with --json that partial result is the envelope, with exitCode: 130. A command interrupted before it had any result is an error envelope whose failure code is cancelled, also exit 130. A command that had already finished everything when the interrupt landed reports complete and exits 0, because nothing was left undone. A second Ctrl+C does not abandon the item in progress, which is the one moment a record could stop matching the disk; it says the command is already stopping. SIGTERM and SIGHUP are handled the same way.
--help, --version, and a command line that does not parse are answered from the command table before anything else runs: no configuration is read and, as root, the install is not inspected, so help is available even where every real command would refuse to start. An empty value or operand (--path=, or --path "$UNSET") is refused rather than resolved to the working directory, a value option given twice is refused rather than letting one silently win, and an argument holding bytes that are not UTF-8 is refused because Node has already replaced them and the path it would name is not the one typed. A refused command line exits 2 with its reason on stderr and nothing on stdout; with --json the reason is instead one invalid-input error envelope on stdout. Anything a command did not expect is reported as one sanitized line (or one internal-error envelope) and exit 2, never as a stack trace.
A reader that stops early — disktop devices | head -1 — is not an error: the rest of the output is dropped, the command finishes, and it exits with its own status. Any other failure to write stdout, such as a full disk behind a redirect, is reported on stderr and exits 2, because nobody received the answer.
An alert threshold is an expected monitoring outcome, so 1 is reserved for that command: disktop --json reports the same alerts and still exits 0. Incomplete reporting takes precedence over both, so an alerts check that reached a threshold on readings it could not complete exits 3 rather than 1; an alert drawn from partial readings is not the whole picture. Contract tests must check stdout, stderr, status, and schema together.
An inventory is incomplete whenever anything could not be read: a mount whose statfs was denied, a missing lsblk, an unparsable mountinfo line, or a configuration file that could not be applied. Each one adds a warning naming what was missed, and no missing reading is ever reported as a zero.
A statfs that does not answer within five seconds — a hard NFS mount whose server has gone does this — is a statfs-timeout warning and that filesystem is left out. Capacity probes run in bounded isolated subprocesses, so an unreachable mount cannot exhaust the main Node worker pool. A timed-out probe is killed and detached; if kernel I/O prevents it from exiting immediately, its path is remembered until it is reaped and repeated refreshes do not start more probes for that path. A finished command can exit while such a probe is pending. Unavailable usage is omitted with a warning, never reported as zero. Device models, transports, and filesystem types are sanitized where they are read: a USB device chooses its own model string and any user who can mount FUSE chooses a filesystem subtype that every other user's dashboard prints.
disktop clean lists what package and container managers can clean, as findings whose
id starts with managers: and whose managerScope is the exact command line they would
run. disktop clean plan managers:<action> asks the manager again, now, and stores a
plan holding the action, its items, and its parameters. The command is derived from
those by a fixed template every time the plan is read, so an edited plan file cannot
name a different program or option, and the plan's JSON shows the derived argument
vectors under manager.commands.
A manager plan is irreversible and needs --permanent at apply time. Apply runs a live
preflight first: an item that is gone or in use again is skipped, and a kernel purge is
refused outright if the running kernel has become one of the reviewed packages or the
simulated removal now takes anything else. A command that needs root is run as
sudo -- /usr/bin/TOOL ARGS (with -n when there is no terminal or --json was given)
or, interactively without sudo, pkexec. Nothing else is escalated. A refused password
skips the rest of the action, is recorded, and exits 3.
Counts and sizes are what the manager says, labelled exact, estimated, or
unknown; selectedBytes is absent when the manager could not say beforehand. The
result's free-space readings are the measurement.
What is offered, and never more: package files apt, dnf, or pacman downloaded; archived
journal files beyond managers.journal_keep_bytes; disabled Snap revisions; Flatpak
runtimes Flatpak itself judges unused; dangling images, stopped containers, and
anonymous volumes for Docker and Podman, never forced; Docker build cache nothing refers
to; kernels that are neither running nor the newest, only when a simulated removal takes
exactly their packages; and what systemd-tmpfiles' own age rules allow, for temporary
files and, under /var/crash and /var/lib/systemd/coredump, crash files. A named
volume is reported and never offered.
Run as root, Disktop plans and applies no change to a file itself; reviewed manager actions still run.
disktop explore PATH --owners adds bytes per owning user under PATH, over regular
files, from the scan that covers it, with account names from /etc/passwd where it can
be read. A scan that could not open some directories makes every total a floor: the
result exits 3 and says so, and names the read-only administrator scan that would
complete it — disktop scan run as root from a root-owned install, never sudo npx.
timer install writes disktop-alerts.service and disktop-alerts.timer under
$XDG_CONFIG_HOME/systemd/user, each starting with a # Managed by Disktop line, and
enables the timer. The service runs alerts check --notify hourly and nothing else; it
never cleans. Install refuses to overwrite a unit that does not carry the marker, and
reports failed reload or enable steps with an error and the systemctl diagnostic.
timer uninstall disables the timer before removing marked units; if disable fails,
the units remain in place and the error warns that the timer may still run. A failed
reload after removal gives the recovery command. Uninstall is safe to run twice.
Neither command elevates anything.
Configuration is $XDG_CONFIG_HOME/disktop/config.toml with the standard home fallback;
config.example.toml documents every key. Rules never contain
shell commands and pass through the same preview and apply path.
disktop with no command, on a terminal, opens the TUI. It is a surface over the same
application services as the commands above and can do nothing they cannot: every change
is a reviewed plan, applied through clean apply's service, and journalled.
| Tab | Shows | Keys beyond the common ones |
|---|---|---|
| 1 Disks | Connected drive counts, readable filesystems with usage bars, and every other partition or logical volume. The selected filesystem separates used, root-reserved, and available space, device, inodes, and mounts. Locked, swap, RAID/LVM backing, and unknown-signature storage have explicit states; unknown never means empty. | Enter explore a mounted tree, S scan it |
| 2 Explore | A stored scan, a directory at a time: size, share of the parent, growth since the previous comparable snapshot, a trend sparkline of the total, file types. A directory the scan never entered shows ? and why; after A, an unreadable one shows its size measured as root and opens to one level of what is inside. |
Enter/l open, h/Backspace up, s sort, f finders (largest, duplicates, stale, empty, broken), / filter, t types, n more, c plan, S scan, A measure unreadable directories as root (asks for your password) |
| 3 Clean | Findings a plan could act on, totalled by category, then informational ones. | Enter details, c plan, p detectors, r look again |
| 4 Dev, 5 Apps | The same findings narrowed to development or to applications. | as Clean |
| 6 History | The journal, item by item. | u undo a Trash action, n older |
Common keys: j/k/arrows, g/G, PgUp/PgDn, Ctrl+U/Ctrl+D, 1–6, Tab and [/],
U units, r refresh, ? help, Esc close or stop, q and Ctrl+C quit. The mouse
selects rows, switches tabs, and scrolls.
The filter after / is words (name contains), ext:log or .log, >1GiB/<5MB
(allocated size), age>30 (not modified for 30 days), and type:file|dir|link|other.
It compiles to the same EntryFilter as explore's flags. Long filters scroll their text to keep the
newest input and its cursor visible. In the detector list (p), j/k, paging, and
g/G reach every detector; the selected explanation appears below the list.
A plan is reviewed in a dialog showing its operation, whether and how it can be undone,
the selected bytes and item count, the permission it needs, its expiry, its warnings,
and its entries. y applies a reversible plan; an irreversible one needs yes typed
and Enter. o re-plans with the next operation on offer. The TUI plans Trash,
permanent removal, emptying Trash, manager actions, and — for an Explore entry, or a
finding that offers them — a move to another disk and a compression; for a copy in a
duplicate group it offers Trash or a hardlink replacement (byte-compared by the helper)
and never a plain permanent removal. A move or a compression asks first, in a dialog
that plans nothing, for the directory its output goes into (absolute, or ~/ for
home; a compression left empty goes beside its source) and, with Tab, whether the
source then goes to Trash or is removed permanently — the same --destination and
--source that clean plan takes. The last answer is offered again, and o on a
move review asks again for a compression with it. A plan that needs root
suspends the TUI while sudo or pkexec asks for the password, then takes the
terminal back. Results keep selected bytes, bytes moved to Trash, and the observed
free-space change apart, as clean apply --json does.
Esc stops a running scan (what it read is indexed and marked incomplete), a discovery,
an index query, or a duplicate search. An apply or undo stops after its current item and still reports;
q is refused while one runs, and Ctrl+C asks it to stop, waits for it to journal, and
exits 130. A normal quit exits 0, or 3 when the inventory was incomplete.
The TUI uses Catppuccin Mocha: mauve accents,
dark surfaces, teal usage bars, yellow warnings, and soft red failures. COLORTERM=truecolor
or 24bit selects the original RGB palette; 256- and 16-colour terminals use
approximations. Selection, state glyphs, and distinct distribution fills remain
readable without colour. The scan activity bar is indeterminate: a tree's total extent
is unknown until traversal finishes. A duplicate listing retains at most 10,000 rows;
if a group exceeds this, its true copy count and the limit are shown, and a smaller
directory can be searched. Short dialogs centre around their content, and result
dialogs show the journal id and preserve partial or uncertain outcomes.
Environment: NO_COLOR (non-empty) removes colour and keeps bold and inverse; a locale
that is not UTF-8, TERM=linux, or DISKTOP_ASCII=1 draw ASCII glyphs;
DISKTOP_NO_MOUSE=1 leaves mouse reporting off. The layout is designed for 80×24 and
stays usable down to 40×10, below which it says so. A plan is reviewed and confirmed
only at 60×20 or larger, so its target, operation, and confirmation are all on screen;
smaller, the review says so and offers no confirmation. Terminal state is restored on exit,
on SIGINT, SIGTERM, SIGHUP, and after an uncaught exception.