CLI · @spfunctions/cli

The local CLI for live prediction markets.

sf queries Kalshi and Polymarket as one stream, exports structured JSON, and hands real market state to Claude Code, Codex, cron jobs, and shell agents.

read

sf world --json

market state

discover

sf discover --quality --json

topic graph

investigate

sf investigate "Fed rate cuts" --json --include query,econ,markets,tools

topic packet

handoff

sf describe --all --json

manifest

Installnpm install -g @spfunctions/cli

Quickstart·Reference·npm

Read state

sf world --json

Current regime, salient markets, live freshness, and next objects as JSON — about 800 tokens, no auth.

Investigate

sf investigate "Fed rate cuts" --json --include query,econ,markets,tools

A topic packet with prediction-market evidence, FRED rate series, traditional anchors, and next commands.

Agent handoff

sf describe --all --json

Recursive command manifest with auth, policy tags, JSON support, and side-effect metadata.

Commands.

Full reference →

Start here

01sf status --json

02sf world --json

03sf discover --quality --json

04sf investigate "topic" --json

05sf inspect <ticker> --json

Agent bootstrap

Ground the model in the installed surface before it starts guessing commands.

sf status --json

no authread-onlyJSON

Health, API, auth, exchange, runtime, and portfolio readiness.

sf doctor --agent --deep --json

no authdiagnosticJSON

Self-diagnosis for JSON contract, manifest truth, auth, and workflow readiness.

sf describe --all --json

no authmanifestJSON

Recursive command catalog with auth, policy tags, and side-effect metadata.

sf tools plan "task" --json

no authread-onlyagent-safe

Plan an ordered command sequence from the live local catalog.

Market state

Read live world, topic, market, and orderbook context before touching user state.

sf world --json

no authread-onlymarket data

Salience-ranked world state for agents, about 800 tokens, no auth.

sf discover --quality --json

no authread-onlyresearch

Ranked ideas, world, cross-venue, new-market, and contagion feed.

sf investigate "topic" --json

no authread-onlyagent-safe

Read-only packet that fuses world, query, econ, gov, traditional markets, and next commands.

sf inspect <ticker> --json

no authread-onlymarket dossier

Complete ticker dossier with regime, indicators, edges, suggestion, and next actions.

Operator state

Authenticated user context stays explicit: portfolio, thesis, watchlist, alerts, and traces.

sf me --json

auth requireduser dataread-only

Bounded boot context: status, portfolio, Kalshi, and Polymarket.

sf brief --agent --json

auth requireduser dataresearch

Compact user, workflow, and world brief for an agent loop.

sf watchlist add --ticker <ticker> --json

auth requiredwriteJSON

Save a watched market object for Plate, alerts, webhooks, and agents.

sf trace receipt trace.ndjson --json

no authdiagnosticread-only

Summarize recorded agent calls, risk classes, and receipt metadata.

Execution & runtime

Side-effecting surfaces are explicit, policy-tagged, and start in paper or intent mode.

sf intent buy <ticker> <qty> --json

auth requiredtradegated

Create a buy intent through the declarative execution gateway.

sf runtime start --smart

auth requiredruntimeside effects

Start the execution runtime with trigger evaluation and LLM soft conditions.

sf quote create <ticker> --paper

auth requiredpaper firsttrade surface

Create a market-making quote in paper mode before live venue mutation.

sf workflow demo monitor --dry-run --json

no authdry-runJSON

Dry-run watchlist, alert, webhook, and Plate workflow setup without mutating server state.

Read-only market state never asks for venue trading credentials. Authenticated and side-effecting commands stay explicit, policy-tagged, and inspectable.

Hand market state to your agent.

Discover the surface, read state, plan from the manifest, and keep side effects blocked until explicitly allowed. The most useful path for agent-native prediction market work.

read-first·JSON contract·side effects blocked·permission gated

Context packet

sf status --json
sf doctor --agent --deep --json
sf describe --all --json > sf-tools.json
sf world --json > sf-world.json
sf investigate "Fed rate cuts" --json --include query,econ,markets,tools

Run modes

sf agent --plain --allow read,user_data --once "Use sf-world.json and sf-tools.json to identify risks"
sf agent --headless --deny trade,runtime

Integration surfaces.

CLI is canonical. HTTP/Data API serves remote services and dashboards. SDK and Agent SDK are wrappers, not a second truth. MCP is compatibility for hosts that need it.

CLI

Primary

Local control plane for humans, scripts, coding agents, cron, policy-gated workflows, and every command that benefits from shell composition.

HTTP / Data API

Network surface

For services, notebooks, dashboards, remote workers, and clients that cannot shell out to sf.

SDK

In development

Typed clients over stable HTTP/Data API objects. The SDK wraps existing contracts; it is not a second truth.

Agent SDK / runtime

In development

Packages command selection, permission policy, traces, budgets, wake checks, and loop mechanics.

MCP adapter

Compatibility

For MCP-only hosts. Useful when a host requires MCP, but not the canonical product center.

Workflows.

Recognize the job, run the chain. Read-only research first, monitoring next, execution behind explicit gates.

Research loop

world → discover → investigate → inspect → thesis

Read-heavy, no venue credentials required.

read-onlyagent-safe

Agent loop

status → doctor → describe → tools plan → agent --plain

Ground the model in the installed surface before tool use.

manifestpermission gates

Monitoring loop

watchlist → alerts → webhooks → workflow demo monitor

Reactive objects instead of polling every market manually.

auth requireddry-run path

Execution loop

intent → runtime → fills → reconcile → trace receipt

Side effects stay declarative, inspectable, and replayable.

side-effect gatedauth required

Market making

book → quote create --paper → quoteengine start → quote list

Paper first, live only after venue credentials and risk gates.

paper firsttrade surface

224

CLI commands

Agent tools

Data endpoints

102

MCP adapters

Questions.

What package do I install?

Install @spfunctions/cli from npm with npm install -g @spfunctions/cli. The executable is sf.

What should I run first?

Run sf world --json to fetch the current world state, then use sf discover --quality --json, sf investigate "topic" --json, and sf inspect <ticker> --json for more specific market workflows.

Is this just a wrapper around Kalshi and Polymarket?

No. Venue aggregation is only the base layer. sf adds normalized market state, topic discovery, event dossiers, JSON contracts, workflow planning, traces, and agent-safe command surfaces.

Do I need venue credentials?

Read-only market state commands such as world, discover, investigate, inspect, book, and cross-venue do not require trading credentials. Portfolio, execution, user-data, runtime, alerts, webhooks, and live venue operations require auth or configured credentials.

Why CLI first?

Agents, scripts, and operators need a local, inspectable, composable surface before remote automation. The CLI is the fastest way to expose product truth to humans and coding agents.

Is MCP required?

No. MCP is a compatibility adapter for MCP-only hosts. CLI and HTTP/Data API remain the canonical surfaces.

Can commands place live trades?

Some direct trading commands can place live orders when trading is enabled and venue credentials are configured. For automation, prefer declarative intents, paper quote workflows, runtime gates, traces, and explicit allow or deny policy.