Peerbit Shared FS CLI

Experimental native mount CLI for @peerbit/shared-fs.

peerbit-fs create
peerbit-fs create --no-auth
peerbit-fs whoami
peerbit-fs trust <address> <public-key>
peerbit-fs install-adapter
peerbit-fs mount <address> <mountpoint>
peerbit-fs mount <address> <mountpoint> --native-adapter peerbit-shared-fs-native
peerbit-fs status [address]
peerbit-fs conflicts <address>
peerbit-fs benchmark [address]
peerbit-fs unmount <mountpoint>

benchmark writes and reads one large file plus a configurable many-small-files workload. It is a baseline for tracking regressions, not a claim that v0 is optimized for code workspaces.

status prints the current native mount adapter, whether its prerequisites are available on the host, and any missing pieces before optionally opening an address.

create creates an access-controlled filesystem rooted at the local Peerbit identity. Use create --no-auth only for explicitly unauthenticated test/demo filesystems. Another machine can run peerbit-fs whoami to print its writer key; the owner can then run peerbit-fs trust <address> <public-key> to authorize that writer.

Install

Install the CLI, then make sure the native adapter is installed:

npm install -g --omit=peer @peerbit/shared-fs-cli
peerbit-fs install-adapter
peerbit-fs status

--omit=peer keeps npm from auto-installing optional browser and React Native peer packages that are not needed by the Node.js CLI.

peerbit-fs install-adapter downloads a prebuilt peerbit-shared-fs-native binary into ~/.peerbit/shared-fs/bin. The global package install also tries this automatically, but the explicit command is safe to rerun and is the easiest way to repair a missing adapter. mount and status auto-detect that managed adapter, a peerbit-shared-fs-native command on PATH, or PEERBIT_SHARED_FS_NATIVE_ADAPTER.

Native runtime prerequisites are platform-specific:

• Linux: FUSE/libfuse. On Debian or Ubuntu, install fuse3 and libfuse3-dev.
• macOS: macFUSE. With Homebrew, run brew install --cask macfuse, then approve macFUSE in System Settings and reboot if macOS requires it.
• Windows: WinFsp runtime must be installed before mounting.

Create and mount an authenticated shared filesystem:

peerbit-fs status
ADDRESS=$(peerbit-fs create)
mkdir -p "$HOME/PeerbitShared"
peerbit-fs mount "$ADDRESS" "$HOME/PeerbitShared"

On Windows PowerShell:

peerbit-fs status
$address = peerbit-fs create
New-Item -ItemType Directory -Force "$env:USERPROFILE\PeerbitShared"
peerbit-fs mount $address "$env:USERPROFILE\PeerbitShared"

Authentication is on by default. Use peerbit-fs create --no-auth only for explicitly unauthenticated tests or demos.

Share With Another Machine

On the joining machine, print the local Peerbit writer key:

peerbit-fs whoami

On a machine that already owns or can write the filesystem, authorize that key:

peerbit-fs trust "$ADDRESS" <public-key>

The joining machine can then mount the same address:

mkdir -p "$HOME/PeerbitShared"
peerbit-fs mount "$ADDRESS" "$HOME/PeerbitShared"

Run peerbit-fs status "$ADDRESS" when diagnosing a host. It checks the native adapter, platform prerequisites, local Peerbit state, and whether the address can be opened.

macOS from this repo

For repository development, the macOS installer builds the TypeScript CLI and the external Go/macFUSE adapter, then installs wrappers into ~/.local/bin:

pnpm shared-fs:install:macos
export PATH="$HOME/.local/bin:$PATH"

peerbit-fs status
ADDRESS=$(peerbit-fs create)
mkdir -p "$HOME/PeerbitShared"
peerbit-fs mount "$ADDRESS" "$HOME/PeerbitShared"

macFUSE is required. The installer tries brew install --cask macfuse when Homebrew is available, but macOS may still require one-time approval in System Settings > Privacy & Security and a reboot.

The external packages/shared-fs/native adapter uses cgofuse for Linux FUSE, macFUSE, and WinFsp. The repo includes a manual Shared FS Native Smoke GitHub workflow for Linux FUSE. Portable CI still runs the backend and cross-OS shared-store checks on Linux, macOS, and Windows.