feat: add `filecoin-pin get` retrieval command

[BravoNatalie]

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

[SgtPooki]

2026-06-16

One thing to reconcile before someone picks this up: "wrap verified-fetch" and "works without IPNI" pull in different directions.

verified-fetch resolves a CID by routing (delegated routing / trustless gateways) to find who has the content. That path depends on the content being discoverable, which is what IPNI provides. So a naive verified-fetch wrap would still wait on IPNI, contradicting DoD bullet 3.

To honor "fetches directly from SP, not via gateway," point verified-fetch straight at the SP retrieval endpoint as its source (bypassing routing), or skip it for that path and do a plain HTTP fetch against the SP retrieval URL. Either works; just worth deciding up front so we don't ship something that quietly needs IPNI.

[BravoNatalie]

2026-06-16

One thing to reconcile before someone picks this up: "wrap verified-fetch" and "works without IPNI" pull in different directions.

verified-fetch resolves a CID by routing (delegated routing / trustless gateways) to find who has the content. That path depends on the content being discoverable, which is what IPNI provides. So a naive verified-fetch wrap would still wait on IPNI, contradicting DoD bullet 3.

To honor "fetches directly from SP, not via gateway," point verified-fetch straight at the SP retrieval endpoint as its source (bypassing routing), or skip it for that path and do a plain HTTP fetch against the SP retrieval URL. Either works; just worth deciding up front so we don't ship something that quietly needs IPNI.

@SgtPooki
Oh, I actually added a question about that in the Notion doc.

If we're using verified-fetch, then we can redirect requests to the trustless endpoint sp-url/ipfs/<cid>. But what about fetching a piece CID through sp-url/piece/<pieceCid>?

Should we remove that retrieval option since the content can't be verified, or just add a note explaining that using the same command with a piece CID does not actually verify the retrieved content?

[BigLep]

I think it would be good to make sure we docs/help text explaining:

1. How this is different/better than curl (it verifies the content matches CID)
2. How this is different/better than kubo get or `verified-fetch_ (it doesn't rely on IPFS Mainnet content routing, but it would still be fine to use those solutions)

[rvagg]

There's a few distinct modes here and an API would need to be clear about what it's supposed to do because "get" is not all that clear. Consider the possibilities here:

• Get the original piece that was uploaded - the CAR we formed when packing, not strictly a well-formed depth-first traversal order CAR but complete. This is from /piece/bagafoo... from a specific SP known to have the piece. Verification would involve running commp over the piece to make sure bagafoo... is what we got, this can be done via the stream as it's received (synapse has utils for this).
• Get the CAR from the /ipfs/bafyfoo... endpoint which is the same data but well-formed by traversal, won't match the /piece/ CAR but will have the same data. This can be fetched from a specific SP with format=car, no need for IPNI to be involved here. Verification (optional) would involve running the traversal locally over the blocks , unixfs-exporter can do this for us, opposite of unixfs-importer (verified-fetch does this, the simplest version of it is demonstrated in Serve IPFS retrievals filbeam/worker#312; not too hard but not trivial).
  • Unpack variant: unpack the file/directory found within the CAR, the reverse of add whereas the "fetch a CAR" is the reverse of import.
    • With the unpack variant where you want to support piping to stdout you have to figure out what to do when your root isn't a raw or file but is a directory.
    • Where you discover that the content is not UnixFS data but someone has imported some other IPLD data that you can't unpack, what then?
• Get the CAR using verified-fetch from its sources (IPNI) which doesn't tie you to an SP, might fetch from non-SP sources, has verification built-in, but isn't strictly a reverse of the add/import flow, you're basically doing lassie here, but that's OK; at least the hard work is done in verified-fetch.
  • Unpack variant.

I think it'd be worth exploring the UX of those permutations before jumping in on this.

One major point I'd impress here is that we want to keep CARs as an implementation detail as much as possible. I know the ecosystem hasn't been good at this, we like to get enamoured with our own technologies, but a CAR really is just a transport for moving content addressed blocks as a group and nobody else really needs to care about this unless what they want is "all of my IPFS data stored in IPFS form in one single file"; which I reckon isn't going to be a common thing. If you're getting your data, you really just want your data, and the CAR is just a means that we happened to use to store it as a single piece on an SP and also happens to be the transport we used to stream it to and from the SP and provides us with a nice stable container (when fetching from /ipfs/) with predictable block ordering that makes for easy verification. But once we've moved the blocks and verified them, then the IPFS job is done; you can have your files back. But as per above, there's a few cans of worms here that need to be thought through.