foc-cli

Store files on Filecoin. From your terminal. Or your AI agent.

Docs  •  Skills.sh  •  GitHub

---

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