SimpleFunctions

Agentic CLI.

Agentic command line for prediction-market workflows. Human output is optional — structured state is the product.

Give agents structured access to market state, world deltas, portfolio history, user-owned context, and execution-ready next actions through a stable JSON protocol. The agentic CLI turns prediction-market data into a reliable command surface for AI agents, cron jobs, research scripts, and institutional workflows.

npm install -g @spfunctions/clinpm
Agentic Usage·Real-Time Data API·Kalshi CLI
Realist oil painting in Pieter de Hooch Dutch Golden Age workshop-genre style — the Plantin-Moretus printing workshop in Antwerp circa 1580, multiple typesetters and pressmen producing structured printed pages

Plantin-Moretus, 1580 — orchestrated stations producing reliably structured output.

Four jobs the CLI does

The agentic CLI lets an agent read state, pull user-owned context, inspect portfolio history, and discover tools — through one stable JSON protocol.

01

Read market and event state

Query Kalshi and Polymarket as one normalized surface, with implied probabilities, related contracts, traditional-market anchors, context, and next actions attached.

sf query "Fed rate cut" --json --limit 3
02

Pull user-owned context

For authenticated users, sf me exposes the agent's account context window — theses, evaluation feed, execution intents, API keys metadata, portfolio state — sensitive values redacted.

sf me theses --json
03

Inspect portfolio history

Reconstruct what happened in the portfolio manager: past ticks, handoff notes, actions taken, risk gates, trades, P&L attribution, user views, strategy instructions.

sf portfolio ticks --json --since 7d
04

Discover tools

sf describe --all --json returns the complete CLI tool manifest — names, args, auth requirements, read-only vs side-effecting, JSON-stable, examples, response schema hints. Agents call this before deciding what to invoke.

sf describe --all --json

Public read commands — no auth required

The minimum surface every agent gets. Stable JSON shape, idempotent, free.

Command
What it returns
sf query "<text>" --json --limit 3

Normalized markets across Kalshi + Polymarket with probabilities, related contracts, anchors, next actions

sf world --json

Compact world-state snapshot — what an agent should know about prediction markets right now

sf world --delta --json --since 1h

Only the changes since the last run — incremental context update

sf inspect <ticker> --json

Full structured dossier for one market: metadata, prices, liquidity, indicators, regime, follow-ups

sf describe --all --json

Tool manifest — every CLI command, args, schema, auth requirements, side-effect class

Portfolio commands — for authenticated agents

Reconstruct what happened in the portfolio manager. All reads are scoped to the authenticated user; the CLI never exposes another user's data.

Command
What it returns
sf portfolio status --json

Current portfolio state — positions, cash, exposure, drawdown, mode

sf portfolio ticks --json --limit 20 --since 7d

Recent evaluation ticks — what the portfolio manager saw and decided

sf portfolio tick <id> --json

Full record of one tick — handoff note, actions, risk gates, trades

sf portfolio trades --json --status open

Trades by status — open / filled / cancelled

sf portfolio views list --json

User-defined portfolio views the agent can read against

sf portfolio strategy list --json

Strategy instructions the user has saved for the portfolio manager

sf me — the agent's account context window

Theses, evaluation feed, execution intents, API keys metadata, portfolio context. Sensitive values redacted; scope is always the authenticated user.

Command
What it returns
sf me theses --json

User-authored theses with conviction, catalyst, risk

sf me feed --json --hours 24

Recent evaluation feed — what the system surfaced for this user

sf me intents --json

Execution intents the user has created — pending, working, terminal

sf me keys --json

API key metadata (no secrets) — when issued, last used, scope

sf me portfolio --json

High-level portfolio context for upstream agents

Tool discovery — sf describe --all --json

Before deciding what to call, agents fetch the manifest. Names, args, auth requirements, side-effect class, JSON-stable flag, examples, response schema hints.

sf describe --all --jsontool manifest excerpt
{
  "tools": [
    {
      "name":              "query",
      "args":              ["text", "--limit", "--json"],
      "auth":              "none",
      "side_effect":       "read",
      "json_stable":       true,
      "example":           "sf query \"Fed rate cut\" --json --limit 3",
      "response_schema":   { "markets": [ { "ticker": "string", "yesPrice": "number", "...": "..." } ] }
    },
    {
      "name":              "portfolio.ticks",
      "args":              ["--limit", "--since", "--json"],
      "auth":              "user",
      "side_effect":       "read",
      "json_stable":       true,
      "example":           "sf portfolio ticks --json --since 7d",
      "response_schema":   { "ticks": [ { "id": "string", "ts": "iso", "actions": "array", "...": "..." } ] }
    }
  ]
}

Where it fits

One CLI, many host environments. Same JSON shape, same tool registry, same authentication.

Claude Code

Spawn the CLI as a tool. Pipe --json output into the next prompt or assistant turn.

Codex / Cursor

Use sf describe --all --json once at session start to ground the available tool list, then call concretely.

Cron jobs

Cron + sf world --delta --json --since 1h → another model or dashboard. Quiet, scheduled context refresh.

Research scripts

Pipe sf inspect <ticker> through jq, redirect into a research database, or build a backtest input set.

Trading systems

sf portfolio ticks --json + sf portfolio trades drive risk monitors, dashboards, and reconciliation routines.

Internal LLM agents

sf describe --all becomes the machine-readable tool registry; the agent picks safe commands by side-effect class.

Quickstart

From zero to a piped JSON query in five lines.

terminal5 lines
npm install -g @spfunctions/cli
sf setup
sf query "Fed rate cut" --json --limit 3
sf portfolio ticks --json --since 7d
sf describe --all --json | jq '.tools[].name'

FAQ

What is an agentic CLI?

A command-line interface designed for an agent (or script, cron job, or research process) as the primary user — not a human at a terminal. Every command that supports --json returns valid machine-parseable JSON on stdout, including empty states and errors. Downstream systems can call it without scraping terminal text.

How is this different from a normal CLI?

A normal CLI optimizes for human readability — colored output, prose, progress bars. An agentic CLI optimizes for stable JSON, idempotent reads, predictable errors, and a tool registry the agent can introspect. Human output is optional; structured state is the product.

What can an agent do with the SimpleFunctions CLI?

Read prediction-market and event state, pull user-owned context from the user's SimpleFunctions account (theses, feed, intents, keys, portfolio), inspect portfolio history (ticks, trades, strategies, views), and discover what tools are available via sf describe --all --json before deciding what to call.

How do I install it?

npm install -g @spfunctions/cli — then sf setup walks through authentication. The CLI reads SF_API_KEY from the environment or your ~/.simplefunctions config; both are honored.

How does authentication work?

Public read commands (sf query, sf world, sf inspect) work unauthenticated. Authenticated commands (sf me, sf portfolio) require an API key; all reads are scoped to the authenticated user — the CLI never exposes another user's data.

What does sf describe --all --json return?

A machine-readable manifest of every CLI command — name, arguments, auth requirements, whether the command is read-only or side-effecting, whether the JSON shape is stable, examples, and response schema hints. Agents should fetch this once per session to ground their tool list.

What does --json guarantee?

Every --json output is valid JSON, including the empty case ({} / [] / null) and the error case ({"error": "..."}). No mixed prose, no warnings on stdout, no decoration. stderr is for human messages; stdout is for parseable state.

Can I pipe results into other tools?

Yes. sf query "Fed rate cut" --json | jq '.markets[] | .yesPrice' is the canonical pattern. The CLI is designed for piping — every command's --json shape is documented in sf describe.

Does the CLI support delta queries?

Yes. sf world --delta --json --since 1h returns only what changed since a relative or absolute timestamp. Useful for cron-driven context refresh and incremental agent state updates.

What's the relationship to the SimpleFunctions APIs?

The CLI is a thin client over the same APIs documented at /docs/api-reference. Anything you can do in the CLI you can do via HTTP; the CLI is the ergonomic surface for agents and operators that want shell-friendly tooling.

How does this compare to writing my own integration?

You absolutely can call the SimpleFunctions REST API directly from any language. The CLI saves the integration work — auth, JSON shape stability, retry logic, tool discovery, idempotency for write commands — for agents and scripts that just need a reliable command surface.

Is the CLI open source?

The CLI is published as @spfunctions/cli on npm. Tool descriptions, schemas, and examples are queryable via sf describe --all --json — agents can introspect the surface without reading source.

Related surfaces

Agentic Usage

Patterns for AI agents on real-time data and execution.

Real-Time Data API

Sub-second WebSocket + REST feed underlying the CLI reads.

Prediction Market Execution

Intents, triggers, routing — what sf intent commands wrap.

Prediction Market API

The REST API the CLI is a thin client over.

Kalshi CLI

Operator-focused command-line for Kalshi-specific workflows.

World State API

sf world --json source — compact world snapshot.

Agent Runtime Docs

Full agent runtime documentation including CLI integration.