Quickstart

This guide installs filecoin, logs in, stores a file, and downloads it again. It uses the calibration test network, so storage is paid with test USDFC.

You need:

• Node.js 24 or newer.
• A browser wallet, such as MetaMask, with calibration FIL for gas and test USDFC. The Filecoin docs list the faucets.

Hand it to an agent

Add Filecoin for Agents to your agent, then ask it to store a file. On its first run, the agent sends you a link to approve its key with your wallet. Agents covers cloud and browser agents.

claude plugin marketplace add filecoin-project/agentsclaude plugin install filecoin@filecoin # In Codexcodex plugin marketplace add filecoin-project/agentscodex plugin add filecoin@filecoin

npx skills add https://poc.filecoin.cloud

npx -y add-mcp https://api.filecoin.cloud/mcp -g

To do it yourself, follow the steps below.

Install the CLI

npm install -g filecoin
filecoin --help

Log in

filecoin login

filecoin login makes a session key, saves it on your machine, and opens the filecoin-app setup page. Connect your wallet there, review the request, and approve each step. The page can also approve Warm Storage and deposit USDFC. The private key never leaves your machine, and the CLI finds the approval on chain, so there is nothing to copy back.

Then check the account:

filecoin status

filecoin status reports when each permission expires, your USDFC funds, and the Warm Storage approval. If the account needs a deposit, it also returns a funding link.

Store a file

Check the size, provider, and cost first. A dry run stores nothing:

filecoin put ./report.pdf --dry-run

Then store it:

filecoin put ./report.pdf

The result's urls.browser is the link to share. A new link to a file can return 404 for a while. Retrieve and verify explains why, and what each link checks.

Get it back

filecoin ls
filecoin get res_… --output ./copy.pdf

filecoin get downloads from the provider and checks the bytes against the PieceCID.

Next

• CLI explains how filecoin works and where its help and schemas are.
• Agents shows how to give an agent the same access.