sgf — Socialgraffa CLI

Game telemetry for the command line and coding agents — with a knowledge-grounded economy advisor built in. As easy as git.

Events, funnels, retention, and a full in-game economy cockpit (source / sink / net float, inflation, whale concentration) — queryable from your terminal or straight from an MCP client. Then sgf advise reads that economy through a real game-economics knowledge base and hands you prioritised insights and the design levers to pull.

Zero dependencies — Node built-ins only (fleet pattern from bgz-cli).

Works with: Claude Code · Cursor · Cline · Windsurf · Aider · Codex · any MCP client

Instrument to insight in one sitting — watch the full demo.

Install

npm install -g socialgraffa

The npm package is socialgraffa; the command is sgf.

Quickstart

# Create a tenant (returns read + ingest keys, shown once; read key auto-saved)
sgf signup my-studio --email [email protected] --password yourpass

# Create a game
sgf game create my-game --name "My Game" --platforms ios,android --currencies gold

# Send events (write-only ingest key)
sgf ingest --game my-game --event level_up --player p1 --props '{"level":2}' --key sgf_ingest_xxx

# Read dashboards (rollup-backed)
sgf overview --game my-game
sgf retention --game my-game
sgf economy --game my-game --currency gold

# Ask the economy advisor what to do about it
sgf advise --game my-game

Economy — a cockpit and an advisor

The economy cockpit — source/sink/net float, inflation, whale concentration. Full-res clip.

Live-service games live or die on their economy. sgf economy gives you the cockpit — the same source / sink / net view a live-ops team watches:

sgf economy --game my-game --currency gold

• Faucets vs sinks — where currency is minted vs burned, and the net float trend
• Inflation ratio — is the economy running hot?
• IAP vs earned — how much source comes from purchases vs gameplay
• Whale concentration (Gini) — how much of the currency a handful of players hold
• Top sources / sinks and anomaly detection on the float series

Raw metrics tell you what is happening. sgf advise tells you what to do about it:

sgf advise --game my-game
sgf advise --game my-game --currency gold --platform ios --from 2026-07-01 --to 2026-07-31
sgf advise --game my-game --json          # machine output for agents

It reads your live economy through a game-economics knowledge base distilled from social/live-service economy design (inflation, faucet/sink mix, whale concentration, dual-currency, IAP-vs-earned, appointment retention, virality/k-factor, progression pacing, gacha, price A/B) and returns prioritised insights — each tagged [ACT] / [WATCH] / [OK] with a plain finding and the design levers to pull:

my-game — economy advisor
sell_produce is 97% of all faucet — a single source dominates the economy

  [ACT] Faucet concentration
  One source mints 97% of currency; a nerf or exploit there swings the whole float.
    → Rebalance rewards so no single faucet exceeds ~50% of source
    → Add sink pressure timed to the dominant faucet
  [WATCH] IAP share of source
  Only 1% of currency comes from purchases — monetisation is thin.
    → Test a soft-currency starter bundle

Same knowledge base powers the human docs panel in the dashboard and the socialgraffa_economy_advisor MCP tool — one source of truth, whether a person or an agent is asking.

Auth

Config priority: --key flag > SGF_API_KEY env > ./.sgf/config.json (local, per-project).

Key scopes:

• sgf_... (tenant) — read/manage: metrics, games, funnels, keys, billing
• sgf_ingest_... (ingest) — write-only event ingestion

Add .sgf/ to your .gitignore.

MCP server (agents)

Prefer tools over a CLI? sgf ships an MCP server — point Claude Code (or any MCP client) at it and your agent can read every dashboard, ingest events, and call the economy advisor natively.

sgf mcp-serve

.mcp.json:

{ "mcpServers": { "socialgraffa": { "type": "stdio", "command": "sgf", "args": ["mcp-serve"] } } }

With no API key configured the server starts in onboarding mode (socialgraffa_get_started / socialgraffa_signup) and unlocks the full toolset in-place after signup — including socialgraffa_economy_advisor.

Machine-readable command schema: sgf init --agent-schema

Features

• Games — create and manage game/title workspaces with currencies and platforms
• Ingest — send events with a write-only sgf_ingest_ key (single event or batch)
• Dashboards — overview, retention (D1/D7/D30 triangle), funnels, sessions
• Economy cockpit — source / sink / net float, inflation ratio, IAP-vs-earned, whale concentration (Gini), top sources/sinks, anomaly detection
• Progression, offers & LTV — level fail-rate/walls, offer/paywall funnel, ARPU/ARPPU/LTV by cohort — each with its own advise-* advisor
• Challenges — per-challenge completion/fail/expiry outcomes, reward rate and best rank, fed by the oddsockets result webhook
• Economy advisor — sgf advise: knowledge-grounded insights tagged ACT/WATCH/OK, each with the design levers to pull
• Funnels — define and read multi-step conversion funnels
• Keys & settings — manage API keys, quota behaviour
• Billing — plans, checkout, portal, change/cancel/reactivate
• MCP server — sgf mcp-serve: every command as a native tool, including the economy advisor
• Agent-ready — --json on every read, sgf init --agent-schema for the full command contract

Environment

• SGF_API_KEY (alias SOCIALGRAFFA_API_KEY) — API key
• SGF_URL — base URL override (default https://socialgraffa.com)
• SGF_SIGNUP_SECRET — fleet-ops only: unlocks sgf provision / sgf admin

All commands

Run sgf --help.

License

Proprietary — Tyga.Cloud Ltd. See LICENSE.