Skip to main content
The smolfs command manages SmolFS workspaces from your terminal. Use it to check the machine, create a volume, open it as a folder, save writes, inspect state, and close it.

​
Common flow

smolfs doctor
smolfs init demo --dev
smolfs mount demo ./workspace
echo hello > ./workspace/hello.txt
smolfs flush demo
smolfs unmount demo

​
Commands

CommandWhat it doesUseful flags
smolfs doctorChecks the storage backend, mount support, and local config.--install, --json
smolfs init NAME --devCreates a local development volume.--dev
smolfs init NAME --metadata URL --storage TYPE --bucket BUCKETCreates a cloud-backed volume with explicit storage settings.--metadata, --store, --storage, --bucket
smolfs mount NAME PATHOpens a volume as a local folder.--foreground, --check-storage
smolfs status [NAME]Shows known volumes and current mountpoints.--json
smolfs flush NAMESaves recent writes for a mounted volume.none
smolfs unmount NAMECloses a mounted volume.--force
smolfs umount NAMEShort alias for smolfs unmount NAME.--force

​
Local volumes

Use --dev for the first run: 
smolfs init demo --dev
Local volumes keep their backing data under SMOLFS_HOME, or ~/.smolfs when SMOLFS_HOME is not set.

​
Cloud volumes

Cloud volumes need a metadata URL and object storage settings: 
smolfs init agent-workspace \
  --metadata redis://localhost:6379/1 \
  --storage s3 \
  --bucket https://my-bucket.s3.us-east-2.amazonaws.com
Keep storage credentials in the environment used by SmolFS. Avoid putting access keys in commands, logs, or docs.
Cloud setup is still changing quickly. Treat this as the shape of the current CLI, not a full production guide.
Last modified on June 24, 2026