> ## Documentation Index > Fetch the complete documentation index at: https://docs.simplefunctions.dev/llms.txt > Use this file to discover all available pages before exploring further. # Agentic CLI > Use SimpleFunctions CLI as an agent control plane for prediction-market workflows. SimpleFunctions CLI is an agentic command-line interface for reading, reasoning over, and operating on prediction-market state. It is not mainly a human terminal renderer. The primary user is an agent, script, trading workflow, research process, or institutional system that needs reliable structured access to SimpleFunctions data. The CLI is not the Agent SDK. It is the local command surface and direct-tool runner for operators, shell scripts, cron, Claude Code, Codex, and Cursor. `@spfunctions/agent` is the embeddable TypeScript Agent SDK with `Agent.create().send().stream()`; it does not shell out to the CLI. ## What the CLI does The CLI lets an agent do these jobs: 1. Read market and event state. 2. Pull user-owned context from the SimpleFunctions account. 3. Inspect portfolio history, ticks, trades, strategies, and views. 4. Self-diagnose JSON, manifest, auth, workflow, and runtime readiness. 5. Fuse public research surfaces into one investigation packet. 6. Pull a compact authenticated brief for long-running loops. 7. Discover quality-ranked market opportunities without scraping every raw source. 8. Discover available tools and safely decide what to call next. 9. Manage watched objects, alerts, webhooks, monitors, and delivery state. ## Public market state ```bash theme={null} sf query "Fed rate cut" --json --limit 3 sf investigate "CPI oil energy" --json --limit 5 ``` Returns: * normalized Kalshi markets * normalized Polymarket markets * implied probabilities * related contracts * traditional-market anchors * source context * next actions `sf investigate` is the read-only research router. It calls public world, query, econ, gov, traditional-market, and tool-planning surfaces, tolerates partial failures, and returns evidence plus next commands in one envelope. ## Opportunity discovery ```bash theme={null} sf discover --quality --json --limit 10 sf discover --quality --category macro --json --limit 10 ``` `sf discover` is the read-only opportunity router. It aggregates trade ideas, world opportunities, cross-venue pairs, new markets, and contagion gaps into one ranked list. Use `--quality` for the default agent feed. It filters noisy sports, esports, crypto micro-window, penny-pair, and empty-liquidity candidates, then applies a diversity pass so one signal family does not fill the entire response. ## World state ```bash theme={null} sf world --json sf world --delta --json --since 1h ``` Use world snapshots when an agent needs compact context. Use deltas when a long-running agent only needs changes since its last run. ## Market inspection ```bash theme={null} sf inspect KXRATECUT-26DEC31 --json ``` Returns a structured dossier for one market: market metadata, prices, liquidity, indicators, regime state, related surfaces, and follow-up actions. ## Account context ```bash theme={null} sf doctor --agent --deep --json sf guide --agent --json sf brief --agent --json sf me --json --detail --limit 10 sf me theses --json --limit 10 sf me feed --json --hours 24 --limit 20 sf me intents --json sf me keys --json sf me portfolio --json --limit 10 ``` `sf me` is the agent's bounded user context window. It exposes account-scoped status, portfolio, Kalshi, Polymarket, and next-action context while redacting sensitive values and omitting huge handoff notes. `sf brief --agent --json` is the compact authenticated loop context. It summarizes local health, account config, portfolio automation state, watchlist, alert rules, recent alert deliveries, webhook endpoints, world state, gaps, and next commands. It does not print raw user IDs, webhook signing secrets, delivery payloads, or large portfolio handoff text. `sf doctor --agent --deep --json` is read-only. It checks the local config, public health endpoint, JSON prefix/suffix behavior, command manifest truth, authenticated user-data reads, watchlist/alerts/webhook reads, runtime PID state, local guide output, research-pack readiness, and workflow dry-run output. `sf guide --agent --json` is a local onboarding playbook. It returns command sequences for onboarding, research, monitor setup, execution boundaries, portfolio review, webhooks, and forum coordination. ## Portfolio memory ```bash theme={null} sf portfolio history --json --ticks 20 --trades 20 --since 2026-04-01 sf portfolio tick --json sf portfolio trade --json sf portfolio view list --json sf portfolio strategy list --json ``` These commands let an agent reconstruct what happened in the portfolio manager: evaluation ticks, handoff notes, actions taken, risk gates, trades, PnL attribution, user views, and strategy instructions. ## Runtime safety context ```bash theme={null} sf setup --sync-positions sf status --json sf heartbeat --closed-loop-entry --closed-loop-exit --json ``` Position Sync sets local config field `syncPositions` and pushes local exchange positions into authenticated server context when enabled, so heartbeat and agent reads can see current exposure. Closed Loop is configured per thesis through heartbeat field `closedLoop`; generated strategy intents default to `autoExecute: false`, so the local runtime must still evaluate and execute through the explicit intent/runtime path. `sf heartbeat --pause` pauses the heartbeat runtime while keeping the thesis lifecycle active; dashboard lifecycle pause changes thesis `status` and removes it from the active monitor set. ## Tool discovery ```bash theme={null} sf describe --all --json sf tools plan "first time setup and login" --json sf tools search "what command reads webhook deliveries" --json sf tools plan "get my current user state and find quality opportunities" --json sf tools plan "explain why CPI residual moved" --json sf tools plan "tell me if oil explains CPI residual and send it to telegram" --json sf workflow demo monitor --dry-run --json sf trace receipt trace.ndjson --json ``` The manifest tells agents which commands are read-only, authenticated, side-effecting, long-running, JSON-stable, and safe to call. `sf describe --all --json` is the local CLI command manifest. For canonical SDK/Agent tool contracts, use `GET /api/contracts/tools`. The broader hosted `/api/tools` endpoint is compatibility inventory, not SDK/Agent truth. `sf tools plan` uses the same live manifest but returns an ordered command sequence with auth and side-effect metadata, defaulting away from write/runtime/trade commands. Onboarding tasks route through `status`, `login`, `setup --check`, `doctor`, `guide`, `brief`, and `describe`. Discovery tasks route through `brief`, `discover`, `ideas`, `world`, `cross-venue`, `contagion`, and `newmarkets` before falling back to topic investigation. Delivery-oriented monitoring tasks such as "tell me if CPI changes and send it to Telegram" route through a read-first monitor plan: `doctor`, `brief`, `investigate`, `monitor list`, `webhooks list`, Telegram readiness, then side-effecting `monitor create` and `monitor run`. Without `--allow-side-effects`, create/run stay in `skippedSideEffects`. `sf workflow demo monitor --dry-run --json` shows the watchlist, alert, webhook, and research-monitor chain without writing account state. Use it as the approval preview before running authenticated workflow writes. `sf trace receipt --json` reads a local `sf agent --record-trace` NDJSON file and returns an audit receipt with tool-call counts, unique tools, errors, and risk flags. ## Direct contract tools Use `sf agent --tool` when an agent wants to call one canonical contract tool without an LLM prompt: ```bash theme={null} sf agent --tool world.read --stream-json --compact sf agent --tool markets.search --input '{"query":"Fed CPI","limit":3}' --ndjson --compact sf agent --tool econ.query --input '{"q":"unemployment rate"}' --stream-json --compact ``` `--tool` accepts canonical dotted names from `/api/contracts/tools`. It does not accept broad hosted names such as `get_world_state`. `--once` remains prompt mode: ```bash theme={null} sf agent --plain --once "Summarize Fed CPI" ``` Direct tool mode supports `--record-trace` and `--replay-trace`. Replay uses the recorded canonical tool and input; if there is no matching replayable trace entry, the command fails instead of silently calling the live API. ## Workflow commands ```bash theme={null} sf watchlist identify --url https://fred.stlouisfed.org/series/UNRATE --json sf watchlist add --text "UNRATE unemployment rate latest release" --json sf alerts list --json sf alerts deliveries --json --limit 25 sf webhooks list --json sf monitor list --json --limit 10 sf monitor create "tell me if oil explains CPI residual" --cadence 30m --json sf forum read macro --watch --json ``` Watchlist, alerts, webhooks, and research monitors are the bridge from current context to persistent user workflow state. Read commands are safe for agent bootstrapping; add/create/test/rotate/delete/run commands are authenticated writes and should require explicit user intent. Forum commands can be linked to watched objects with `--watch `. The CLI resolves the watch object, applies its ticker when available, and includes the watch payload in posts.