The web3.storage JavaScript client provides a get method that allows you to retrieve any IPFS content using that content's content identifier (CID).

First, you'll need to create a web3.storage client using your API token. Getting an API token is free, but you'll need a free web3.storage account. If you already have an account and a token, read on. If not, have a look at the quickstart guide to get up and running in just a few minutes.

First you'll need to add the web3.storage package to your project's dependencies:

npm install web3.storage

Use the following code to create a web3.storage client:

import { Web3Storage } from 'web3.storage'

function getAccessToken () {
  // If you're just testing, you can paste in a token
  // and uncomment the following line:
  // return 'paste-your-token-here'

  // In a real app, it's better to read an access token from an
  // environement variable or other configuration that's kept outside of
  // your code base. For this to work, you need to set the
  // WEB3STORAGE_TOKEN environment variable before you run your code.
  return process.env.WEB3STORAGE_TOKEN
}

function makeStorageClient () {
  return new Web3Storage({ token: getAccessToken() })
}

Once you have a client, you can call client.get, passing in a CID string:

async function retrieve (cid) {
  const client = makeStorageClient()
  const res = await client.get(cid)
  console.log(`Got a response! [${res.status}] ${res.statusText}`)
  if (!res.ok) {
    throw new Error(`failed to get ${cid}`)
  }

  // request succeeded! do something with the response object here...
}

The Web3Response object

The get method returns a Web3Response object. This object extends the Response object from the Web Fetch API with two methods that provide access to the retrieved IPFS data: files and unixFsIterator().

The files method returns an array of Web3File objects, which represent all files contained in the content archive identified by the given CID. A Web3File is just like a regular Web File object, with the addition of path and cid properties. These contain the relative path of the file within the archive and the CID of the file, respectively.

Here's the example from above, now with the code to unpack and inspect the files in the response:

async function retrieveFiles (cid) {
  const client = makeStorageClient()
  const res = await client.get(cid)
  console.log(`Got a response! [${res.status}] ${res.statusText}`)
  if (!res.ok) {
    throw new Error(`failed to get ${cid} - [${res.status}] ${res.statusText}`)
  }

  // unpack File objects from the response
  const files = await res.files()
  for (const file of files) {
    console.log(`${file.cid} -- ${file.path} -- ${file.size}`)
  }
}

The Go client library's Client interface provides a Get method that accepts a context.Context and a Cid from the go-cid library.

The Get method returns a w3http.Web3Response, which is a standard http.Response with an additional Files method that provides access to the downloaded files.

First, import the client package and a few other things we'll be using:

import (
	"context"
	"fmt"
	"io/fs"

	cid "github.com/ipfs/go-cid"
	w3s "github.com/web3-storage/go-w3s-client"
)

Assuming you've already created a Client, you can use it to Get files by cid. The method below takes a CID string and converts it to a Cid type, which is what the Get method expects. You may not need this step if you're already using the Cid type in your code base.

func retrieveFiles(client w3s.Client, cidString string) (fs.File, fs.FS, error) {
	c, err := cid.Parse(cidString)
	if err != nil {
		return nil, nil, err
	}

	res, err := client.Get(context.Background(), c)
	if err != nil {
		return nil, nil, err
	}

	if res.StatusCode != 200 {
		return nil, nil,
			fmt.Errorf("request for %s was unsuccessful: [%d]: %s",
				cidString, res.StatusCode, res.Status)
	}

	// res is an http.Response with an extra method for reading IPFS UnixFS files
	return res.Files()
}

The Files method returns an fs.File that may be either a single file or a directory, depending on the CID that you requested. To distinguish, you can call Stat on the file and check the IsDir method of the returned fs.FileInfo. If it is a directory, you can type-cast to the fs.ReadDirFile interface and use ReadDirFile's ReadDir method to list the contents:

func listDirectory(f fs.File) error {
	// make sure the File is actually a directory that supports listing contents
	info, err := f.Stat()
	if err != nil {
		return err
	}

	d, ok := f.(fs.ReadDirFile)
	if !ok || !info.IsDir() {
		return fmt.Errorf("not a directory")
	}

	dirEntries, err := d.ReadDir(0)
	if err != nil {
		return err
	}

	// print the name of each file or directory inside.
	// note that this does not traverse nested directories.
	for _, entry := range dirEntries {
		fmt.Println(entry.Name())
	}
	return nil
}

Alternatively, you can use the second return value of the Files method, which is an fs.FS "file system" that represents all files included in the download. The fs.ReadDir function takes an fs.FS and the name of a directory to read, which can be "/" to read the root:

func listDirectoryUsingFilesystem(fsys fs.FS) error {
	entries, err := fs.ReadDir(fsys, "/")
	if err != nil {
		return err
	}
	for _, entry := range entries {
		fmt.Println(entry.Name())
	}
	return nil
}

The examples above only list the direct contents of a directory, without descending into nested subdirectories. You can pass the returned fs.FS to fs.WalkDir to walk the entire structure, including all nested folders:

func walkDirectory(fsys fs.FS) {
	// Walk whole directory contents (including nested directories)
	fs.WalkDir(fsys, "/", func(path string, d fs.DirEntry, err error) error {
		info, _ := d.Info()
		fmt.Printf("%s (%d bytes)\n", path, info.Size())
		return err
	})
}

1. Open a terminal window.

2. Use curl to download your file:

   curl https://<YOUR CID>.ipfs.w3s.link/<FILE NAME> -o ~/<OUTPUT FILE>
   

   Replace <YOUR CID>, <FILE NAME>, and <OUTPUT FILE> with their respective values.

   | Variable | Replace with | Example | | --- | --- | --- | | <YOUR CID> | The CID of the file you want to download. | bafybeie2bjap32zi2yqh5jmpve5njwulnkualcbiszvwfu36jzjyqskceq | | <FILE NAME> | The name of the file that you originally uploaded to web3.storage. | example.txt | | <OUTPUT FILE> | The path and filename that you want curl to save the file to. This can be different to <FILE NAME>. | Desktop/output-file.txt |

   Your complete command should look something like this:

   curl https://bafybeie2bjap32zi2yqh5jmpve5njwulnkualcbiszvwfu36jzjyqskceq.ipfs.w3s.link/example.txt -o ~/output-file.txt
   

1. Open a terminal window.

2. Use curl to download your file:

   curl https://<YOUR CID>.ipfs.w3s.link/<FILE NAME> -o ~/<OUTPUT FILE>
   

   Replace <YOUR CID>, <FILE NAME>, and <OUTPUT FILE> with their respective values.

   | Variable | Replace with | Example | | --------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | <YOUR CID> | The CID of the file you want to download. | bafybeie2bjap32zi2yqh5jmpve5njwulnkualcbiszvwfu36jzjyqskceq | | <FILE NAME> | The name of the file that you originally uploaded to web3.storage. | example.txt | | <OUTPUT FILE> | The path and filename that you want Powershell to save the file to. This can be different to <FILE NAME>. | Desktop/output-file.txt |

   Your complete command should look something like this:

   curl https://bafybeie2bjap32zi2yqh5jmpve5njwulnkualcbiszvwfu36jzjyqskceq.ipfs.w3s.link/example.txt -o ~/output-file.txt
   

1. Open a Powershell window.

2. Use Invoke-WebRequest to download your file:

    Invoke-WebRequest -Uri "https://<YOUR_CID>.ipfs.w3s.link/<FILE NAME>" -OutFile "C:\Users\<USERNAME>\<OUTPUT FILE>
   

   Replace <YOUR CID>, <FILE NAME>, <USERNAME>, and <OUTPUT FILE> with their respective values.

   Variable	Replace with	Example
   <YOUR CID>	The CID of the file you want to download.	bafybeie2bjap32zi2yqh5jmpve5njwulnkualcbiszvwfu36jzjyqskceq
   <FILE NAME>	The name of the file that you originally uploaded to web3.storage.	example.txt
   <USERNAME>	The username you use to log into Windows with.	Laika
   <OUTPUT FILE>	The path and filename that you want Powershell to save the file to. This can be different to <FILE NAME>.	Desktop/output-file.txt

   Your complete command should look something like this:

   Invoke-WebRequest -Uri "https://bafybeie2bjap32zi2yqh5jmpve5njwulnkualcbiszvwfu36jzjyqskceq.ipfs.w3s.link/example.txt" -OutFile "C:\Users\Laika\Desktop\output-file.txt"