Pinata has always been dedicated to provide the developers the best experience possible when using IPFS. It started with our APIs, which are simple and can be used anywhere, but we took it a step further with our SDK. Finally, we have one more tool for your machine: the Pinata IPFS CLI. This CLI built in Go is the ultimate terminal companion while using Pinata, and can be really handy for managing files on Public or Private IPFS, as well as uploading larger pieces of content. In this guide, we’ll show you how to install it and how to start using it right away!

Installation

The Pinata IPFS CLI can be installed multiple ways, so if you have some preferences for that sort of thing, then check out the docs here. The easiest way to install it is to copy and paste the install script below:

curl -fsSL https://cli.pinata.cloud/install | bash

Once it’s finished installing, try running this command to make sure it worked:

pinata

If successful, then you should see the following:

NAME:
   pinata - The official Pinata IPFS CLI! To get started make an API key at https://app.pinata.cloud/keys, then authorize the CLI with the auth command with your JWT

USAGE:
   pinata [global options] command [command options] [arguments...]

COMMANDS:
   auth, a       Authorize the CLI with your Pinata JWT
   upload, u     Upload a file to Pinata
   groups, g     Interact with file groups
   files, f      Interact with your files on Pinata
   swaps, s      Interact and manage hot swaps on Pinata
   gateways, gw  Interact with your gateways on Pinata
   keys, k       Create and manage generated API keys
   config, cfg   Configure Pinata CLI settings
   help, h       Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --help, -h  show help

Sweet! Now all we need to do is authorize the CLI with our API Key. If you haven’t already, visit the API Keys Page and create a new API key in the top right. We would recommend selecting admin permissions for the CLI so you can manage everything in one spot. Once you have the longer JWT stored somewhere safe, run the following command in the terminal.

pinata auth

This will prompt you to paste in your API key. From there, it will test it to make sure it’s valid, and then it will ask which Dedicated Gateway you would like to use. Once complete, it will save that information to your dot files!

Before we go into some specifics, I think it would be helpful to provide some basic CLI instructions and tips to make your life easier. First thing you should know is that you can always pass --help with any command to learn how it works. If you remember, just a moment ago we ran pinata and it gave us some different commands that were available. Let’s say we want to learn more about the upload command; we would run the following:

pinata files --help

That will print out the following:

NAME:
   pinata files - Interact with your files on Pinata

USAGE:
   pinata files command [command options] [arguments...]

COMMANDS:
   delete, d  Delete a file by ID
   get, g     Get file info by ID
   update, u  Update a file by ID
   list, l    List most recent files
   help, h    Shows a list of commands or help for one command

OPTIONS:
   --help, -h  show help

So it looks like there are multiple commands under files such as get, list, update, etc. Let’s learn more about delete by running the following:

pinata files delete --help

This will return the following help guide:

NAME:
   pinata files delete - Delete a file by ID

USAGE:
   pinata files delete [command options] [ID of file]

OPTIONS:
   --network value, --net value  Specify the network (public or private). Uses default if not specified
   --help, -h                    show help

If we read the instructions here, then we learn we can run pinata files delete <FILE_ID> to delete the target file ID, but we can also pass pinata files delete --network private <FILE_ID> to make sure we tell the CLI that this file is on Private IPFS. By following this pattern, you can really learn the entire thing without leaving the terminal! But don’t worry, we’ll still show you the basics now.

Uploading Files

Let’s start our CLI journey by uploading a simple text file. Let’s run both of these commands one at a time:

echo "Hello World from the Pinata IPFS CLI!" > hello.txt

pinata upload hello.txt

Here we simply saved some text to a txt file, then uploaded it to IPFS using Pinata; easy! It should return a JSON body like this:

{
    "id": "0195aab1-8803-767d-be77-8692910390f5",
    "name": "hello.txt",
    "cid": "bafkreia5kssd5gmk6dc7dp2ehrombpohgbwavlkinpdvmwimoo52rezdje",
    "size": 37,
    "created_at": "2025-03-18T19:18:36.824Z",
    "number_of_files": 1,
    "mime_type": "text/plain",
    "group_id": null,
    "keyvalues": null,
    "vectorized": false,
    "network": "public"
}

This is helpful for other commands we’ll go over shortly, but before we leave uploads, here’s a few other tricks. The upload command includes several flags that we can use to do things like give the file a custom name, add it to a group, or even see a progress loader:

pinata upload --name cli-hello-file --verbose hello.txt

Listing and Managing Files

We uploaded our first file, now let’s say we want to retrieve that information about it once again. To do this we can use the files list command to see not only this file but any file we want to find.

pinata files list

This will spit out a result of the last 10 files uploaded to our account, but we can query for specific files too using the flags. This one will get info for a specific CID:

pinata files list --cid bafkreia5kssd5gmk6dc7dp2ehrombpohgbwavlkinpdvmwimoo52rezdje

We could also query by name:

pinata files list --name hello.txt

Or we can search for files in a Group or for a given keyvalue!

pinata files list --group <GROUP_ID>

pinata files list --keyvalues env=prod

Again, there’s a lot of possibilities here, so be sure to use --help to learn everything there is!

On top of listing files, you can also delete files by ID:

pinata files delete <FILE_ID>

Or update an existing file:

pinata files update --name hello-from-cli <FILE_ID>

Perhaps one of the more under utilized is Pinata Groups where you can create groups and add files to groups!

pinata groups create my-group

pinata groups list 

pinata groups add <GROUP_ID> <FILE_ID>

There really is so much more so be sure to check out the docs!

Retrieving Files

Once you have files on IPFS, it’s natural that you’ll want to retrieve them, and the CLI provides some cool ways you can do that with the gateways command! Let’s go back to that file we uploaded earlier, which should have the CID bafkreia5kssd5gmk6dc7dp2ehrombpohgbwavlkinpdvmwimoo52rezdje. We can create a link for that file CID by using the following:

pinata gateways link bafkreia5kssd5gmk6dc7dp2ehrombpohgbwavlkinpdvmwimoo52rezdje

This will return something like this:

https://dweb.mypinata.cloud/ipfs/bafkreia5kssd5gmk6dc7dp2ehrombpohgbwavlkinpdvmwimoo52rezdje

Want to test it? We can use a command like xargs to pass the result into curl and fetch the data!

pinata gateways link bafkreia5kssd5gmk6dc7dp2ehrombpohgbwavlkinpdvmwimoo52rezdje | xargs curl

Hello World from the Pinata IPFS CLI!

Let’s go a little crazy and test Private IPFS, where you can only access content through a time sensitive link. First let’s create a new file and upload it to Private IPFS:

echo "A secret hello" > secret.txt

pinata upload --network private secret.txt

Now let’s grab the CID and create a link to access it, once again passing the network flag.

pinata gateways link --network private bafkreifwlnaa3io5injioohkrkt2zercoztswlr3bgxlcyt6mipeibd7ui

You should get an access link where you can view the file, but after thirty seconds it will no longer work! Wrapping it up, let’s do one more cool trick. Try using this command:

pinata gateways open bafkreia5kssd5gmk6dc7dp2ehrombpohgbwavlkinpdvmwimoo52rezdje | xargs curl

Surprise! Just opened it in your browser :) Pretty handy when you’re testing stuff out or just want to quickly access a file.

Wrapping Up

Despite the length of this post, we barely scratched the surface of what is capable of the Pinata CLI. With that said, we would highly recommend exploring the documentation below and seeing some of the other goodies we have inside.

IPFS CLI - Pinata Docs

The official CLI for Pinata written in Go

Pinata Docs

For decades, CLIs have been essential productivity tools for developers and it’s still the same case today. Many developers even have full end to end workflows in the terminal with tools like Neovim and Tmux. We’re not saying you should go that far (even though I think it’s worth a shot 😉), but we are saying that the Pinata CLI should be a well explored piece in your IPFS and blockchain tool belt.

Happy Pinning!