IPFS Docs

# Basic CLI operations with Kubo

This short guide aims to walk you through the basics of using IPFS with the Kubo CLI. Kubo is one of multiple IPFS implementations. It is the oldest IPFS implementation and exposes a CLI (among other things).

You will learn how to add, retrieve, read, and remove files within the CLI. If you are unsure about the meaning of some terms, you can check out the glossary.

All instructions and examples shown here were performed and tested on an M1 Mac. However, the IPFS commands are the same on Linux, macOS, and Windows. You will need to know how to navigate your computer's directories from within the CLI. If you're unsure how to use the CLI, we recommend learning how before continuing with this guide.

# Install Kubo

Next up, we need to install Kubo for the command-line. We have a great guide that will walk you through how to install Kubo with the CLI.

Once you have Kubo installed, we need to get our node up and running. If this is your first time using Kubo, you will first need to initialize the configuration files:

ipfs init

This will output something like:

initializing ipfs node at /Users/<user>/.ipfs
generating 2048-bit RSA keypair...done
peer identity: Qm...
to get started, enter:

  ipfs cat /ipfs/QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG/readme

We're now ready to start the IPFS daemon to bring the node online. Run the ipfs daemon command:

ipfs daemon

This will output something like:

Initializing daemon...
Kubo version: 0.12.0
Repo version: 12
System version: arm64/darwin
[...]
Daemon is ready

This command will stay running until you tell it to stop; don't do this yet! Simply open up a new instance of the CLI and continue with the guide!

WARNING

Do not close the CLI that you used to initialize your daemon. Only terminate the daemon when you want to take your IPFS node offline.

# Add files

Now that we have our Kubo IPFS node up and running, we're ready to add files to IPFS.

  1. Within the CLI, navigate to the directory containing the file or folder you wish to share. In this example, we will navigate to the ~/Documents directory:

    cd ~/Documents

  2. Once in there, list the contents of the directory to make sure we're in the right place:

    ls

    This will output the contents of this folder:

    hello-ipfs.txt

  3. Next up, we'll use the ipfs add command to add a file to IPFS. Be sure to add the file extension to the end of the file name:

    ipfs add hello-ipfs.txt

    This will output something like:

    added QmRgR7Bpa9xDMUNGiKaARvFL9MmnoFyd86rF817EZyfdGE hello-ipfs.txt
6 B / 6 B [==========================================================] 100.00

We've now added a file to IPFS, and it's ready to be shared with peers on the network!

# Retrieve a file

In the previous section, we went through how to add local files to IPFS. We're going to cover how to retrieve remote files from IPFS and save them to your computer. For this example, we will retrieve a folder containing a single text file.

  1. Within the CLI, navigate to the directory where you wish to save the folder. IPFS will save the folder to whichever directory you are in. In this case, we're going to save the folder in the ~/Documents directory:

    cd ~/Documents

  2. To get content over IPFS, we need to tell the ipfs daemon which CID we want. In this case, we want bafybeif2ewg3nqa33mjokpxii36jj2ywfqjpy3urdh7v6vqyfjoocvgy3a.

  3. Use the command ipfs get, combined with the CID we want, to retrieve the folder:

    ipfs get bafybeif2ewg3nqa33mjokpxii36jj2ywfqjpy3urdh7v6vqyfjoocvgy3a

    This will output something like:

    Saving file(s) to bafybeif2ewg3nqa33mjokpxii36jj2ywfqjpy3urdh7v6vqyfjoocvgy3a
1.76 KiB / 1.76 KiB [==============================================] 100.00% 0s

    It may take a few moments for your IPFS node to find the data we're looking for.

We've now retrieved the folder over IPFS, and a copy of it has been saved to your computer's local storage! You are also now hosting the folder and its contents for others to retrieve.

# View a file

You can view the contents of a file from within the CLI using the command ipfs cat. We're going to use this command to view the contents of the folder we just retrieved, but you can also use ipfs cat on files you don't already have locally.

ipfs cat bafybeif2ewg3nqa33mjokpxii36jj2ywfqjpy3urdh7v6vqyfjoocvgy3a

This will output something like:

Error: this dag node is a directory

Attempting to run ipfs cat on the CID from above returns an error! The CID points to the directory, not the file. To view the directory contents, we will run ipfs refs <CID>.

ipfs refs bafybeif2ewg3nqa33mjokpxii36jj2ywfqjpy3urdh7v6vqyfjoocvgy3a

This will output something like:

bafkreig24ijzqxj3cxdp6yh6ia2ysxzvxsfnd6rzahxxjv6ofcuix52wtq

The ref command returns the CID that points to the file within the directory. Now we can use ipfs cat with this new CID to view it:

ipfs cat bafkreig24ijzqxj3cxdp6yh6ia2ysxzvxsfnd6rzahxxjv6ofcuix52wtq

This will output something like:

MMMMMMMMMMN0xo;';ox0NMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM
MMMMMMWXOdoloxkkkxolodOXWMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM
MMMN0xdoodkOOOOOOOOOkdoodx0NMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM
MKo;;oxOOOOOOOOOOOOOOOOOxo;;oKMMMMMXOKMMMN0kkkkkO0NWMMXOkkkkkkOXMMWKkddddk0NMMMM
Wd...':okOOOOOOOOOOOOOko:'...dWMMMWd.lWMM0,.;ccc:;,oXWd.'clllco0WO:,:loolcckWMMM
Wdckdc,..;lxOOOOOOOxl;..';lo;dWMMMWo.lWMM0''0MMMWK:.oNo.lWMMMMMMX:.dWMMMMMWWMMMM
WdcOKK0ko;'.,:c:c:,..,:oxxxd;dWMMMWo.lWMM0''0MMMMNc.oNo.lNWWWWWMNl.;x0XNWMMMMMMM
WdcOKKKKKKOd:.   .,cdxxxxxxd;dWMMMWo.lWMM0'.coool;'cKWo..clllldXMNkl:;;;:lxXMMMM
WdcOKKKKKKKK0l. .:dxxxxxxxxd;dWMMMWo.lWMM0'.cooodkKWMWo.:0K000KWMMMMWNK0xc.,0MMM
WdcOKKKKKKKKK0: ,dxxxxxxxxxd:dWMMMWo.lWMM0''0MMMMMMMMWo.lWMMMMMMMMMMMMMMMX:.dWMM
Wd;xKKKKKKKKK0: ,dxxxxxxxxxl,dWMMMWo.lWMM0''0MMMMMMMMWo.lWMMMMMMWOdk0KXXKd.,0MMM
Mk',d0KKKKKKK0: ,dxxxxxxxdc.'kMMMMMO:xWMMKllXMMMMMMMMWk:kWMMMMMMWOlcccccccdKWMMM
MWKkdooxOKKKK0: ,dxxxxdlclokKWMMMMMWWWMMMMWWMMMMMMMMMMMWMMMMMMMMMMMWWNNNNWMMMMMM
MMMMWNOxdodk00: ,ddoccldONWMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM
MMMMMMMMWKkdol' .:lokKWMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM
MMMMMMMMMMMWKd'.'dKWMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM

It is important to note that ipfs cat only works with plaintext files. As demonstrated above, attempting to cat a directory will return an error. If you attempt to cat an image file or a text file that is not plaintext, your terminal will be filled with unreadable lines.

# Pin a file

We can pin data we want to save to our IPFS node to ensure we don't lose this data.

  1. Use the ipfs pin add command:

    ipfs pin add bafybeif2ewg3nqa33mjokpxii36jj2ywfqjpy3urdh7v6vqyfjoocvgy3a

    This will output something like:

    pinned bafybeif2ewg3nqa33mjokpxii36jj2ywfqjpy3urdh7v6vqyfjoocvgy3a recursively

By default, objects that you retrieve over IPFS are not pinned to your node. If you wish to prevent the files from being garbage collected, you need to pin them. You will notice that the pin you just added is a recursive pin, meaning it is a directory containing other objects. Check out the Pinning page to learn more about how this works.

# Remove a file

If we decide that we no longer want to host a file, all we have to do is remove the pin.

  1. First, we need to grab the CID of the file or folder we want to unpin. To view a list of the content you have pinned, run ipfs pin ls:

    ipfs pin ls

    This will output something like:

    QmPZ9gcCEpqKTo6aq61g2nXGUhM4iCL3ewB6LDXZCtioEB indirect
QmQGiYLVAdSHJQKYFRTJZMG4BXBHqKperaZtyKGmCRLmsF indirect
QmU5k7ter3RdjZXu3sHghsga1UQtrztnQxmTL22nPnsu3g indirect
QmUNLLsPACCz1vLxQVkXqqLX5R1X345qqfHbsf67hvA3Nn recursive
QmYCvbfNbCwFR45HiNP45rwJgvatpiW38D961L5qAhUM5Y indirect
QmejvEPop4D7YUadeGqYWmZxHhLc4JBUCzJJHWMzdcMe2y indirect
QmQ5vhrL7uv6tuoN9KeVBwd4PwfQkXdVVmDLUZuTNxqgvm indirect
QmQPeNsJPyVWPFDVHb77w8G42Fvo15z4bG2X8D2GhfbSXc recursive
QmQy6xmJhrcC5QLboAcGFcAE1tC8CrwDVkrHdEYJkLscrQ indirect

  2. If you know exactly which CID you want to remove, then great! However, if you're unsure which CID is, you can use the ipfs add command again on the file or folder you want to remove to find out. We're going to unpin the hello-ipfs.txt file we used earlier.

    cd ~/Documents
ipfs add hello-ipfs.txt

    This will output something like:

    added QmRgR7Bpa9xDMUNGiKaARvFL9MmnoFyd86rF817EZyfdGE hello-ipfs.txt
6 B / 6 B [==========================================================] 100.00

    Even though IPFS is just giving us the same output as before, we're not actually re-adding the file. We can grab the CID from this output, though.

  3. Now, we can use the ipfs pin rm command to unpin the file:

    ipfs pin rm QmRgR7Bpa9xDMUNGiKaARvFL9MmnoFyd86rF817EZyfdGE

    This will output something like:

    unpinned QmRgR7Bpa9xDMUNGiKaARvFL9MmnoFyd86rF817EZyfdGE

  4. The hello-ipfs.txt file is now unpinned, but it has not been removed from our node completely. To remove it completely, we need to run the garbage collection. The command will remove everything from your node that does not have a pin:

    ipfs repo gc

    This will output something like:

    removed bafybeif2ewg3nqa33mjokpxii36jj2ywfqjpy3urdh7v6vqyfjoocvgy3a
removed bafkreieceevgg2auxo4u3rjgeiqfr4ccxh6ylkgxt2ss6k2leuad5xckxe
removed bafkreiblcvcr7letdbp2k2thkbjyunznrwq3y6pyoylzaq4epawqcca2my
[...]

The target file has now been fully removed from your IPFS node and any other files that we did not pin. If the content that was just garbage collected was saved to your computer's local storage, it is still there. If you wish to remove the content from your computer's local storage, you will need to find where it is saved and delete it using the normal deletion method.

Help us improve this site!

Last Updated: 2/10/2023, 1:07:04 AM