mountx CLI
#The mountx CLI
Use one command to create a real mount and print each kernel request.
npx mountx # an in-memory tree at ~/mountx
npx mountx /tmp/scratch # somewhere else
npx mountx --helpYou do not need root on Linux or macOS. Unprivileged FUSE requires fusermount3. On macOS, you must own the NFS mount point. Only the mount point remains after cleanup.
If you name a transport, the CLI skips the probe and calls that transport. 9P requires Linux and root.
sudo -E "$(command -v npx)" mountx /tmp/scratch -t 9p # 9P: Linux, and rootUse command -v because root's PATH usually does not include a version-managed node.
Note
The CLI is a demonstration and test tool. It is not a general mount tool. It always serves the memory driver included with mountx. The in-memory tree exists only while the process runs. Use the library to mount a real driver.
#What it does
The CLI prepares an in-memory filesystem, adds a request logger, and mounts it through mountx/auto.
Auto checks the host one time.
On Linux, it selects the first usable transport in this order: FUSE, 9P, then NFS.
On macOS, it selects NFSv3.
The choice is final.
If the selected transport cannot mount, auto does not fall back.
The CLI then prints each lookup, open, read, and write request from the kernel. The log shows traffic from commands such as ls -l. It also shows the effect of the attribute cache. You can count the FUSE requests caused by one system call.
By default, the CLI does not print successful lstat, stat, and statfs polls.
Use --verbose to print them.
A directory listing sends one lstat for each entry, and desktop software polls statfs.
Without --verbose, the CLI prints these calls only when they fail.
An ENOENT often explains the command that caused it.
#Options
| flag | action | default |
|---|---|---|
[mountpoint] or -m, --mountpoint <path> | select the mount point | ~/mountx, or $MOUNTX_MOUNTPOINT |
-t, --transport <name> | select auto, fuse, 9p, or nfs | auto |
-q, --quiet | do not log filesystem requests | off |
-v, --verbose | also log metadata polls (lstat, stat, and statfs) | off |
-r, --read-only | mount read-only | off |
--empty | use an empty tree instead of the prepared tree | off |
--allow-other | let other users access the mount (FUSE; implied as root) | off |
-h, --help | show usage |
The CLI expands a leading ~ in the mount point in the same way as a shell. Press Ctrl-C to unmount and exit.
#Using it
Run client commands from another terminal. Do not run them from the serving process. See Troubleshooting.
ls -l ~/mountx
head ~/mountx/README.md
echo 'written from outside' > ~/mountx/note.txt
cat ~/mountx/note.txtThe first terminal shows the requests for each command.
#If it dies without unmounting
If the process is killed before it unmounts, the mount remains in the mount table and returns ENOTCONN. A later mount() refuses to stack on that path.
On its next run, the CLI removes a stale entry at the same path. If cleanup requires privileges that the CLI does not have, it prints the required command.
fusermount3 -u -z ~/mountx # FUSE, unprivileged — run for you
umount -f ~/mountx # NFS on macOS — run for you
sudo umount -l ~/mountx # NFS on Linux — printed, not run
sudo umount -l ~/mountx # 9P on Linux — printed, not run; always root, there is no unprivileged 9P routeWhen the CLI runs as root, it uses umount -l directly.
The CLI cannot remove stale Linux NFS or 9P mounts without root. umount(8) is not set-user-ID on Linux, so the CLI prints a sudo command instead. Both transports required root when they were mounted.
The CLI can remove unprivileged FUSE mounts because fusermount3 -u is set-user-ID. It can remove macOS NFS mounts because macOS lets the user who created a mount remove it. See NFS mount requirements.
#From source
Run these commands when you work in the repository instead of using the published package:
pnpm mountx # node src/cli/index.ts
pnpm mountx --helpSource: src/cli/index.ts.