Skip to content

Commit 9b6db20

Browse files
nijoe1nijoe1
committed
docs(readme): compact rewrite with verified quick start
Badges, one-table command map, quick start that walks init->fund->costs->deposit->upload->download (download doubles as the storage proof), wallet/key-safety and chain/funding sections that link the skill references. ClawHub install lines assume the skills are published there — publish first or drop that line before release. Closes #29.
1 parent f8e0580 commit 9b6db20

1 file changed

Lines changed: 51 additions & 122 deletions

File tree

‎README.md‎

Lines changed: 51 additions & 122 deletions
Original file line numberDiff line numberDiff line change
@@ -1,172 +1,101 @@
1+
<h1 align="center">foc-cli</h1>
2+
13
<p align="center">
2-
<strong>foc-cli</strong>
3-
<br/>
44
Store files on Filecoin. From your terminal. Or your AI agent.
55
</p>
66

7+
<p align="center">
8+
<a href="https://www.npmjs.com/package/foc-cli"><img src="https://img.shields.io/npm/v/foc-cli?color=0090ff&label=npm" alt="npm version"/></a>
9+
<a href="https://www.npmjs.com/package/foc-cli"><img src="https://img.shields.io/node/v/foc-cli?color=339933&label=node" alt="node version"/></a>
10+
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0%20OR%20MIT-blue" alt="license"/></a>
11+
</p>
12+
713
<p align="center">
814
<a href="https://docs.filecoin.cloud">Docs</a> &nbsp;&bull;&nbsp;
915
<a href="https://skills.sh">Skills.sh</a> &nbsp;&bull;&nbsp;
16+
<a href="https://clawhub.ai">ClawHub</a> &nbsp;&bull;&nbsp;
1017
<a href="https://github.com/FIL-Builders/foc-cli">GitHub</a>
1118
</p>
1219

1320
---
1421

15-
**foc-cli** is a CLI and AI agent skill for [Filecoin Onchain Cloud](https://docs.filecoin.cloud) (FOC) — decentralized warm storage with cryptographic proof your data is held, paid with USDFC stablecoin on Filecoin.
16-
17-
**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.
18-
19-
## Install
20-
21-
**As a CLI:**
22-
23-
```bash
24-
npm install -g foc-cli
25-
```
26-
27-
**As an AI Agent Skill** via [skills.sh](https://skills.sh) — works with Claude Code, Cursor, Copilot, Codex, Windsurf, and 20+ AI tools:
28-
29-
```bash
30-
# Install all skills (CLI + docs)
31-
npx skills add FIL-Builders/foc-cli
32-
33-
# Or install individually
34-
npx skills add FIL-Builders/foc-cli --skill foc-cli # CLI & operations
35-
npx skills add FIL-Builders/foc-cli --skill foc-docs # Documentation search
36-
```
37-
38-
**As an MCP server** for direct tool access:
39-
40-
```bash
41-
npx foc-cli mcp add # Auto-detect your agent
42-
npx foc-cli mcp add --agent claude-code # Specific agent
43-
```
22+
**foc-cli** is a command-line interface and AI agent skill for [Filecoin Onchain Cloud](https://docs.filecoin.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.
4423

4524
## Quick Start
4625

4726
```bash
4827
npx foc-cli wallet init --auto # 1. Create a wallet
4928
npx foc-cli wallet fund # 2. Get testnet tokens
50-
npx foc-cli wallet deposit 1 # 3. Deposit 1 USDFC for storage
51-
npx foc-cli upload ./myfile.pdf # 4. Upload a file
29+
npx foc-cli wallet costs --extraBytes 1000000 --extraRunway 1 # 3. Estimate cost
30+
npx foc-cli wallet deposit 1 # 4. Deposit 1 USDFC for storage
31+
npx foc-cli upload ./myfile.pdf # 5. Upload a file
32+
npx foc-cli download <pieceCid> # 6. Prove it's retrievable (pieceCid from upload output)
5233
```
5334

54-
That's it. Your file is now stored on Filecoin with PDP verification and redundant copies.
55-
56-
## Skills
57-
58-
This package ships two focused skills for AI agents:
59-
60-
| Skill | Purpose | When to use |
61-
|-------|---------|-------------|
62-
| **foc-cli** | CLI & Operations | Setup, upload, wallets, datasets, pieces, providers — everything operational. |
63-
| **foc-docs** | Documentation | Search guides, SDK refs, concept explainers. |
64-
65-
## Commands
66-
67-
Every command supports `-h` for full usage details.
35+
A successful `download` is cryptographic proof your file is stored and intact — the SDK validates the bytes against the piece CID.
6836

69-
### Upload
37+
## Install
7038

7139
```bash
72-
npx foc-cli upload <path> # Upload with auto provider/dataset
73-
npx foc-cli upload <path> --withCDN --copies 3 # CDN + 3 redundant copies
74-
npx foc-cli multi-upload ./a.pdf,./b.pdf # Batch upload; all paths must be readable
40+
npm install -g foc-cli # CLI
41+
npx skills add FIL-Builders/foc-cli # Agent skills via skills.sh (Claude Code, Cursor, Copilot, 20+ tools)
42+
clawhub install foc-cli && clawhub install foc-docs # Agent skills via ClawHub (OpenClaw)
43+
npx foc-cli mcp add # MCP server (auto-detects your agent)
7544
```
7645

77-
### Wallet
46+
## Commands
7847

79-
```bash
80-
npx foc-cli wallet init [--auto|--keystore <path>|--privateKey <key>]
81-
npx foc-cli wallet balance # Check FIL & USDFC balances
82-
npx foc-cli wallet fund # Testnet faucet
83-
npx foc-cli wallet deposit <amount> # Deposit USDFC for storage
84-
npx foc-cli wallet withdraw <amount> # Withdraw USDFC
85-
npx foc-cli wallet summary # Funding timeline & rates
86-
npx foc-cli wallet costs --extraBytes <n> --extraRunway <months>
87-
```
48+
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).
8849

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

91-
```bash
92-
npx foc-cli dataset list # List all datasets
93-
npx foc-cli dataset details -d <id> # Metadata + pieces
94-
npx foc-cli dataset create <providerId> [--cdn] # Create dataset
95-
npx foc-cli dataset upload <path> <providerId> # Create + upload
96-
npx foc-cli dataset terminate <dataSetId> # Terminate dataset
97-
```
60+
**Global options:** `--chain <id>` (`314159` testnet default, `314` mainnet) · `--format toon|json|yaml|md` · `--json` · `--debug`
9861

99-
### Pieces & Providers
62+
## Wallet & Keys
10063

101-
```bash
102-
npx foc-cli piece list <dataSetId> # List pieces in dataset
103-
npx foc-cli piece remove <dataSetId> <pieceId> # Remove piece
104-
npx foc-cli provider list # Approved PDP providers
105-
```
64+
`wallet init --auto` for quick start, testnet, and automation. Use an encrypted [Foundry keystore](skills/foc-cli/references/keystore-setup.md) (`--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.
10665

107-
### Docs
66+
## Chains & Funding
10867

109-
```bash
110-
npx foc-cli docs # Browse docs index
111-
npx foc-cli docs --prompt "upload files" # Search by topic
112-
npx foc-cli docs --url <url> # Fetch specific page
113-
```
68+
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](skills/foc-cli/references/mainnet-funding.md).
11469

115-
### Global Options
70+
**Pricing:** billed per copy per month by size (default 2 copies) plus a flat per-data-set monthly fee. `wallet costs` is the source of truth.
11671

117-
| Option | Default | Description |
118-
|--------|---------|-------------|
119-
| `--chain <id>` / `-c` | `314159` | Chain ID (`314159` = testnet, `314` = mainnet) |
120-
| `--debug` | `false` | Verbose error logging |
121-
| `--format <fmt>` | `toon` | Output format: `toon`, `json`, `yaml`, `md` |
122-
| `--json` | | Shorthand for `--format json` |
72+
## Agent Skills
12373

124-
### Source tag
74+
| Skill | Purpose |
75+
|-------|---------|
76+
| [**foc-cli**](skills/foc-cli/SKILL.md) | Operations — setup, upload, download, wallets, datasets, pieces, providers |
77+
| [**foc-docs**](skills/foc-docs/SKILL.md) | Documentation — search guides, SDK refs, concept explainers |
12578

126-
The `source` string the CLI reports to Synapse/Warm Storage (telemetry & attribution) is stored in your config. Set it to identify your app or integration (defaults to `foc-cli`):
79+
Built with [incur](https://github.com/wevm/incur) for first-class agent support:
12780

128-
```bash
129-
npx foc-cli wallet init --source my-app
130-
```
81+
- **MCP server** — every command as an MCP tool (`npx foc-cli --mcp`)
82+
- **Structured output** — `--json`, `--format yaml`, `--filter-output`
83+
- **Introspection** — `--schema` per command, `--llms` manifest
84+
- **TTY-aware** — interactive prompts for humans, structured output for agents
85+
- **Source tag** — `wallet init --source my-app` sets the attribution tag reported to Synapse (default `foc-cli`)
13186

13287
## How FOC Works
13388

134-
FOC transforms Filecoin into a **programmable cloud storage layer**:
135-
13689
| Layer | What it does |
13790
|-------|-------------|
13891
| **Storage** | Warm, retrievable files via FWSS (Filecoin Warm Storage Service) |
139-
| **Verification** | PDP (Proof of Data Possession) — cryptographic proof providers hold your data |
92+
| **Verification** | PDP — cryptographic proof providers hold your data |
14093
| **Settlement** | Filecoin Pay — continuous USDFC payment streams to providers |
141-
| **Developer** | Synapse SDK + this CLI — TypeScript APIs for storage, payments, retrieval |
142-
143-
**Pricing:** $2.5/TiB/month per copy (minimum 2 copies). Minimum spend: 0.06 USDFC/month (~24 GiB).
144-
145-
## Agent Features
146-
147-
Built with [incur](https://github.com/wevm/incur) for first-class AI agent support:
148-
149-
- **MCP Server** — all commands as MCP tools (`npx foc-cli --mcp`)
150-
- **Structured Output** — `--json`, `--format yaml`, `--token-count`
151-
- **Schema Introspection** — `npx foc-cli <cmd> --schema` for JSON Schema
152-
- **LLM Manifest** — `npx foc-cli --llms` for machine-readable docs
153-
- **TTY Awareness** — interactive prompts for humans, structured output for agents
154-
155-
## Mainnet
156-
157-
All commands default to **Calibration testnet**. Add `--chain 314` for mainnet:
158-
159-
```bash
160-
npx foc-cli upload ./data.bin --chain 314
161-
```
94+
| **Developer** | Synapse SDK + this CLI |
16295

16396
## References
16497

165-
- [FOC Documentation](https://docs.filecoin.cloud)
166-
- [LLM-friendly docs](https://docs.filecoin.cloud/llms.txt)
167-
- [Synapse SDK](https://github.com/FilOzone/synapse-sdk)
168-
- [PDP Overview](https://docs.filecoin.cloud/core-concepts/pdp-overview/)
169-
- [Filecoin Pay](https://docs.filecoin.cloud/core-concepts/filecoin-pay-overview/)
98+
[FOC Documentation](https://docs.filecoin.cloud) · [LLM-friendly docs](https://docs.filecoin.cloud/llms.txt) · [Synapse SDK](https://github.com/FilOzone/synapse-sdk) · [PDP Overview](https://docs.filecoin.cloud/core-concepts/pdp-overview/) · [Filecoin Pay](https://docs.filecoin.cloud/core-concepts/filecoin-pay-overview/)
17099

171100
## License
172101

0 commit comments

Comments
 (0)