Ctrlk
BasicsStorage providersNodesNetworksSmart contractsReference
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Migrate from the command line

Migrate your IPFS pins to Filecoin Onchain Cloud from the terminal with the ipfs2foc CLI. The recommended path for any serious migration.

The ipfs2foc CLI migrates your pins in a single command. It handles files of any size, scales to large inventories, and requires nothing about your machine to be reachable from the internet.

This is the recommended path for any serious migration.

ipfs2foc is a bridge. This migration logic is actively being moved into a native filecoin-pin migrate subcommand. Everything on this page works today, but once that subcommand lands it becomes the supported path, and migrating will be one command inside the Filecoin Pin tool you already use for new uploads.

What you need

  • Node.js 24 or newer. Check with node --version.

  • A wallet with FIL for gas and USDFC for storage. You will export its private key, so use one kept for this purpose.

  • A list of CIDs to migrate.

  • Content that is fetchable from an IPFS gateway. Support varies by pinning provider - check Where your content is fetched from for yours.

The walkthrough below takes one CID end to end on Filecoin Mainnet. By the end you'll have measured a piece, uploaded it, committed it onchain, and confirmed it with report.

Step 1: Install

npm install -g ipfs2foc

Confirm the install:

npm ls -g ipfs2foc

You should see ipfs2foc@0.8.1 or later.

Step 2: Set your signing key

Export the private key of a Filecoin wallet funded with FIL and USDFC on Filecoin Mainnet. The key must be 0x followed by 64 hex characters:

Verify the format. This must print 66:

This one key does everything. It signs every transaction in the migration and authorizes spending from your deposited balance. Use a dedicated wallet funded with roughly what the migration needs. Never use a wallet holding significant funds, and never paste this key into a web page.

Keep this terminal open for the rest of the guide - the variable is lost when you close it.

Step 3: Check your gateway

Before spending anything, confirm a gateway serves your content in the verifiable form the migration requires. Pick any one CID from your list:

A working gateway returns a line beginning OK and ending deterministic:

Seeing FAIL or fetch failed? Try a different gateway before assuming your content is at fault. Public gateways are not reachable from every network. Try your own pinning provider's gateway instead:

ipfs2foc probe <cid> --gateway https://gateway.pinata.cloud

Whichever gateway returns OK is the one to use - pass it with --gateway on every command below. For what WARN and FAIL each mean, and the gateway to use for your provider, see Where your content is fetched from.

Step 4: Fund your account

Two currencies do two different jobs. FIL pays gas on your own transactions. USDFC pays storage providers.

Confirm you have a sufficient balance before going further:

You should see a positive USDFC balance with approvals in place.

Deposit a comfortable margin. If your balance or allowance falls short, the migration fails at the commit stage, and the error may not tell you how much more is needed.

Step 5: Build your CID list

One CID per line in a plain text file. Blank lines and lines beginning with # are ignored:

Step 6: Migrate

One command runs the whole migration:

Flag
Purpose

--cids

Your list of CIDs.

--car-store

Required. A working directory where content is staged. Files are deleted as each piece is confirmed, so it stays near 1 GiB rather than growing to the size of your migration.

--db

Progress file, so an interrupted run resumes instead of restarting.

--gateway

The gateway you validated in step 3.

Do not press Ctrl+C. Interrupting between upload and onchain confirmation can leave a piece in an unconfirmed state needing manual recovery. If the run seems stuck, let it time out.

What you'll see

The run reads and measures your content, packs it, then uploads and commits.

You should see something like:

It finishes with a JSON summary of the run.

To store a single copy instead of two - cheaper, less redundant - add --copies 1.

Step 7: Confirm it landed

Reconcile your local record against what is actually onchain:

The line that matters is the CID count.

You should see something like:

When committed equals your total and failed is zero, your migration succeeded.

A "not yet proven" warning here is expected. Committing your data onchain and proving it is stored are two separate events. Providers prove possession on a recurring schedule, and the first proof after your migration can be up to a couple of hours away. The command also exits with a non-zero code while that is pending.

If your CID count reads fully committed with zero failures, you are done. Run the same command again later and the warning clears.

Step 8: Verify retrieval

The whole point is that nothing about retrieval changes. Fetch one of your CIDs the way you always have:

200 means your content still resolves by its original CID.

Now switch to Filecoin Pin

Your existing pins are on Filecoin Onchain Cloud, and this migration is a one-time job.

From here, use Filecoin Pin for everything new. IPFS2FOC is built for moving a backlog, not for day-to-day uploads. Filecoin Pin is the ongoing workflow: it pins new content, gives the same verifiable Filecoin persistence, and works with the standard IPFS tooling you already use.

Related

PreviousMigrating IPFS pins to Filecoin Onchain Cloud
NextFilecoin Pin GitHub Action

Last updated