Command reference
CLI
Install and use the nuFS CLI on Windows. File commands, history, access keys and local cache management.
Install the client
Run the nuFS EXE installer. It installs the desktop app, CLI and WinFsp mount component together. Open a new PowerShell terminal after installation to use nufs. For later desktop updates, use Settings → Check for updates, then Download update and Install & restart. Your saved session and settings are kept.
# Run the downloaded installer in PowerShell:
.\nufs-VERSION-windows-x86_64.exe
# In a new terminal:
nufs --version
nufs --helpSign 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.
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_IDMount a drive
Choose an unused drive letter, such as N:. Leave the foreground mount running while you work. The desktop app can also mount the selected drive and open it in File Explorer.
nufs mount DRIVE_ID N: write
# From another PowerShell terminal:
Get-ChildItem N:\
nufs unmount N: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.
nufs cache status DRIVE_ID
nufs cache clear DRIVE_ID
# Use another private CLI profile:
$env:NUFS_CLI_HOME = "$env:USERPROFILE\.nufs-cli"
nufs cache status DRIVE_IDList and read files
Use entry IDs from ls. Offsets and lengths are measured in bytes; '-' streams content to standard output.
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 4096Create 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.
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_IDInsert, remove, splice and truncate
Supply the current version for each new edit. A successful edit returns a new version for your next operation.
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_IDRead 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.
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_IDManage files, folders and drives
Rename, move and deletion require the reviewed entry revision.
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_REVISIONSearch and retrieve text
Search lists matches; retrieve returns passages with immutable source citations. Pass the returned cursor for another page.
nufs search DRIVE_ID "project notes" 20
nufs search DRIVE_ID "project notes" 20 CURSOR
nufs retrieve DRIVE_ID "project notes" 5Create 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.
nufs keys create automation read drive DRIVE_ID ./key.json
nufs keys list
nufs keys revoke KEY_ID
nufs auth logout