Related Pages

Related topics: CLI Command Reference, JavaScript Library and Core Modules, Integrations, Configuration, and Operations

Overview and System Architecture

Purpose and Scope

Filecoin Pin is the reference implementation for uploading content to Filecoin Onchain Cloud. It packages the underlying Synapse SDK and Helia into several user-facing affordances that share one well-tested core library, so the same upload behavior is reachable from a terminal, a CI pipeline, a JavaScript application, or a standards-compliant IPFS Pinning Service endpoint.

The repository ships four affordances:

Source: README.md:1-60

The project targets a predictable workflow: a user authenticates with a private key or session key, tops up the on-chain Filecoin Pay balance, packs input into a UnixFS DAG, ships it as a CAR, and hands the resulting pieces to a Filecoin storage provider. The same core flow backs every affordance so behavior stays consistent across them.

System Architecture

The architecture is layered: thin interface adapters at the top, a shared src/core/ library in the middle, and the Synapse SDK plus Helia at the bottom.

flowchart TB
  subgraph Affordances
    CLI["CLI<br/>src/cli, src/data-set, src/payments"]
    Lib["JavaScript Library<br/>filecoin-pin / filecoin-pin/core/*"]
    Action["GitHub Upload Action<br/>upload-action/"]
    Server["IPFS Pinning Server (beta)<br/>filecoin-pin server"]
  end

  subgraph Core["src/core/ (shared business logic)"]
    Syn["core/synapse<br/>SDK init + session keys"]
    Upload["core/upload<br/>CAR → Synapse"]
    Payments["core/payments<br/>Filecoin Pay planning"]
    DataSet["core/data-set<br/>list / show / pieces"]
    UnixFS["core/unixfs<br/>Helia DAG packing"]
    CAR["core/car<br/>storage backends"]
  end

  subgraph External
    Synapse["@filoz/synapse-sdk"]
    Helia["Helia (UnixFS)"]
    FOC["Filecoin Onchain Cloud<br/>(WarmStorage, PDP, Filecoin Pay)"]
    SP["Storage Providers"]
  end

  CLI --> Core
  Lib --> Core
  Action --> Core
  Server --> Core
  Syn --> Synapse
  Upload --> Synapse
  Payments --> Synapse
  DataSet --> Synapse
  UnixFS --> Helia
  CAR --> Helia
  Synapse --> FOC
  FOC --> SP

Each affordance imports from filecoin-pin/core/* rather than re-implementing the flow. As the maintainers note, this is deliberate: keeping the business logic in one place "makes mocking easier for testing" and lets the surrounding UX layers be forked and remixed independently. Source: src/core/payments/README.md:1-15

The same initializeSynapse helper that powers the CLI also boots the upload action, the JS library, and the Pinning Server. It accepts a privateKey, an rpcUrl, and optional session-key configuration, then returns a Synapse instance bound to a logger. Source: src/core/payments/README.md:60-72

Core Module Organization

The shared library is partitioned by responsibility rather than by feature:

• core/synapse — wraps SDK initialization, WebSocket cleanup, session-key detection, and a reusable service singleton. Source: src/core/payments/README.md:20-30
• core/upload — accepts a CAR stream plus a root CID, runs it through uploadToSynapse, and surfaces progress events for piece addition, confirmation, and metadata association. Source: src/core/payments/README.md:32-44
• core/payments — wraps Filecoin Pay: FIL gas balance, USDFC wallet and deposit balances, ERC20 approve/deposit, service approvals, and a funding planner that turns a PaymentStatus plus an accountSummary into a deposit plan with a human-readable reason. Source: src/core/payments/index.ts:1-60, src/core/payments/funding.ts:1-50
• core/data-set — wraps dataset queries and piece inspection. It defines a PieceStatus enum covering ACTIVE, PENDING_REMOVAL, ONCHAIN_ORPHANED, and OFFCHAIN_ORPHANED so the CLI can surface on-chain vs. provider-side state clearly. Source: src/core/data-set/index.ts:1-15, src/core/data-set/types.ts:20-40
• core/car — provides a CARStorageBackend interface with initialize, writeBlock, readBlock, finalize, and cleanup, so memory and filesystem backends stay pluggable. Source: src/core/car/car-storage-backend.ts:1-55
• core/unixfs — Helia-based DAG packing that turns a file or directory into a UnixFS root CID plus a CAR.

Cross-cutting helpers live under src/utils/. cli-auth.ts normalizes authentication flags (--private-key, --wallet-address, --session-key, --view-address, --network, --rpc-url, --provider-id, --data-set-id) and merges the deprecated comma-separated aliases into a single array. Source: src/utils/cli-auth.ts:1-50. cli-logger.ts applies the global -v/--verbose flag to LOG_LEVEL and switches between Clack's TTY renderer and plain console.log for CI environments. Source: src/utils/cli-logger.ts:1-50

Affordance Layer

CLI

The CLI is the primary human interface. Commands are grouped for the v1.1.0 release so that add and import — the two primary upload verbs — are no longer buried mid-list (see #576). The companion data-set list was changed to a compact summary view (#578), and piece-status gained pagination because the original "list everything" approach degraded linearly on large datasets (#579). A long-standing community request is a --dry-run mode for add that surfaces packed size and storage cost before any commitment (#591).

GitHub Upload Action

The action lives in upload-action/ and is versioned separately (#527). It composes a build step, a transfer step, and a comment step, posting PR comments, creating check runs via octokit.rest.checks.update, and consuming a CombinedContext that carries upload results, payment status, optional CDN and provider overrides, and a dryRun flag. Source: upload-action/src/types.ts:1-80, upload-action/src/github.js:1-50

The action is deliberately conservative: only same-repo PRs and direct pushes are accepted, and workflow_run events with incomplete repository provenance are rejected "before wallet input validation or upload" to prevent non-maintainer PR actors from draining funds. Source: upload-action/README.md:60-75

JavaScript Library and IPFS Pinning Server

The library exposes both a curated filecoin-pin entry point for most consumers and a lower-level filecoin-pin/core/* surface for users who need to remix a single module. The Pinning Server reuses the same core, holding state in memory for the duration of a process. It implements the IPFS Pinning Service API spec so ipfs pin remote works against it; because state is not persisted, the maintainers flag it as beta. Source: README.md:18-28

Cross-Cutting Design Notes

A few decisions recur across the architecture and are worth knowing for new contributors:

• SkipProvider for termination. data-set terminate calls synapse.storage.terminateService({ dataSetId, skipProvider: true }); this is filecoin-pin's explicit choice rather than the SDK default and is being tracked as a long-term confirmation in #581.
• Egress defaults. The community is converging on making --egress-provider beam the default for add and import, with --egress-provider none available to opt out (#464).
• Retrieval round-trip. A long-standing gap — no built-in get command — is being closed in #575 so the upload-store-retrieve loop stays inside one tool.
• Key handling. Session keys and view-only addresses are first-class alongside a raw PRIVATE_KEY, and support for 1Password/LastPass/Bitwarden secure vaults is under investigation in #589.
• Formatting. All currency and runway values are rendered through core/utils/format.ts, which dynamically widens decimal precision for sub-cent amounts so a non-zero tFIL balance is never silently rounded to 0.0000. Source: src/core/utils/format.ts:1-25

See Also

• Behind the Scenes of Adding a File — end-to-end walkthrough of an add run.
• Content Routing FAQ — IPNI caching, providers, and indexer behavior.
• Retrieving Your Data — gateways, trustless retrieval, and /piece endpoints.
• Progress Events — typed onProgress unions exposed by the JS library.
• Glossary — definitions for Filecoin Onchain Cloud, Synapse, PDP, and related terms.

Related Pages

Related topics: Overview and System Architecture, JavaScript Library and Core Modules, Integrations, Configuration, and Operations

CLI Command Reference

The filecoin-pin command-line interface is the primary user-facing affordance of the project. It wraps the Synapse SDK to provide a one-stop tool for packing local files into IPFS-compatible data, uploading them to Filecoin Onchain Cloud, managing data sets, and operating the payment rail that funds storage. The same business logic exposed by the CLI is also reused by the upload-action/ composite action and the filecoin-pin JavaScript library, ensuring consistent behavior across affordances (README.md:67-88).

Command Groups

The CLI organizes its surface into groups so newcomers can see the typical workflow at a glance — a redesign tracked in #576 and shipped in v1.1.0 (v1.1.0 release notes). The primary groups are Uploads (add, import), Data Sets (data-set list, data-set show, data-set terminate, piece-status), Payments (payments setup, payments status, deposit, withdraw), and Server (server).

Typical Quick-Start Workflow

# 1. Configure payments (lockup + USDFC top-up)
filecoin-pin payments setup --auto-fund

# 2. Upload (pack + send in one step)
filecoin-pin add ./my-data

# 3. Inspect
filecoin-pin data-set list
filecoin-pin data-set show <datasetID>

Common Options and Authentication

Authentication is shared across every command that signs transactions. The --private-key / --wallet-address / --session-key triplet is registered once via addAuthOptions so behavior stays consistent, and every option is bound to a matching environment variable so --help shows [env: PRIVATE_KEY] etc. (src/utils/cli-options.ts:31-49). The CLI flag wins over the env var when both are set.

The --network flag selects between mainnet (default), calibration, and devnet. --network and --rpc-url are mutually exclusive — passing both is a hard error. When --rpc-url is supplied, Filecoin Pin probes eth_chainId at startup and uses the matching chain (README.md:96-120).

The --metadata key=value flag is repeatable and accepts an empty value; it is wired through addMetadataOptions in src/utils/cli-options-metadata.ts:27-58, which also adds the dataset-metadata variant and the optional --erc8004-type for artifact types. A planned --egress-provider flag (defaulting to beam, with none to opt out) is tracked in #464.

The global -v/--verbose flag maps to LOG_LEVEL=debug unless an explicit level is already exported, letting any command emit debug logs (src/utils/cli-logger.ts:21-27). Spinners and intro/outro prompts are handled by src/utils/cli-helpers.ts:23-66, which degrades to plain text in non-TTY environments so the CLI is scriptable.

Cost Estimation, Pagination, and Retrieval — In Flight

Several community-driven enhancements are landing alongside the command-group refactor:

• add --dry-run: Pre-upload estimates of packed size and storage cost, surfaced before any on-chain commit. Tracked in #591.
• piece-status pagination: The current implementation fetches piece metadata serially, which scales poorly. Pagination is the proposed fix (#579).
• filecoin-pin get <cid>: A first-class retrieval command that closes the upload-store-retrieve loop, removing the need to switch to Kubo or curl after pinning. Tracked in #575.
• Secure-vault key sourcing: Investigation of 1Password / LastPass / Bitwarden integrations for private-key material, supplementing openwallet flows, is tracked in #589.
• Error-scenario smoke tests: A regression matrix for CLI error outputs and exit codes, born out of the CliFatal sentinel work, is tracked in #470.

See Also

• Builder Cookbook — hands-on CLI and GitHub Action recipes
• Progress Events — typed onProgress event unions for library consumers
• Retrieving Your Data — fetching content back from an IPFS Root CID
• Configuration Reference — environment variables and network selection
• upload-action README — the GitHub Action that wraps the same CLI

Related Pages

Related topics: Overview and System Architecture, CLI Command Reference, Integrations, Configuration, and Operations

JavaScript Library and Core Modules

Overview and Purpose

filecoin-pin is published as a multi-entry-point npm package that exposes the same business logic that drives the CLI and the upload-action GitHub Action. The README explicitly recommends two import styles: the high-level import { ... } from 'filecoin-pin' for most consumers, and the lower-level import { ... } from 'filecoin-pin/core/*' modules for callers who need to assemble their own pipelines (CAR files, payments, Synapse SDK, uploads, UnixFS). Source: README.md

The src/core/ tree is intentionally curated as a *reference implementation* of how to talk to the Synapse SDK. According to the module's own README, "Synapse is abstracted within Filecoin Pin to isolate it as an educational resource, to integrate with our logging system, and to make mocking easier for testing." Source: src/core/payments/README.md

The library is consumed by three affordances (CLI, GitHub Action, IPFS Pinning Server) plus external dApps, so the design goal is to keep the canonical flows in core/ while letting each affordance remain thin and easy to fork.

Package Layout and Export Surface

The exports field in package.json declares the public entry points. The high-level package and several core/* subpaths ship with TypeScript types and a JavaScript implementation:

Source: package.json

The bin field registers a single filecoin-pin executable that dispatches to the CLI. A separate browser-only entry (src/core/car/browser.ts) re-exports a CAR blockstore plus carInputError, INPUT_IS_CAR, and isCar helpers so that browser bundles do not pull in Node-only modules. Source: src/core/car/browser.ts

Core Module Reference

`core/synapse` — SDK Initialization and Lifecycle

Provides SDK configuration (network, RPC URL, private key), storage context creation, progress callbacks, WebSocket cleanup, and a service-singleton pattern for reuse across multiple operations. The CLI's authentication helpers share these conventions, including handling of private key, session key, and view-only address modes. Source: src/utils/cli-auth.ts

`core/upload` — Data Upload Patterns

The unified upload interface accepts either pre-built CAR files or paths that the UnixFS layer will pack first. It surfaces typed progress events for upload, piece addition, and confirmation, links the IPFS Root CID to the resulting Filecoin piece, and reports the provider's direct-download URLs. This is the same pipeline that filecoin-pin add and filecoin-pin import invoke under the hood.

`core/payments` — Filecoin Pay Operations

This is the most fully documented module. The README enumerates four capability buckets: native FIL balance checking for gas fees; ERC20 (USDFC) balance management; the two-step approve-then-deposit flow; and service-approval configuration for storage operators. Source: src/core/payments/README.md

The payments module exports a planFilecoinPayFunding function (and a pure counterpart calculateFundingPlan) that classifies the reason for any required deposit. The reason codes — none, piece-upload, runway-insufficient, runway-with-piece, target-deposit, withdrawal-excess — map to localized strings via formatFundingReason. This classification powers the filecoin-pin payments deposit UX so users can see *why* they are being asked to top up. Source: src/core/payments/funding.ts

Deposits can be safely clamped to a user-supplied balance ceiling through clampDepositToLimit, which returns one of three outcomes (passthrough, already-at-limit, clamped) with an explanatory message. Source: src/core/payments/top-up.ts

`core/data-set` — Data Set Management

Provides listing, summarization, and inspection helpers. listDataSets(synapse, options) returns DataSetSummary[] and optionally filters by address, marking entries that were created through Filecoin Pin (via the DEFAULT_DATA_SET_METADATA sentinel). This is the underlying source for the filecoin-pin data-set list command, whose output was compacted in v1.1.0 to make scanning easier (community issue #578). Source: src/core/data-set/list-data-sets.ts

`core/unixfs`, `core/car`, `core/utils`

These support the upload pipeline: unixfs turns files and directories into CAR-shaped block graphs via Helia; car provides CAR blockstore utilities (with a Node-only and a browser-only entry point); utils exposes formatting helpers used across all affordances. For example, formatFIL(amount, isTestnet, decimals) automatically widens the displayed precision when the raw value rounds to zero, and formatRunway(days, hoursRemainder) produces human strings such as "1 year(s) 2 month(s)" for storage runway output. Source: src/core/utils/format.ts

Usage Patterns and Conventions

High-level vs. low-level API

Most consumers should import from the package root. Callers building their own workflows — for example a custom dApp that needs to deposit USDFC, pack a CAR, and upload without the CLI's argument parsing — should prefer the core/* subpaths. Both share the same logger (pino) and event conventions, so telemetry and progress reporting remain consistent. Source: README.md

Metadata and authentication flags

The CLI registers metadata flags (piece-level, dataset-level, and optional ERC-8004 artifacts) through a single helper, registerMetadataOptions, which enforces key=value syntax, rejects duplicate keys, and normalizes ERC-8004 configuration. Source: src/utils/cli-options-metadata.ts

Authentication flags (--private-key, --wallet-address, --session-key, --view-address, --network, --rpc-url, --provider-id, --data-set-id) are collected by parseAuthOptions, which merges the canonical repeatable flags with their deprecated comma-separated aliases and forwards the result to initializeSynapse. Source: src/utils/cli-auth.ts

Telemetry and versioning

The package re-exports read-telemetry-config-from-env and version-check so library consumers can honor the same disable mechanisms the CLI and GitHub Action support (see documentation/events-and-metrics.md). Telemetry is on by default for the affordances but never collects PII, and every emission goes through the same event names used by the CLI.

Architecture at a Glance

flowchart LR
  Consumer["dApp / external code"] -->|"filecoin-pin"| Facade["src/index.ts<br/>(high-level facade)"]
  Consumer -->|"filecoin-pin/core/*"| Core["src/core/* modules"]
  Facade --> Core
  Core --> Synapse["@filoz/synapse-sdk"]
  Synapse --> FOC["Filecoin Onchain Cloud<br/>(smart contracts, SPs)"]
  Core --> Helia["Helia<br/>(UnixFS packing)"]
  Helia --> CAR["CAR v1 blocks"]
  CAR --> Synapse
  CLI["CLI (bin: filecoin-pin)"] --> Facade
  Action["upload-action"] --> Facade
  Server["Pinning Server (beta)"] --> Facade

Failure Modes and Community Considerations

Several community issues map directly to library behavior:

• A --dry-run mode (issue #591) would let core/upload report packed size and cost before any on-chain call. Today the same information is exposed only after the upload begins; library consumers wanting an estimate must call synapse.storage.getPriceList() themselves.
• The data-set terminate flow hard-codes skipProvider: true when calling synapse.storage.terminateService (issue #581). Library consumers should be aware that this is a Filecoin Pin choice rather than an SDK default.
• A planned filecoin-pin get retrieval command (issue #575) is intended to close the upload-store-retrieve loop; once shipped, the underlying logic will be added to a core/retrieve module so that library consumers can fetch content programmatically.
• piece-status and data-set show currently fetch piece metadata serially, causing both latency and output overflow on large datasets (issue #579). Library consumers hitting the same problem should switch to listDataSets (now compact in v1.1.0) or paginate manually until the upstream fix lands.

See Also

• Builder Cookbook — practical guides for the CLI, GitHub Action, library, and dApp demo
• Behind the scenes of adding a file — deep dive into the add flow
• Progress Events — typed onProgress event conventions
• Events & Metrics — telemetry event names and tags
• Retrieval — fetching content back by IPFS Root CID
• Content Routing FAQ — IPNI caching and provider management
• API Reference — TypeDoc-generated reference

Related Pages

Related topics: Overview and System Architecture, CLI Command Reference, JavaScript Library and Core Modules

Integrations, Configuration, and Operations

Filecoin Pin is distributed as a single package that exposes several integration surfaces — a CLI, a programmatic JavaScript library, a GitHub Action, and a Pinning Service daemon — all sharing one core module built on top of the Synapse SDK. This page documents how those surfaces are wired together, how authentication and network selection are configured, and how day-to-day operational workflows (payments funding and data-set management) are expressed across surfaces.

Integration Surfaces

The repository ships four user-facing affordances that all share the same filecoin-pin/core/* library, ensuring consistent behavior across interfaces. Source: README.md.

The library has two import levels: a high-level API (filecoin-pin) for most consumers, and a core/* namespace exposing CAR files, payments, Synapse SDK, uploads, and UnixFS primitives for advanced integrators. Source: README.md.

Authentication and Network Configuration

Every CLI command that touches the chain funnels its options through a shared CLIAuthOptions interface, which is then normalized into a SynapseSetupConfig for SDK initialization. Source: src/utils/cli-auth.ts:23-48.

export interface CLIAuthOptions {
  privateKey?: string
  walletAddress?: string
  sessionKey?: string
  viewAddress?: string
  network?: string
  rpcUrl?: string
  providerIds?: string[]
  dataSetIds?: string[]
}

Key operational notes:

• Four signing modes are supported: a direct private key, a session key paired with a wallet address, a view-only address, and MetaMask-style session keys. The isSessionKeyMode helper detects which mode the caller is using. Source: src/core/payments/index.ts:22-23.
• Network selection resolves through NETWORK_CHAINS and getRpcUrl, which also support an RPC URL override and a local devnet configuration via resolveDevnetConfig. Source: src/utils/cli-auth.ts:7-8.
• Provider and data-set overrides accept both a canonical repeatable --provider-id flag and a deprecated comma-separated --provider-ids alias; both are merged into the providerIds array at parse time so downstream code only sees one shape. Source: src/utils/cli-auth.ts:39-48.
• GitHub Action consumers configure a PaymentConfig that pins minStorageDays and (optionally) filecoinPayBalanceLimit directly in workflow files; both are passed in via the with: block of action.yml. Source: upload-action/src/types.ts:60-65.

The GitHub Action additionally enforces a two-workflow pattern that rejects artifacts from forks, even those flowing through workflow_run, to prevent non-maintainer PR actors from draining funds. Source: upload-action/README.md.

Payment and Funding Operations

Filecoin Pin uses Filecoin Pay (USDFC) for storage payments and FIL for gas. The core/payments module is the integration point and exposes balance checks, ERC20 approve/deposit helpers, service approvals, and a pure-calculator planFilecoinPayFunding function for both runway-based and target-deposit-based funding. Source: src/core/payments/README.md.

flowchart LR
  CLI[filecoin-pin payments] -->|CLIAuthOptions| Setup[initializeSynapse]
  Setup -->|Synapse SDK| Status[getPaymentStatus]
  Status --> Plan[planFilecoinPayFunding]
  Plan -->|deficit| Approve[USDFC approve]
  Approve --> Deposit[USDFC deposit]
  Deposit --> Service[WarmStorage service approval]
  Service --> Ready[Ready to upload]

The funding planner reasons about distinct reason codes — none, piece-upload, runway-insufficient, runway-with-piece, target-deposit, and withdrawal-excess — and returns a human-readable explanation per code so the CLI can print *why* a top-up is required rather than only *how much*. Source: src/core/payments/funding.ts:18-44.

Operationally relevant constants live alongside the module: MIN_FIL_FOR_GAS = 0.1 FIL, DEFAULT_LOCKUP_DAYS derived from synapse-core, and MAX_RATE_ALLOWANCE/MAX_LOCKUP_ALLOWANCE set to maxUint256 so wallets display "Unlimited". Source: src/core/payments/constants.ts:14-31.

Data-Set Operations

The core/data-set module wraps Synapse SDK primitives to provide a single API for listing, enriching, and inspecting data sets. Source: src/core/data-set/index.ts:1-22.

Exported entry points include listDataSets, getDataSetPieces, getDetailedDataSet, calculateActualStorage, and resolveByMetadata. They operate on a DataSetSummary shape that augments the SDK's EnhancedDataSetInfo with a dataSetId alias for pdpVerifierDataSetId, optional provider enrichment, computed totals, optional piece lists, a createdWithFilecoinPin flag, and structured warnings. Source: src/core/data-set/types.ts:60-92.

Piece health is reported through a PieceStatus enum — ACTIVE, PENDING_REMOVAL, ONCHAIN_ORPHANED, and OFFCHAIN_ORPHANED — where the orphaned states are surfaced explicitly because, while unexpected, they have been observed in practice and must be logged for operators. Source: src/core/data-set/types.ts:27-39.

data-set terminate deliberately calls synapse.storage.terminateService({ dataSetId, skipProvider: true }). The skipProvider: true is an explicit Filecoin Pin choice — not the SDK default — and is tracked as a deliberate operational policy. Source: issue #581.

Operational Tooling

Community work has steadily added affordances for safe day-to-day operations: a reorganized --help with command groups (#576), a compact summary view for data-set list (#578), pagination for data-set show and piece-status (#579), a --dry-run flag for filecoin-pin add to estimate packed size and cost (#591), and a filecoin-pin get retrieval command so users do not need to leave the tool to fetch what they just stored (#575). The upload-action is also being prepared for extraction into its own repository for independent versioning (#527).

See Also

• Behind the Scenes of Adding a File
• Glossary
• Retrieving Your Data
• Progress Events
• Content Routing FAQ

Doramagic Pitfall Log

Found 28 structured pitfall item(s), including 5 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/filecoin-project/filecoin-pin/issues/575

2. Runtime risk: Runtime risk requires verification

• Severity: high
• Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/filecoin-project/filecoin-pin/issues/579

3. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Developers should check this security_permissions risk before relying on the project: Add CLI error-scenario smoke test matrix for devs
• User impact: Developers may expose sensitive permissions or credentials: Add CLI error-scenario smoke test matrix for devs
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Add CLI error-scenario smoke test matrix for devs. Context: Observed when using node
• Evidence: failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/470

4. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/filecoin-project/filecoin-pin/issues/470

5. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/filecoin-project/filecoin-pin/issues/527

6. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Extract upload-action into a standalone repository for independent versioning
• User impact: Developers may fail before the first successful local run: Extract upload-action into a standalone repository for independent versioning
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Extract upload-action into a standalone repository for independent versioning. Context: Observed when using node
• Evidence: failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/527

7. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: feat: add compact summary view to data-set list
• User impact: Developers may fail before the first successful local run: feat: add compact summary view to data-set list
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: feat: add compact summary view to data-set list. Context: Observed when using node
• Evidence: failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/578

8. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v0.22.1
• User impact: Upgrade or migration may change expected behavior: v0.22.1
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.22.1. Context: Observed when using node
• Evidence: failure_mode_cluster:github_release | https://github.com/filecoin-project/filecoin-pin/releases/tag/v0.22.1

9. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v0.23.2
• User impact: Upgrade or migration may change expected behavior: v0.23.2
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.23.2. Context: Observed when using node
• Evidence: failure_mode_cluster:github_release | https://github.com/filecoin-project/filecoin-pin/releases/tag/v0.23.2

10. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/filecoin-project/filecoin-pin/issues/578

11. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: v0.22.3
• User impact: Upgrade or migration may change expected behavior: v0.22.3
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.22.3. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/filecoin-project/filecoin-pin/releases/tag/v0.22.3

12. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: v0.23.0
• User impact: Upgrade or migration may change expected behavior: v0.23.0
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.23.0. Context: Observed during version upgrade or migration.
• Evidence: failure_mode_cluster:github_release | https://github.com/filecoin-project/filecoin-pin/releases/tag/v0.23.0

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using filecoin-pin with real data or production workflows.

• feat: reorganize --help output with command groups and quick-start exa - github / github_issue
• feat: add compact summary view to data-set list - github / github_issue
• feat: add --dry-run flag to filecoin-pin add for pre-upload cost est - github / github_issue
• Extract upload-action into a standalone repository for independent versi - github / github_issue
• feat: add filecoin-pin get retrieval command - github / github_issue
• feat: add pagination to piece-status - github / github_issue
• data-set terminate: confirm skipProvider as the default termination path - github / github_issue
• investigate support for 1pass/lastpass/bitwarden secure vaults for priva - github / github_issue
• Add CLI error-scenario smoke test matrix for devs - github / github_issue
• v1.1.0 - github / github_release
• v1.0.1 - github / github_release
• v0.23.2 - github / github_release