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