SimpleFunctions CLI (sf)

A terminal-native prediction-market CLI. Query live Kalshi + Polymarket state, inspect markets, export structured JSON for agents, and gate execution from the shell. The installed binary is the source of truth; inspect the current command surface with sf describe --all --json.

$ sf world
# World State — 2026-04-09T13:00 UTC
SF Index v2: Disagree 57/100 | GeoRisk 35/100 | Breadth +0.33 | Activity 86/100

Markets: SPY $655.94 (+0.12%) | GLD $429.08 (-1.79%) | USO $138.18 (+11.99%)

## Geopolitical
- Will the U.S. invade Iran before 2027?: 54c (-7c)
- Russia x Ukraine ceasefire by end of 2026?: 30c

## Economy
- US recession by end of 2026?: 28c
- How many Fed rate cuts in 2026?: 0 (0 bps): 36c

Install

npm install -g @spfunctions/cli
sf login                # browser auth (recommended)
sf status               # verify everything works

What it does

World model — Real-time prediction index distilled from the active market universe. One command gives any LLM situational awareness.

sf world                    # ~800 token world state snapshot
sf world --delta            # what changed since last check (~30 tokens)
sf world --focus energy,geo # deep coverage on specific topics
sf ideas                    # S&T-style trade ideas with catalyst + risk

Thesis engine — Structured causal models with Bayesian node trees, continuous evaluation against live market data, and automatic edge detection.

sf thesis create 'Oil will exceed $120 by Q3 due to Hormuz disruption'
sf thesis list              # all theses with confidence + status
sf thesis context <id>      # causal tree + top edges + positions
sf thesis evaluate <id>     # trigger deep re-evaluation
sf thesis signal <id> "OPEC cuts"  # inject a signal for next eval cycle

Edge detection — Cross-venue scanner compares your model's probabilities against Kalshi and Polymarket prices.

sf edges                    # top mispricings across all theses
sf scan "recession"         # search live markets by keyword
sf book KXRECSSNBER-26      # orderbook depth
sf watch oil orderbook      # live terminal orderbook stream
sf watch "fed" all --smart  # LLM-filtered alerts + news divergence detection

Intent system — Declarative execution: describe what you want, the runtime handles when and how.

sf intent buy KXRECSSNBER-26 10 --price 30 --trigger below:28 --auto
sf intent list              # active intents + fill status
sf runtime start            # daemon evaluates triggers, executes orders

Interactive agent — Natural language interface over the installed sf command surface. Maintains a persistent workspace, shares context across sessions, and can schedule its own future actions.

sf agent <id>               # TUI agent with tool calling
sf agent <id> --once "summarize my portfolio risk"  # single-shot
sf agent <id> --plain       # readline mode, no TUI
sf telegram --daemon        # Telegram bot (text + voice)

Agent harness — Deterministic replay, budget + permission capsules.

sf agent <id> --record-trace /tmp/t.ndjson   # record session
sf agent <id> --replay-trace /tmp/t.ndjson   # replay offline
sf agent --budget-usd 5 --deny order         # constrained agent

Event subscription — Reactive agents. NDJSON stream or webhook push.

sf subscribe list
sf subscribe cancel <id>

Runtime controls — Local runtime commands keep side effects explicit. Cloud/remote runtime surfaces are not the canonical public workflow; use the local CLI and HTTP/Data API unless your account has a separately documented remote runtime enabled.

X / Twitter intelligence — Social signal layer.

sf x "tariff impact"        # discussion summary + top posts
sf x-volume "iran oil"      # volume and velocity trend
sf x-news "fed rate"        # Grok-aggregated news stories
sf x-account @elikinosian   # recent posts from an account

Setup

Quick (browser login)

sf login

Power user

sf setup                    # interactive wizard: API key, Kalshi, Polymarket, trading
sf setup --check            # show config status
sf setup --polymarket       # configure Polymarket wallet
sf setup --enable-trading   # unlock buy/sell/intent commands

Config is saved to ~/.sf/config.json. Environment variables override config values:

export SF_API_KEY=sf_live_xxx
export KALSHI_API_KEY_ID=xxx
export KALSHI_PRIVATE_KEY_PATH=~/.kalshi/private.pem

Verify

$ sf status
  API            ok  simplefunctions.dev 252ms
  Auth           ok  sf_live_8838...
  Kalshi         ok  $156.42 balance
  Polymarket     ok  0xd53b9354...
  Theses         ok  4 active, 4 total
  Trading        ok  enabled
  Runtime        --  not running (sf runtime start)
  Telegram       ok  PID 84372

Command Reference

World Model (no auth required)

| Command | Description | |---------|-------------| | sf world | Prediction index: markets + geopolitics + economy + crypto + elections | | sf world --delta | Changes since last check (~30 tokens, ideal for agent polling) | | sf world --focus <topics> | Deep coverage on specific topics | | sf ideas | Trade ideas with conviction, catalyst, direction, risk | | sf query "question" | LLM-enhanced market knowledge search | | sf markets | Traditional markets: SPY, VIX, bonds, gold, oil |

Thesis

| Command | Description | |---------|-------------| | sf thesis list | All theses with status, confidence, last update | | sf thesis get <id> | Full details: causal tree, edges, evaluation history | | sf thesis context <id> | Thesis context snapshot | | sf thesis create "thesis" | Create a new thesis | | sf thesis signal <id> "text" | Inject signal for next evaluation | | sf evaluate <id> | Trigger deep re-evaluation | | sf augment <id> | Evolve causal tree with new nodes | | sf heartbeat <id> | View/configure autonomous evaluation schedule + costs | | sf publish / sf unpublish <id> | Manage public visibility |

Markets

| Command | Description | |---------|-------------| | sf scan "keywords" | Search Kalshi + Polymarket by keyword | | sf scan --series TICKER | Browse all markets in a Kalshi series | | sf edges [--json] | Top mispricings across all theses | | sf watch [query] [mode] | Live market watch (modes: orderbook, flow, cross-venue, all) | | sf watch "q" --smart | LLM-filtered alerts + news divergence via monitor-the-situation | | sf watch "q" --smart --execute | Auto-create trading intents from detected signals | | sf book <ticker> [...] | Orderbook depth for specific markets | | sf whatif <id> | What-if scenario analysis on causal tree | | sf liquidity [topic] | Orderbook liquidity scanner | | sf forecast <event> | Market distribution (P50/P75/P90) | | sf explore [slug] | Browse public theses |

Portfolio

| Command | Description | |---------|-------------| | sf positions | Kalshi + Polymarket positions with P&L | | sf balance | Account balance | | sf orders | Resting (open) orders | | sf fills | Recent trade fills | | sf settlements | Settled contracts with final P&L | | sf performance | P&L over time with event annotations | | sf dashboard | Interactive TUI portfolio overview |

Intents & Runtime

Intents are declarative execution orders. You define the trade and trigger condition; the runtime daemon evaluates and executes.

| Command | Description | |---------|-------------| | sf intent buy <ticker> <qty> | Create buy intent (--trigger below:28, --trigger time:<ISO>, --soft "condition", --auto) | | sf intent sell <ticker> <qty> | Create sell intent | | sf intent list | Active intents (--all for history) | | sf intent status <id> | Detailed status + fills | | sf intent cancel <id> | Cancel an intent | | sf runtime start | Start execution daemon (Kalshi + Polymarket) | | sf runtime stop | Stop daemon | | sf runtime status | Active intents + runtime state | | sf backtest <ticker> | Strategy backtest (--entry-below 35 --stop 20 --tp 60 --days 30) | | sf heartbeat <id> | View/configure heartbeat + closed-loop (--closed-loop-entry, --closed-loop-exit) |

Trading (requires --enable-trading)

| Command | Description | |---------|-------------| | sf buy <ticker> <qty> | Buy contracts (--price 31, --market, --side yes\|no) | | sf sell <ticker> <qty> | Sell contracts | | sf cancel [orderId] | Cancel order(s) | | sf rfq <ticker> <qty> | Request for quote on large orders |

Agent

| Command | Description | |---------|-------------| | sf agent [id] | Interactive agent (TUI with panels) | | sf agent [id] --plain | Readline mode, pipe-friendly | | sf agent [id] --once "prompt" | Single-shot: run, answer, exit | | sf prompt [id] | Print dynamic system prompt for any LLM | | sf telegram [--daemon] | Telegram bot (text + voice messages) |

The agent uses the installed command manifest, including market scanning, trading, workspace read/write, X search, self-wake scheduling, and a math calculator. Check the exact surface with sf describe --all --json. Slash commands inside the agent include /voice /tree /edges /pos /eval /balance /intents /wakes /alerts /switch /model /help /exit.

X / Twitter

| Command | Description | |---------|-------------| | sf x "query" | Discussion summary + top posts | | sf x-volume "query" | Discussion volume and velocity trend | | sf x-news "query" | Grok-aggregated news stories | | sf x-account @username | Recent posts from a specific account |

Info

| Command | Description | |---------|-------------| | sf feed | Evaluation history stream | | sf delta <id> | Changes since last check | | sf milestones | Upcoming Kalshi events | | sf schedule | Exchange status | | sf announcements | Exchange announcements | | sf history <ticker> | Historical market data | | sf status | Full system health check |

Sharing

Any command with --share generates a short URL:

sf scan "gold" --share
sf query "fed rate" --share
sf context --share

JSON Output

Most commands support --json for machine-readable output:

sf thesis list --json
sf context f582bf76 --json
sf edges --json
sf world --json
sf ideas --json
sf discover --quality --json
sf brief --agent --json
sf intent list --json

For AI Agents

If you are an AI agent (Claude, GPT, Cursor, etc.), these are the commands that matter:

Setup

npm install -g @spfunctions/cli
sf login                          # or: export SF_API_KEY=sf_live_xxx
sf thesis list                           # verify: should print theses
sf doctor --agent --deep --json          # verify CLI JSON/manifest/auth surfaces

Primary commands

# World state in ~800 tokens — give your agent situational awareness
sf world --json

# Compact authenticated loop context: health, portfolio, workflow, world, gaps
sf brief --agent --json

# Quality-ranked opportunity queue across ideas/world/cross-venue/new/contagion
sf discover --quality --json

# What changed since last poll — ~30 tokens, efficient for loops
sf world --delta --json

# Thesis context: causal tree + edges + positions + evaluation
sf context <thesisId> --json

# Top mispricings across all theses
sf edges --json

# Single-shot agent: ask a question, get an answer, exit
sf agent <thesisId> --once "what is the biggest risk to my portfolio?"

Key JSON fields

sf context <id> --json returns:

{
  "confidence": 0.31,
  "causalTree": {
    "nodes": [{ "id": "n1", "label": "...", "probability": 0.95 }]
  },
  "edges": [{
    "marketId": "KXWTIMAX-26DEC31-T140",
    "venue": "kalshi",
    "marketPrice": 62,
    "thesisPrice": 95,
    "edge": 33
  }]
}

• confidence — overall thesis probability (0 to 1)
• edges[].edge — mispricing in cents (positive = market underpriced vs model)
• edges[].marketPrice — current market price (0-100 cents)

Patterns

# Monitor: poll world state, react to deltas
sf world --delta --json

# React to news: inject signal, re-evaluate, read updated state
sf signal <id> "Breaking: OPEC cuts production" --type news
sf evaluate <id>
sf context <id> --json

# Trade: create intent with trigger, let runtime execute
sf intent buy KXRECSSNBER-26 5 --price 30 --trigger below:28 --auto
sf runtime start

Error codes

| Error | Fix | |-------|-----| | "API key required" | sf login or set SF_API_KEY | | "Thesis not found" | sf thesis list to get valid IDs (8-char prefix works) | | "Kalshi not configured" | sf setup to add Kalshi credentials | | "Trading disabled" | sf setup --enable-trading |

Architecture

You ──→ sf agent ──→ LLM (Claude/GPT) ──→ sf command manifest
              │                                  │
              │         ┌────────────────────────┘
              ▼         ▼
         ┌─────────────────────┐
         │   SF API Server     │
         │  thesis · edges ·   │
         │  intents · eval ·   │
         │  proxy (LLM/TTS)    │
         └────────┬────────────┘
                  │
         ┌────────┴────────┐
         │                 │
    ┌────▼────┐     ┌──────▼──────┐
    │ Kalshi  │     │ Polymarket  │
    │  API    │     │    API      │
    └─────────┘     └─────────────┘

Local only (never leaves your machine):
  ~/.sf/config.json     — API keys, Kalshi private key path
  ~/.sf/workspace/      — agent scratchpad (notes, context logs)
  ~/.sf/wake/           — scheduled agent wake conditions
  ~/.sf/bus/            — daemon ↔ agent message bus
  ~/.sf/trade-journal.jsonl — local trade log

Kalshi credentials never leave your machine. Orders are signed locally with your RSA private key and sent directly to the Kalshi API. The SF server never sees your trading keys.

Local Development

cd cli
npm install
npm run dev -- list          # run without building
npm run build                # compile to dist/
npm run test                 # run tests
npm link                     # install as global 'sf' command

License

MIT