Beta
Download

nuFS Public Beta. Compatibility changes and release notes.

Command reference

CLI

Install and use the nuFS CLI on macOS. File commands, history, access keys and local cache management.

Install and open the CLI

Install the nuFS DMG by dragging nuFS into Applications. The CLI is included inside the app; no separate download is needed. Add its directory to PATH for the current terminal session.

Shell
export PATH="/Applications/nuFS.app/Contents/Resources/bin:$PATH"
nufs --version
nufs --help

Sign in and find a drive

Use your deployment's API origin without /v1. Enter the code sent to your email; later commands use your saved profile.

Shell
nufs --endpoint https://api.example.test auth login you@example.test
nufs auth status
nufs drives

# Free drive (20 GB, one person):
nufs plans
nufs drive create "My Drive" 20 1
nufs subscription DRIVE_ID
# Change your plan using the storage, member limit and revision from plans and subscription:
nufs subscription DRIVE_ID 50 2 REVISION
nufs drive leave SHARED_DRIVE_ID

Mount through the desktop app

Open nuFS, sign in, select your drive and choose Mount. Use Finder to open the mounted drive. The CLI can list, read and update files through the API independently of the mount.

Shell
open -a "nuFS"

# Use the CLI with the same account and drive:
nufs drives
nufs ls DRIVE_ID

Inspect and clear local cache

In the desktop app, open Settings → Local cache to see the selected drive's cache location and clear downloaded file data. Saved cloud files, credentials and pending edits are kept. Close open videos or files first so their reads do not fill the cache again.

The commands below inspect and clear the CLI profile's cache. Desktop and CLI profiles have separate cache locations. Unmount a CLI mount before clearing its cache; these commands work without signing in or contacting the backend.

Shell
nufs cache status DRIVE_ID
nufs cache clear DRIVE_ID

# Use another private CLI profile:
NUFS_CLI_HOME="$HOME/.nufs-cli" nufs cache status DRIVE_ID

List and read files

Use entry IDs from ls. Offsets and lengths are measured in bytes; '-' streams content to standard output.

Shell
nufs ls DRIVE_ID
nufs ls DRIVE_ID FOLDER_ID
nufs stat ENTRY_ID
nufs get ENTRY_ID ./downloaded.txt
nufs get ENTRY_ID - 0 4096

Create and update a file

Use the new entry ID returned by create. none is only for a file with no committed version. Subsequent edits use the returned version ID.

Shell
nufs create DRIVE_ID notes.txt file
# Save "hello" in content.txt using your text editor.
nufs write-at ENTRY_ID 0 ./content.txt none OPERATION_ID

# Save "H" in edit.bin for the partial update.
nufs write-at ENTRY_ID 0 ./edit.bin VERSION_ID NEXT_OPERATION_ID

# Replace the whole file using the entry revision from stat:
nufs put ENTRY_ID ./replacement.txt ENTRY_REVISION
nufs status DRIVE_ID
nufs sync DRIVE_ID

Insert, remove, splice and truncate

Supply the current version for each new edit. A successful edit returns a new version for your next operation.

Shell
nufs insert ENTRY_ID 5 ./addition.bin VERSION_ID OPERATION_ID
nufs remove ENTRY_ID 5 10 VERSION_ID OPERATION_ID
nufs splice ENTRY_ID 5 10 ./replacement.bin VERSION_ID OPERATION_ID
nufs truncate ENTRY_ID 1024 VERSION_ID OPERATION_ID

# edits.json: {"changes":[{"offset":0,"data_file":"edit.bin"}]}
nufs patch ENTRY_ID ./edits.json VERSION_ID OPERATION_ID

Read history and restore

History is off by default. The drive owner can enable it for future edits. Clearing history permanently removes earlier versions while preserving current files.

Shell
nufs history-settings DRIVE_ID
# Use the revision returned above.
nufs history-settings DRIVE_ID on HISTORY_REVISION
nufs history ENTRY_ID
nufs get ENTRY_ID ./earlier.txt 0 4096 VERSION_ID
nufs restore ENTRY_ID VERSION_ID ENTRY_REVISION
nufs ls-at DRIVE_ID CHANGE_SEQUENCE

# Permanently clear retained history.
nufs clear-file-history ENTRY_ID
nufs clear-history DRIVE_ID

Manage files, folders and drives

Rename, move and deletion require the reviewed entry revision.

Shell
nufs create DRIVE_ID assets folder
nufs rename ENTRY_ID new-name.txt ENTRY_REVISION
nufs rename ENTRY_ID new-name.txt ENTRY_REVISION DESTINATION_FOLDER_ID
nufs rm ENTRY_ID ENTRY_REVISION

Create and revoke an access key

The create command writes the one-time key secrets to a new private output file. Use a drive-scoped key for access to one drive.

Shell
nufs keys create automation read drive DRIVE_ID ./key.json
nufs keys list
nufs keys revoke KEY_ID
nufs auth logout