Common Use Cases

Uploading a single file

Uploading a folder (recursive)

Publishing to BitTorrent Name System (BTNS)

BTFS uses content-based addressing; it creates an address of a file based on data contained within the file. If you were to share an BTFS address such as /btfs/QmbezGequPwcsWo8UL4wDF6a8hYwM1hmbzYv2mnKkEWaUp with someone, you would need to give the person a new link every time you update the content.

The BitTorrent Name System (BTNS) solves this issue by creating an address that can be updated.

A name in BTNS is the hash of a public key. It is associated with a record containing information about the hash it links to that is signed by the corresponding private key. New records can be signed and published at any time.

When looking up an BTNS address, use the /btns/ prefix:

/btns/QmSrPmbaUKA3ZodhzPWZnpFgcPMFWF4QsxXbkWfEptTBJd

Example BTNS Setup with CLI

  1. Start your BTFS daemon, if it isn't already running:
btfs daemon
  1. Open another command line window and create the file that you want to set up with BTFS. For the tutorial, we're just going to create a simple hello world file:
echo "Hello BTFS" > hello.txt
  1. Add your file to BTFS:
btfs add hello.txt

> added QmUVTKsrYJpaxUT7dr9FpKq6AoKHhEM7eG1ZHGL56haKLG hello.txt
> 11 B / 11 B [=====================================================] 100.00%

Take note of the CID output by BTFS.

  1. Use cat and the CID you just got from BTFS to view the file again:
btfs cat QmUVTKsrYJpaxUT7dr9FpKq6AoKHhEM7eG1ZHGL56haKLG

> Hello BTFS
  1. Publish your CID to BTNS:
btfs name publish /btfs/QmUVTKsrYJpaxUT7dr9FpKq6AoKHhEM7eG1ZHGL56haKLG

> Published to k51qzi5uqu5dkkciu33khkzbcmxtyhn376i1e83tya8kuy7z9euedzyr5nhoew: /btfs/QmUVTKsrYJpaxUT7dr9FpKq6AoKHhEM7eG1ZHGL56haKLG

k51... is the public key or BTNS name of the BTNS you are running. You can now change the file repeatedly, and, even though the CID changes when you change the file, you can continue to access it with this key.

You can view your file by going to BTFS Gateway

curl https://gateway.btfs.io/btns/k51qzi5uqu5dkkciu33khkzbcmxtyhn376i1e83tya8kuy7z9euedzyr5nhoew

> Hello BTFS

Make a change to your file, add it to BTFS, and update your BTNS:

echo "Hello again BTFS" > hello.txt

btfs add hello.txt

> added QmaVfeg2GM17RLjBs9C4fhpku6uDgrEGUYCTC183VrZaVW hello.txt
> 17 B / 17 B [=====================================================] 100.00%

btfs name publish QmaVfeg2GM17RLjBs9C4fhpku6uDgrEGUYCTC183VrZaVW

> Published to k51qzi5uqu5dkkciu33khkzbcmxtyhn376i1e83tya8kuy7z9euedzyr5nhoew: /btfs/QmaVfeg2GM17RLjBs9C4fhpku6uDgrEGUYCTC183VrZaVW

You can now go back to BTFS Gateway to view your updated file using the same address:

curl https://gateway.btfs.io/btns/k51qzi5uqu5dkkciu33khkzbcmxtyhn376i1e83tya8kuy7z9euedzyr5nhoew

> Hello again BTFS

You can view the CID of the file associated with your k5 key by using name resolve:

btfs name resolve

> /btfs/QmaVfeg2GM17RLjBs9C4fhpku6uDgrEGUYCTC183VrZaVW

To use a different k5 key, first create one using key gen test, and use the --key flag when calling name publish:

btfs key gen SecondKey

> k51qzi5uqu5dh5kbbff1ucw3ksphpy3vxx4en4dbtfh90pvw4mzd8nfm5r5fnl

btfs name publish --key=SecondKey /btfs/QmaVfeg2GM17RLjBs9C4fhpku6uDgrEGUYCTC183VrZaVW

> Published to k51qzi5uqu5dh5kbbff1ucw3ksphpy3vxx4en4dbtfh90pvw4mzd8nfm5r5fnl: /btfs/QmaVfeg2GM17RLjBs9C4fhpku6uDgrEGUYCTC183VrZaVW