How to Use IPFS With cURL

If you’re a developer then you likely have used cURL at one point or another or perhaps use it all the time. It’s a great terminal tool for making HTTP requests, whether it’s downloading a tool or making a post request. Just a few weeks ago cURL added support for IPFS, an exciting step for the future decentralized web! In this post we’ll show you how to use it, with both some basic techniques which can be on the slower side, and some advance techniques which can make cURL with IPFS fast.

The first thing you’ll need to do is make sure you have the latest version of cURL. This can sometimes be tricky because most computers might have cURL already installed and are not controlled by a package manager. You can find out what version you have by running curl —version to see what you currently have. IPFS support was added in version 8.4.0. If you’re not at that version you can learn how to update here.

Basic Usage

Most of what we’ll cover can be found on the IPFS page of the cURL documentation found here. The way the IPFS implementation works is that it looks for either a local IPFS node or a gateway environment variable in your exported paths, so we’ll get into what that could look like or ways you can customize it a bit. The following methods we would consider basic usage that will probably result in slower speeds, so just keep that in mind. In the next section we’ll go into faster and more advance methods.

The slower but perhaps simpler ways of using IPFS with cURL is to have a local IPFS node running on your computer. You can do this with either the IPFS Desktop app, or IPFS Kubo by running ipfs daemon in the terminal. While the node is running you can just run a command like the following:

curl ipfs://QmPyCYfL5oF79cfXjbt5cyr5hAZcyNrPNV9ytvUPdk8KT9

While this one is nice and simple to use, the speeds of a local IPFS node can be pretty slow and hard to setup for better efficiency.

Another way to use it is to pass in the IPFS gateway as a flag with --ipfs-gateway like so:

curl ipfs://QmPyCYfL5oF79cfXjbt5cyr5hAZcyNrPNV9ytvUPdk8KT9 --ipfs-gateway gateway.pinata.cloud

With this method we can curl the ipfs://QmPyCYfL5oF79cfXjbt5cyr5hAZcyNrPNV9ytvUPdk8KT9 url with the passed in gateway parameter gateway.pinata.cloud. You could use any public gateway that you like in that flag as long as its a valid IPFS gateway. The only downside is that you have to essentially keep typing in that flag along with your desired gateway.

A quick way to avoid all the retyping is to export the IPFS gateway as an environment variable on your computer. This will vary depending on what shell you are using and what kind of operating system you are running. The default for most unix systems would be bash, so you could run the following to export it to your path:

echo 'export IPFS_GATEWAY="gateway.pinata.cloud"' >> ~/.bashrc && source ~/.bashrc

This command will add a line to your .bashrc file with an export variable of the IPFS gateway of your choice and then source it. After doing this you can cURL without the gateway flag as cURL will identify that environment variable.

curl ipfs://QmPyCYfL5oF79cfXjbt5cyr5hAZcyNrPNV9ytvUPdk8KT9

All of these methods will get the job done, but if you’re trying to access larger files or content that is not as easy to fetch through a public gateway it can be less than ideal. Let’s show you how you can make IPFS with cURL even faster.

Advance Usage

While standard and public IPFS methods are slower, Pinata offers Dedicated Gateways on both free and paid plans! These are hooked up to a large network of IPFS nodes with 200 edge point caching, making them blazing fast. To use them with cURL there’s a few ways you can go about it.

If you are primarily going to just be accessing IPFS files already on your Pinata account, you can simply add your Dedicated Gateway url as an environment variable like we showed earlier:

echo 'export IPFS_GATEWAY="your-sub-domain.mypinata.cloud"' >> ~/.bashrc && source ~/.bashrc

If the CID you’re curling is from your own account it should go through with no problems at awesome speeds. Easy!

Now if you want to access content outside your Pinata account using your Dedicated Gateway, we can do so with Gateway Access Controls. Pinata created these to help keep Dedicated Gateways safe while also allowing them to access content all over IPFS, because without them your gateway could get hammered by anyone! With that said there’s two access controls we could utilize.

The first one would be IP address, which essentially puts any specified IP address on an “allowlist”. You can get your public IP address several different ways, then paste it into the Gateway Access Controls for your gateway.

Then you can just export your Dedicated Gateway domain as previously demonstrated. After that, you can just curl any IPFS cid in a flash!

curl ipfs://QmPyCYfL5oF79cfXjbt5cyr5hAZcyNrPNV9ytvUPdk8KT9

Another method is to use a Gateway Access Token  and use it as part of a header in the request. If you have the Dedicated Gateway domain already part of your environment variables then you can run a request like this:

curl ipfs://QmPyCYfL5oF79cfXjbt5cyr5hAZcyNrPNV9ytvUPdk8KT9 --header "x-pinata-gateway-token: YOUR_TOKEN"

The nice thing about using a Gateway Access Token is that you can make your gateway a bit more flexible and used in different places without designating an IP address, and there are several ways you could automate the request with tools like Raycast.

With all the different ways you can use cURL with IPFS you should certainly experiment to see what works best for your workflow, but we’re excited to see more and more developer tooling support IPFS as a protocol.

Happy Pinning!