|
1 | | -# SimpleFunctions CLI (`sf`) |
| 1 | +# SimpleFunctions CLI |
2 | 2 |
|
3 | | -Prediction market intelligence CLI. Build causal thesis models, scan Kalshi/Polymarket for mispricings, detect edges, and trade — all from the terminal. |
| 3 | +[](https://www.npmjs.com/package/@spfunctions/cli) |
| 4 | +[](https://github.com/spfunctions/simplefunctions-cli/blob/main/LICENSE) |
4 | 5 |
|
5 | | - |
| 6 | +Prediction market intelligence from the terminal. Build causal thesis models, scan Kalshi & Polymarket for mispricings, and trade. |
6 | 7 |
|
7 | | -## Quick Start |
8 | | - |
9 | | -```bash |
10 | | -npm install -g @spfunctions/cli |
11 | | -sf setup # interactive config wizard |
12 | | -sf list # see your theses |
13 | | -sf context <id> --json # get thesis state as JSON |
14 | | -``` |
15 | | - |
16 | | -## Setup |
17 | | - |
18 | | -### Interactive (recommended) |
| 8 | +## Install |
19 | 9 |
|
20 | 10 | ```bash |
| 11 | +npm i -g @spfunctions/cli |
21 | 12 | sf setup |
22 | 13 | ``` |
23 | 14 |
|
24 | | -This walks you through: |
25 | | -1. **SF API key** (required) — get one at [simplefunctions.dev](https://simplefunctions.dev) |
26 | | -2. **Kalshi credentials** (optional) — for positions, trading, and orderbook data |
27 | | -3. **Trading mode** (optional) — enable `sf buy`/`sf sell` commands |
28 | | - |
29 | | -Config is saved to `~/.sf/config.json`. Environment variables override config values. |
30 | | - |
31 | | -### Manual |
32 | | - |
33 | | -```bash |
34 | | -export SF_API_KEY=sf_live_xxx # required |
35 | | -export KALSHI_API_KEY_ID=xxx # optional, for positions/trading |
36 | | -export KALSHI_PRIVATE_KEY_PATH=~/.ssh/kalshi.pem # optional, for positions/trading |
37 | | -``` |
38 | | - |
39 | | -### Verify |
40 | | - |
41 | | -```bash |
42 | | -sf setup --check # show current config status |
43 | | -sf list # should show your theses |
44 | | -``` |
45 | | - |
46 | | -## Commands |
47 | | - |
48 | | -### Thesis Management |
49 | | - |
50 | | -| Command | Description | |
51 | | -|---------|-------------| |
52 | | -| `sf list` | List all theses with status, confidence, and update time | |
53 | | -| `sf get <id>` | Full thesis details: causal tree, edges, positions, last evaluation | |
54 | | -| `sf context <id>` | Compact context snapshot (primary command for agents) | |
55 | | -| `sf create "thesis"` | Create a new thesis (waits for formation by default) | |
56 | | -| `sf signal <id> "text"` | Inject a signal (news, observation) for next evaluation | |
57 | | -| `sf evaluate <id>` | Trigger deep evaluation with heavy model | |
58 | | -| `sf publish <id>` | Make thesis publicly viewable | |
59 | | -| `sf unpublish <id>` | Remove from public view | |
60 | | - |
61 | | -### Market Exploration (no auth required) |
| 15 | +## Key Commands |
62 | 16 |
|
63 | | -| Command | Description | |
| 17 | +| Command | What it does | |
64 | 18 | |---------|-------------| |
65 | | -| `sf scan "keywords"` | Search Kalshi markets by keyword | |
66 | | -| `sf scan --series KXWTIMAX` | List all markets in a series | |
67 | | -| `sf scan --market TICKER` | Get single market detail | |
68 | | -| `sf explore` | Browse public theses | |
69 | | - |
70 | | -### Portfolio & Trading (requires Kalshi credentials) |
71 | | - |
72 | | -| Command | Description | |
73 | | -|---------|-------------| |
74 | | -| `sf edges` | Top edges across all theses — what to trade now | |
75 | | -| `sf positions` | Current positions with P&L and edge overlay | |
76 | | -| `sf balance` | Account balance | |
77 | | -| `sf orders` | Resting (open) orders | |
78 | | -| `sf fills` | Recent trade fills | |
79 | | -| `sf performance` | P&L over time with thesis event annotations | |
80 | | -| `sf settlements` | Settled contracts with final P&L | |
81 | | -| `sf liquidity` | Market liquidity scanner by topic | |
82 | | - |
83 | | -### Trading (requires `sf setup --enable-trading`) |
84 | | - |
85 | | -| Command | Description | |
86 | | -|---------|-------------| |
87 | | -| `sf buy <ticker> <qty>` | Buy contracts | |
88 | | -| `sf sell <ticker> <qty>` | Sell contracts | |
89 | | -| `sf cancel [orderId]` | Cancel order(s) | |
90 | | -| `sf rfq <ticker> <qty>` | Request for quote on large orders | |
91 | | - |
92 | | -### Analysis |
93 | | - |
94 | | -| Command | Description | |
95 | | -|---------|-------------| |
96 | | -| `sf whatif <id>` | What-if scenario: "if node X drops to 10%..." | |
97 | | -| `sf feed` | Evaluation history stream | |
98 | | -| `sf forecast <event>` | Market distribution forecast (P50/P75/P90) | |
99 | | -| `sf dashboard` | Interactive TUI portfolio overview | |
100 | | - |
101 | | -### Interactive Modes |
102 | | - |
103 | | -| Command | Description | |
104 | | -|---------|-------------| |
105 | | -| `sf agent [id]` | Interactive agent with natural language + tool calling | |
106 | | -| `sf telegram` | Telegram bot for monitoring and trading | |
107 | | - |
108 | | -## JSON Output |
109 | | - |
110 | | -Most commands support `--json` for machine-readable output: |
111 | | - |
112 | | -```bash |
113 | | -sf list --json |
114 | | -sf context f582bf76 --json |
115 | | -sf edges --json |
116 | | -sf scan "oil" --json |
117 | | -sf get f582bf76 --json |
118 | | -``` |
119 | | - |
120 | | -## For AI Agents |
| 19 | +| `sf list` | List your theses with confidence scores and status | |
| 20 | +| `sf context <id> --json` | Full thesis state as structured JSON (for agents) | |
| 21 | +| `sf scan "topic"` | Search Kalshi/Polymarket markets by keyword | |
| 22 | +| `sf edges` | Top mispricings across all your theses | |
| 23 | +| `sf signal <id> "news"` | Inject a signal for the next evaluation cycle | |
| 24 | +| `sf agent` | Interactive agent with natural language + tool calling | |
121 | 25 |
|
122 | | -**If you are an AI coding agent (Claude, GPT, OpenClaw, Cursor, etc.), follow these steps:** |
| 26 | +All commands support `--json` for machine-readable output. |
123 | 27 |
|
124 | | -### Step 1: Install and configure |
| 28 | +## MCP Server |
125 | 29 |
|
126 | | -```bash |
127 | | -npm install -g @spfunctions/cli |
128 | | -sf setup --key sf_live_YOUR_KEY_HERE |
129 | | -``` |
130 | | - |
131 | | -If `sf setup` is not available or you cannot run interactive commands: |
132 | | -```bash |
133 | | -export SF_API_KEY=sf_live_YOUR_KEY_HERE |
134 | | -``` |
135 | | - |
136 | | -### Step 2: Verify it works |
| 30 | +Connect SimpleFunctions to Claude, Cursor, or any MCP-compatible client: |
137 | 31 |
|
138 | 32 | ```bash |
139 | | -sf list |
140 | | -``` |
141 | | - |
142 | | -Expected output (table format): |
| 33 | +claude mcp add simplefunctions --url https://simplefunctions.dev/api/mcp/mcp |
143 | 34 | ``` |
144 | | -ID Status Conf Updated Title |
145 | | -f582bf76 active 82% Mar 12 11:13 Oil prices will exceed $100... |
146 | | -a1b2c3d4 active 65% Mar 11 09:30 Fed will cut rates by June... |
147 | | -``` |
148 | | - |
149 | | -If you see theses, the CLI is working. If you see an error, check that `SF_API_KEY` is set correctly. |
150 | 35 |
|
151 | | -### Step 3: Get thesis context (most important command) |
| 36 | +Listed on the [MCP Registry](https://registry.modelcontextprotocol.io). |
152 | 37 |
|
153 | | -```bash |
154 | | -sf context <thesisId> --json |
155 | | -``` |
156 | | - |
157 | | -This returns a JSON object with the complete thesis state: |
158 | | - |
159 | | -```json |
160 | | -{ |
161 | | - "thesisId": "f582bf76-3113-4208-b0c1-...", |
162 | | - "thesis": "Oil prices will exceed $100 by end of 2026", |
163 | | - "title": "Oil Bull Thesis", |
164 | | - "status": "active", |
165 | | - "confidence": 0.82, |
166 | | - "causalTree": { |
167 | | - "rootClaim": "Oil prices will exceed $100", |
168 | | - "nodes": [ |
169 | | - { |
170 | | - "id": "n1", |
171 | | - "label": "Supply disruption", |
172 | | - "probability": 0.75, |
173 | | - "importance": 0.6, |
174 | | - "depth": 0 |
175 | | - } |
176 | | - ] |
177 | | - }, |
178 | | - "edges": [ |
179 | | - { |
180 | | - "marketId": "KXWTIMAX-26DEC31-T100", |
181 | | - "market": "Will oil exceed $100 by Dec 2026?", |
182 | | - "venue": "kalshi", |
183 | | - "direction": "yes", |
184 | | - "marketPrice": 35, |
185 | | - "thesisPrice": 55, |
186 | | - "edge": 20, |
187 | | - "confidence": 0.8 |
188 | | - } |
189 | | - ], |
190 | | - "lastEvaluation": { |
191 | | - "summary": "Supply concerns rising due to...", |
192 | | - "newConfidence": 0.82, |
193 | | - "confidenceDelta": 0.03 |
194 | | - } |
195 | | -} |
196 | | -``` |
197 | | - |
198 | | -**Key fields:** |
199 | | -- `confidence` — overall thesis probability (0 to 1) |
200 | | -- `edges[].edge` — mispricing size in cents (positive = market underpriced vs thesis) |
201 | | -- `edges[].marketPrice` — current market price in cents (0-100) |
202 | | -- `edges[].thesisPrice` — what the thesis model thinks the price should be |
203 | | -- `lastEvaluation.summary` — human-readable summary of latest analysis |
204 | | - |
205 | | -### Step 4: Other useful commands |
206 | | - |
207 | | -```bash |
208 | | -# Inject a signal for the thesis to consider in its next evaluation |
209 | | -sf signal <thesisId> "Breaking: OPEC announces production cut" --type news |
| 38 | +## Documentation |
210 | 39 |
|
211 | | -# View top edges (mispricings) across all theses |
212 | | -sf edges --json |
| 40 | +Full docs, API reference, and guides: **[simplefunctions.dev/docs](https://simplefunctions.dev/docs)** |
213 | 41 |
|
214 | | -# Search Kalshi markets by keyword |
215 | | -sf scan "recession" --json |
| 42 | +## License |
216 | 43 |
|
217 | | -# Trigger a deep re-evaluation |
218 | | -sf evaluate <thesisId> |
219 | | - |
220 | | -# What-if analysis: what happens if a node probability changes? |
221 | | -sf whatif <thesisId> |
222 | | -``` |
223 | | - |
224 | | -### Common patterns for agents |
225 | | - |
226 | | -**Monitor a thesis:** |
227 | | -```bash |
228 | | -sf context <id> --json # poll periodically, check confidence changes |
229 | | -``` |
230 | | - |
231 | | -**React to news:** |
232 | | -```bash |
233 | | -sf signal <id> "Reuters: Iran nuclear deal collapses" --type news |
234 | | -sf evaluate <id> # trigger re-evaluation after injecting signal |
235 | | -sf context <id> --json # read updated state |
236 | | -``` |
237 | | - |
238 | | -**Find trading opportunities:** |
239 | | -```bash |
240 | | -sf edges --json # get top mispricings sorted by edge size |
241 | | -``` |
242 | | - |
243 | | -### Error handling |
244 | | - |
245 | | -- **"API key required"** — set `SF_API_KEY` env var or run `sf setup --key <key>` |
246 | | -- **"Thesis not found"** — use `sf list` to get valid thesis IDs. IDs can be short prefixes (first 8 chars) |
247 | | -- **"Kalshi not configured"** — positions/trading commands need Kalshi credentials via `sf setup` |
248 | | -- **Exit code 0** — success. **Exit code 1** — error (message printed to stderr) |
249 | | - |
250 | | -## Local Development |
251 | | - |
252 | | -```bash |
253 | | -cd cli |
254 | | -npm install |
255 | | -npm run dev -- list # run without building |
256 | | -npm run build # compile to dist/ |
257 | | -npm run test # run unit tests |
258 | | -npm link # install as global 'sf' command |
259 | | -``` |
| 44 | +MIT |
0 commit comments