IPFS Docs

# Pin a file with IPFS using the command line

Similar to the Pin a file with IPFS quickstart, this guide will teach you about pinning services and how to use them to publish content-addressed data with IPFS. However, instead of using a web UI, you will upload files using command-line tools and APIs provided by various pinning services. By the end of this guide, you should have a better understanding of how content addressing and CIDs work from a high level, as well as how to use CLI tools to publish data to IPFS.

If you prefer a graphical interface, see Pin with browser interfaces.

# Contents

# Overview

Pinning refers to the process of ensuring that a particular piece of content is retrievable with IPFS. In other words, pinning is equivalent to storing a file on a computer or server that is connected to the internet, thereby making it available to the rest of the IPFS network.

Pinning can be done at various levels, from individual files to entire directories that are addressed by a CID. You can also pin CIDs to multiple IPFS nodes to increase the redundancy and resilience of the file on the network.

# Pinning services

Pinning services are similar to hosting services, in that they run an IPFS node for you and ensure that your files are available to the IPFS network.

Data pinned to the IPFS network is public by default and retrievable by anyone. Avoid publishing private data or adequately encrypt it before publishing.

# Self-hosting option

You can run your own IPFS node using Kubo to pin files locally:

  • Full control: Run ipfs daemon to start your node and use ipfs pin commands to manage pinned content
  • Combine with pinning services: Use both local pinning, and remote services for redundancy - your data stays available even if your node goes offline
  • Learn more: See the Kubo quickstart and pinning files guide for detailed instructions

Running your own node gives you complete control over your data while participating in the IPFS network.

# Prerequisites

image

# Upload and pin a file

Choose one of the following methods based on your setup:

# Using Kubo (self-hosted)

If you're running your own Kubo node, use the ipfs add and ipfs pin commands. See the pinning files guide for detailed instructions and the working with remote pinning services guide to configure remote pinning.

# Option 1: Storacha CLI

Storacha provides a command-line interface through their storacha tool. For detailed installation and usage instructions, see their CLI documentation (opens new window).

Basic usage:

# Install the CLI (requires Node.js)
npm install -g @storacha/cli

# Authenticate
storacha login your@email.com

# Create a space for your files
storacha space create MySpace

# Upload a file
storacha up welcome-to-IPFS.jpg

# Option 2: Pinata API

Pinata provides a REST API that you can use with curl or any HTTP client. See their API documentation (opens new window) for authentication setup.

Basic usage with curl:

# Set your API credentials
export PINATA_API_KEY="your_api_key"
export PINATA_SECRET_API_KEY="your_secret_key"

# Upload a file
curl -X POST https://api.pinata.cloud/pinning/pinFileToIPFS \
  -H "pinata_api_key: $PINATA_API_KEY" \
  -H "pinata_secret_api_key: $PINATA_SECRET_API_KEY" \
  -F "file=@welcome-to-IPFS.jpg"

# Option 3: Filebase S3-Compatible API and Kubo RPC

Filebase offers an S3-compatible API, making it easy to use with AWS CLI or any S3 SDK. See their S3-compatible API documentation (opens new window) and developer quick start guide (opens new window). They also offer a subset of Kubo RPC API - see their IPFS RPC API documentation (opens new window).

Basic usage with AWS CLI:

# Configure AWS CLI with Filebase credentials
aws configure --profile filebase

# Upload a file to your IPFS bucket
aws --profile filebase s3 cp welcome-to-IPFS.jpg s3://your-bucket-name/

Each method will return a CID (Content Identifier) for your uploaded file. Save this CID as you'll use it to retrieve your file.

# CIDs explained

In IPFS, every file and directory is identified with a Content Identifier (CID). The CID serves as the permanent address of the file and can be used by anyone to find it on the IPFS network.

When a file is first added to an IPFS node (like the image used in this guide), it's first transformed into a content-addressable representation in which the file is split into smaller chunks (if above ~1MB) which are linked together and hashed to produce the CID.

For example, a CID might look like:

bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4

You can now share the CID with anyone and they can fetch the file using IPFS.

To dive deeper into the anatomy of the CID, check out the CID inspector (opens new window).

The transformation into a content-addressable representation is a local operation that doesn't require any network connectivity. Many CLI tools perform this transformation locally before uploading.

# Retrieving with a gateway

Now that your file is pinned to a pinning service, you can fetch it using an IPFS gateway. An IPFS Gateway is an HTTP interface that serves as a bridge to the IPFS network.

You can retrieve your content using curl or a web browser:

# Using service-specific gateways

Storacha Gateway:

curl https://[CID].ipfs.w3s.link/
# or
curl https://w3s.link/ipfs/[CID]

Pinata Gateway:

curl https://gateway.pinata.cloud/ipfs/[CID]

Filebase Gateway:

curl https://[BUCKET_NAME].ipfs.filebase.io/ipfs/[CID]

# Using public gateways

curl https://ipfs.io/ipfs/[CID]
# or
curl https://dweb.link/ipfs/[CID]

When pinning a file to IPFS, the filename is not stored by default. To ensure the filename is retained, it's common to wrap the file in a directory. In such instances, both the file and the directory will have unique CIDs.

# Summary and next steps

In this quickstart guide, you learned about pinning services, and how to use them to publish content-addressed data with IPFS using command-line tools. You explored different CLI options for Storacha, Pinata, and Filebase.

Pinning services provide a convenient alternative to running IPFS nodes and infrastructure. However, the two are not mutually exclusive; you can combine a pinning service with an IPFS node on your computer to increase the resilience of your CIDs.

Possible next steps include:

Help us improve this site!