filecoin-project/filecoin-pin

feat: add `filecoin-pin get` retrieval command

Open

#575 opened on Jun 15, 2026

View on GitHub
 (8 comments) (1 reaction) (1 assignee)TypeScript (18 forks)github user discovery
CLIenhancementhelp wantedready-for-workteam/filecoin-pinteam/fs-wg

Repository metrics

Stars
 (22 stars)
PR merge metrics
 (PR metrics pending)

Description

Description

After a successful upload, filecoin-pin gives the user a CID and retrieval URLs but has no way to fetch content itself. Users must switch to Kubo, a browser, or curl to retrieve what they just stored. This breaks the upload-store-retrieve loop. A tool that can pin should also be able to retrieve. SP retrieval URLs work over plain HTTP and don't require IPFS routing, so a get command doesn't depend on IPNI being ready.

Proposed solution

Add filecoin-pin get <cid>/<pieceCid> that fetches content from the SP retrieval URL. Support -O <filename> to write output to a file (mirroring curl -O). Accept both IPFS CID and Piece CID. Default to stdout so it composes with pipes.

Done criteria

  • filecoin-pin get <ipfs-cid> streams file content from the SP retrieval URL
  • filecoin-pin get <cid> -O <filename> writes output to disk
  • Works without IPNI being ready (fetches directly from SP, not via gateway)
  • Piece CID accepted as an alternative to IPFS CID
  • Error message is actionable when CID is not retrievable

Notes

  • Implementation: wrap verified-fetch

Contributor guide

Research direction
Examine the existing filecoin pin codebase, particularly how upload works and how verified fetch is used. Understand the SP retrieval URL format and implement a get command that streams content to stdout or a file. Refer to the verified fetch documentation for fetching content.
Tech stack
typescript
Domain
backendcli
Issue type
Feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
Half day
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
GitTypeScriptIPFS/Filecoin basics
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
60