Common Usage

Add a File

Run the btfs add command:

User-MacBook-Pro:images user_home$ btfs add heart.png
added QmdA3o9nFLwfF21GizuMK4xZpvdrZmwdA8xR8Z78Hn7J1i heart.png
 29.89 KiB / 29.89 KiB [==================================================================================] 100.00%

Get a File

Run the btfs get command:

User-MacBook-Pro:images user_home$ btfs get QmdA3o9nFLwfF21GizuMK4xZpvdrZmwdA8xR8Z78Hn7J1i
Saving file(s) to QmdA3o9nFLwfF21GizuMK4xZpvdrZmwdA8xR8Z78Hn7J1i
 29.89 KiB / 29.89 KiB [===============================================================================] 100.00% 0s

File Pinning

In the default configuration, BTFS nodes garbage collect their cache when the storage exceeds the max capacity threshold set in the configuration file. Pinned files, however, are exempt from the garbage collection process.

User-MacBook-Pro:images user_home$ btfs pin add QmdA3o9nFLwfF21GizuMK4xZpvdrZmwdA8xR8Z78Hn7J1i
pinned QmdA3o9nFLwfF21GizuMK4xZpvdrZmwdA8xR8Z78Hn7J1i recursively

You can also publish the uploaded file for your local BTFS node to host:

User-MacBook-Pro:images user_home$ btfs name publish  QmdA3o9nFLwfF21GizuMK4xZpvdrZmwdA8xR8Z78Hn7J1i
Published to QmY4KyMSCuWVo4BXrDu9g44WErya8EmGMJ1sWKWjXkR3r4: /btfs/QmdA3o9nFLwfF21GizuMK4xZpvdrZmwdA8xR8Z78Hn7J1i

Check your local BTFS node's peer ID to see which file is hosted:

User-MacBook-Pro:images user_home$ btfs name resolve QmY4KyMSCuWVo4BXrDu9g44WErya8EmGMJ1sWKWjXkR3r4

View your hosted file through the gateway at<PeerID>.

Domain Binding

Domain binding allows you to display the hosted file path as a standard URL domain rather than the peer ID of your BTFS node. For example, assuming you own "", domain binding allows you to create a URL path like

To bind the domain, the domain DNS settings must be changed by adding a DNS TXT record of the form dnslink=/btfs/<peerID>.