foc-cli
Store files on Filecoin. From your terminal. Or your AI agent.

Docs  •  Skills.sh  •  GitHub

---

foc-cli is a CLI and AI agent skill for Filecoin Onchain Cloud (FOC) — decentralized warm storage with cryptographic proof your data is held, paid with USDFC stablecoin on Filecoin.

Why FOC? Traditional cloud storage requires trusting a provider. FOC gives you onchain verification (PDP proofs), programmable payments, and redundant copies across independent storage providers — all through a simple CLI or AI agent skill.

Install

As a CLI:

npm install -g foc-cli

As an AI Agent Skill via skills.sh — works with Claude Code, Cursor, Copilot, Codex, Windsurf, and 20+ AI tools:

# Install all skills (CLI + docs)
npx skills add FIL-Builders/foc-cli

# Or install individually
npx skills add FIL-Builders/foc-cli --skill foc-cli  # CLI & operations
npx skills add FIL-Builders/foc-cli --skill foc-docs   # Documentation search

As an MCP server for direct tool access:

npx foc-cli mcp add                       # Auto-detect your agent
npx foc-cli mcp add --agent claude-code   # Specific agent

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 deposit 1          # 3. Deposit 1 USDFC for storage
npx foc-cli upload ./myfile.pdf       # 4. Upload a file

That's it. Your file is now stored on Filecoin with PDP verification and redundant copies.

Skills

This package ships two focused skills for AI agents:

Skill	Purpose	When to use
foc-cli	CLI & Operations	Setup, upload, wallets, datasets, pieces, providers — everything operational.
foc-docs	Documentation	Search guides, SDK refs, concept explainers.

Commands

Every command supports -h for full usage details.

Upload

npx foc-cli upload <path>                        # Upload with auto provider/dataset
npx foc-cli upload <path> --withCDN --copies 3   # CDN + 3 redundant copies
npx foc-cli multi-upload ./a.pdf,./b.pdf         # Batch upload

Wallet

npx foc-cli wallet init [--auto|--keystore <path>|--privateKey <key>]
npx foc-cli wallet balance             # Check FIL & USDFC balances
npx foc-cli wallet fund                # Testnet faucet
npx foc-cli wallet deposit <amount>    # Deposit USDFC for storage
npx foc-cli wallet withdraw <amount>   # Withdraw USDFC
npx foc-cli wallet summary             # Funding timeline & rates
npx foc-cli wallet costs --extraBytes <n> --extraRunway <months>

Datasets

npx foc-cli dataset list                          # List all datasets
npx foc-cli dataset details -d <id>               # Metadata + pieces
npx foc-cli dataset create [providerId] [--cdn]   # Create dataset
npx foc-cli dataset upload <path> <providerId>    # Create + upload
npx foc-cli dataset terminate <dataSetId>         # Terminate dataset

Pieces & Providers

npx foc-cli piece list <dataSetId>                # List pieces in dataset
npx foc-cli piece remove <dataSetId> <pieceId>    # Remove piece
npx foc-cli provider list                         # Approved PDP providers

Docs

npx foc-cli docs                                  # Browse docs index
npx foc-cli docs --prompt "upload files"          # Search by topic
npx foc-cli docs --url <url>                      # Fetch specific page

Global Options

Option	Default	Description
--chain <id> / -c	314159	Chain ID (314159 = testnet, 314 = mainnet)
--debug	false	Verbose error logging
--format <fmt>	toon	Output format: toon, json, yaml, md
--json		Shorthand for --format json

How FOC Works

FOC transforms Filecoin into a programmable cloud storage layer:

Layer	What it does
Storage	Warm, retrievable files via FWSS (Filecoin Warm Storage Service)
Verification	PDP (Proof of Data Possession) — cryptographic proof providers hold your data
Settlement	Filecoin Pay — continuous USDFC payment streams to providers
Developer	Synapse SDK + this CLI — TypeScript APIs for storage, payments, retrieval

Pricing: $2.5/TiB/month per copy (minimum 2 copies). Minimum spend: 0.06 USDFC/month (~24 GiB).

Agent Features

Built with incur for first-class AI agent support:

• MCP Server — all commands as MCP tools (npx foc-cli --mcp)
• Structured Output — --json, --format yaml, --token-count
• Schema Introspection — npx foc-cli <cmd> --schema for JSON Schema
• LLM Manifest — npx foc-cli --llms for machine-readable docs
• TTY Awareness — interactive prompts for humans, structured output for agents

Mainnet

All commands default to Calibration testnet. Add --chain 314 for mainnet:

npx foc-cli upload ./data.bin --chain 314

References

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

License

Apache-2.0 OR MIT