Getting Started

This guide walks you through pinning your first file to Filecoin using the Filecoin Pin CLI. By the end, you'll be set up to:

• ✅ Install the Filecoin Pin CLI
• ✅ Connect your Ethereum-style wallet on Filecoin
• ✅ Deposit storage credit on Filecoin Pay
• ✅ Pin a file to Filecoin and retrieve it using standard IPFS tooling

🚀 Prerequisites

Before starting, make sure you have:

• An Ethereum-style wallet on Filecoin - MetaMask is the easiest option. If you don't have one set up, see Wallets and Metamask setup.
• FIL in your wallet - to pay transaction gas fees on Filecoin.
• USDFC in your wallet - to pay for storage. USDFC is the stablecoin used by Filecoin Onchain Cloud. The easiest way to get some is to swap FIL for USDFC on Sushi.
• Node.js 24 or later - the Filecoin Pin CLI runs on Node.js. Install from nodejs.org or via your package manager.

📦 Install the Filecoin Pin CLI

Install the CLI globally with npm:

npm install -g filecoin-pin

Verify the installation:

filecoin-pin --version

To see all available commands at any time:

filecoin-pin --help

🔐 Connect your wallet

The Filecoin Pin CLI signs transactions using your wallet's private key. You provide it as an environment variable - the CLI reads it directly and never stores it on disk.

1️⃣ Export your private key from MetaMask

In MetaMask:

1. Open the MetaMask extension.
2. Click the three dots next to your account name.
3. Select Account details.
4. Click Show private key.
5. Enter your MetaMask password.
6. Copy the private key shown.

The private key is a 64-character hex string, with or without an 0x prefix.

2️⃣ Save the private key to a .env file

Create a file named .env in your working directory containing:

export PRIVATE_KEY="0xYOUR_PRIVATE_KEY_HERE"

Then secure it and load it into your shell:

chmod 600 .env
source .env

Add .env to your .gitignore if you're inside a git repository.

💰 Set up payments

Filecoin Pin uses Filecoin Pay to manage storage payments. Before you can pin anything, you need to:

1. Authorise the Warm Storage Service contract to spend USDFC on your behalf.
2. Deposit USDFC into Filecoin Pay so storage providers can be paid.

The CLI walks you through both steps interactively.

filecoin-pin payments setup

The CLI will guide you through the following stages:

1️⃣ Connect and check balances

The CLI confirms it can connect to Filecoin Mainnet and reports your wallet's FIL and USDFC balances.

2️⃣ Review pricing

The CLI shows current storage pricing per GiB per month and per TiB per month. Use this to estimate how much USDFC you want to deposit.

3️⃣ Choose a deposit amount

The CLI asks: "Would you like to deposit USDFC to enable storage?" Answer Yes.

It then shows example monthly costs for common storage amounts (100 GiB, 1 TiB, 10 TiB) so you can pick a sensible deposit.

When prompted "How much USDFC would you like to deposit?", enter the amount you want. A first-time deposit of 10.0 USDFC is a reasonable starting point.

4️⃣ Confirm the deposit

The CLI submits the deposit transaction onchain and shows the transaction hash and your new storage capacity.

✓ Deposit complete
  Deposit tx: 0x1234...abcd

New Storage Capacity:
  Total deposit: 10.00 USDFC
  Capacity: ~XX GiB for 1 month

💵 Top up your runway (optional)

If you want to ensure your deposit covers a specific number of days at your current storage usage, run:

filecoin-pin payments fund --days 30

This deposits (or withdraws) the right amount of USDFC to give you exactly 30 days of runway based on what you're currently storing. You can use any number of days you like.

To check your current deposit balance, runway, and payment status at any time:

filecoin-pin payments status

📌 Pin your first file

Now you're ready to pin. Create a test file:

echo "Hello Filecoin Pin @ $(date)!" > demo.txt

Pin it to Filecoin:

filecoin-pin add demo.txt

The CLI will:

1. Pack your file into IPFS-compatible format (a CAR file).
2. Select storage providers automatically.
3. Store your file with two providers for redundancy.
4. Verify the upload was advertised to IPNI indexers.

✓ File validated (20 B)
✓ Connected to Filecoin Mainnet
✓ File packed with root CID: bafybeihkoviema7g3gxyt6la7vd5ho32ictqbilu3wnlo3rs7ewhnp7lly
✓ IPFS content loaded (96 B)

━━━ Add Complete ━━━

Root CID:  bafybeihkoviema7g3gxyt6la7vd5ho32ictqbilu3wnlo3rs7ewhnp7lly
Piece CID: bafkzcibcfab4grpgq6e6rva4kfuxfcvibdzx3kn2jdw6q3zqgwt5cou7j6k4wfq
Copies:    2/2

Add completed successfully

The Root CID is your IPFS Content Identifier - it's how you'll retrieve your data. Save it somewhere.

You can also pin a directory by passing the directory path instead of a file:

mkdir my-data
echo "File 1" > my-data/file1.txt
echo "File 2" > my-data/file2.txt
filecoin-pin add my-data/

🌐 Retrieve your file

Your file is now retrievable via standard IPFS tooling using its Root CID. For example:

https://<YOUR_ROOT_CID>.ipfs.inbrowser.link

Or via the dweb.link gateway:

https://dweb.link/ipfs/<YOUR_ROOT_CID>

Try opening one of those URLs in your browser - your file should load.

You can also retrieve it programmatically using any IPFS-compatible client (Kubo, Helia, Lassie, etc.) by referencing the Root CID.

🛡️ Inspect your storage proofs

Filecoin storage providers must cryptographically prove daily that they continue to store your data. You can inspect those proofs and the on-chain payment rails at any time.

List the data sets associated with your wallet:

filecoin-pin data-set --ls

Then get the full on-chain detail for a specific data set:

filecoin-pin data-set <DATASET_ID>

This queries the smart contracts directly, so the values are live blockchain state.

Data Set #279 • live
  Managed by Warm Storage: yes
  Pieces stored: 2
  Total size: 672.0 B
  PDP rail ID: 631
  Payer: 0xYOUR_WALLET_ADDRESS
  Payee: 0xPROVIDER_ADDRESS

Provider
  Provider: <provider-name> (ID <N>)

Provider Service
  Service URL: https://<provider-service-url>
  Min proving period: 30 epochs

Pieces
  #0
    CommP: bafkzcib...
    Root CID: bafybei...

Key things to look for:

• Status: live - your data set is active and being proved.
• PDP rail ID - your active storage-proof payment rail.
• Min proving period - how often the provider must submit a fresh proof.
• Provider Service URL - direct retrieval endpoint for your pieces.
• CommP / Root CID per piece - the piece CID is what the provider proves; the Root CID is what you use to retrieve.

🎉 You're Done!

You've successfully pinned your first file to Filecoin. You now have:

• ✅ The Filecoin Pin CLI installed and configured
• ✅ Your wallet connected with funded payments on Filecoin Pay
• ✅ Files pinned to two Filecoin storage providers with daily cryptographic proofs
• ✅ Your content retrievable via standard IPFS gateways

🔜 Next Steps

• 📖 Run filecoin-pin --help to explore advanced usage, including auto-funding and custom provider selection.
• 🔍 Want to understand what's happening behind the scenes? Read Behind the Scenes of Adding a File for a deep dive into each step.
• 🤖 Automate pinning in your CI/CD pipeline with the Filecoin Pin GitHub Action.
• 💬 Join the community in Filecoin Slack #fil-foc for help, discussion, and updates.
• 🐛 Found a bug or have a feature request? Open an issue on GitHub.