skill

foc-cli

CLI and AI agent skill for Filecoin Onchain Cloud — manage wallets, datasets, and storage providers using synapse-sdk

FIL-Builders/foc-clicommunitylistedunreviewed

Set up

Skills are installed by placing their folder where your agent loads skills.

Download ZIP from GitHub Open the repository

The download comes from github.com/FIL-Builders/foc-cli itself, not from our server, so what you get is exactly what its author published.

Install instructions come from the README

Skills do not use an MCP config. Follow the steps in the README below.

README

synced Oct 17, 2026

foc-cli is a command-line interface and AI agent skill for Filecoin Onchain Cloud (FOC) — decentralized warm storage on Filecoin with cryptographic proof your data is held (PDP), paid in USDFC stablecoin. Upload, download (with built-in cryptographic verification), and pay for storage from a terminal, a script, or an agent via MCP.

Quick Start

npx foc-cli wallet init --auto        # 1. Create a wallet
npx foc-cli wallet fund               # 2. Get testnet tokens
npx foc-cli wallet costs --extraBytes 1000000 --extraRunway 1   # 3. Estimate cost
npx foc-cli wallet deposit 1          # 4. Deposit 1 USDFC for storage
npx foc-cli upload ./myfile.pdf       # 5. Upload a file
npx foc-cli download <pieceCid>       # 6. Prove it's retrievable (pieceCid from upload output)

A successful download is cryptographic proof your file is stored and intact — the SDK validates the bytes against the piece CID.

Install

npm install -g foc-cli                    # CLI
npx skills add FIL-Builders/foc-cli       # Agent skills via skills.sh (Claude Code, Cursor, Copilot, 20+ tools)
npx foc-cli mcp add                       # MCP server (auto-detects your agent)

Commands

Every command supports -h for usage and --schema --format json for its JSON Schema. Flags are camelCase as documented (--withCDN); help shows kebab-case equivalents — both work. Boolean flags are presence-only switches (use --flag=false for an explicit value).

Group	Commands	Notes
Upload	`upload <path>` · `multi-upload <a,b>`	Auto provider/dataset. `--copies N`, `--withCDN`
Download	`download <pieceCid> [--out <path>]`	Bytes validated against the CID — retrieval is the verification
Wallet	`wallet init` · `balance` · `fund` · `deposit` · `withdraw` · `summary` · `costs`	`fund` = testnet faucet. `costs` = live estimate
Datasets	`dataset list` · `details` · `create` · `terminate`	`details` paginates pieces with next-page + fetch-all CTAs
Pieces	`piece list <id>` · `piece remove <id> <pieceId>`	Paginated with next-page + fetch-all CTAs
Providers	`provider list`	Approved PDP providers with location, pricing, performance
Docs	`docs --prompt "upload"` · `docs --url developer-guides/synapse.md`	Searches/fetches `docs.filecoin.cloud` only

Global options: --chain <id> (314159 testnet default, 314 mainnet) · --format toon|json|yaml|md · --json · --debug

Wallet & Keys

wallet init --auto for quick start, testnet, and automation. Use an encrypted Foundry keystore (--keystore <path>) when the wallet will hold real funds. A --privateKey flag exists for non-interactive setups — avoid it: raw keys in arguments leak into shell history and logs. Keep a dedicated wallet holding only what foc-cli needs.

Chains & Funding

All commands default to Calibration testnet; add --chain 314 for mainnet. Testnet tokens are one command (wallet fund). Mainnet needs real FIL for gas and USDFC for storage — see the funding guide.

Pricing: billed per copy per month by size (default 2 copies) plus a flat per-data-set monthly fee. wallet costs gives a live estimate; the upload itself re-quotes (and funds) at execution time.

Agent Skills

Skill	Purpose
foc-cli	Operations — setup, upload, download, wallets, datasets, pieces, providers
foc-docs	Documentation — search guides, SDK refs, concept explainers

Built with incur for first-class agent support:

MCP server — every command as an MCP tool (npx foc-cli --mcp)
Structured output — --json, --format yaml, --filter-output
Introspection — --schema per command, --llms manifest
TTY-aware — interactive prompts for humans, structured output for agents
Source tag — wallet init --source my-app sets the attribution tag reported to Synapse (default foc-cli)

How FOC Works

Layer	What it does
Storage	Warm, retrievable files via FWSS (Filecoin Warm Storage Service)
Verification	PDP — cryptographic proof providers hold your data
Settlement	Filecoin Pay — continuous USDFC payment streams to providers
Developer	Synapse SDK + this CLI

References

FOC Documentation · LLM-friendly docs · Synapse SDK · PDP Overview · Filecoin Pay

License

Apache-2.0 OR MIT