vivly 0.5.0b3

Python client + CLI for the Vivly social-data API (X / Reddit) with smart prompt-based routing.

vivly

Async Python client for the Vivly social-data API. One bearer key, two live sources: X (Twitter) and Reddit, plus a smart router that picks sources from a plain-language prompt. Comes with a CLI and an optional MCP server so AI agents (Claude Desktop, Claude Code, Cursor, …) can call it directly.

0.5.0b3 — breaking change. The Python API is now async (async with + await). The CLI is unchanged. See Usage.

Install

pip install --pre vivly==0.5.0b3                # core SDK + CLI
pip install --pre "vivly[mcp]==0.5.0b3"         # + MCP server (vivly-mcp)

The --pre flag is required while we're in beta.

Authenticate

The client needs a personal access token (looks like vk_live_...). Two ways:

# Option A: log in interactively (opens a browser, stores the token at
# ~/.config/vivly/config.json with 0600 perms)
vivly login

# Option B: set it yourself if you were handed a token
export VIVLY_API_KEY="vk_live_..."

A .env file in the working directory is auto-loaded. Resolution order: explicit api_key= argument, then VIVLY_API_KEY (or legacy VIVLY_SKILL_KEY), then .env, then ~/.config/vivly/config.json.

Usage

CLI

vivly route "what reddit thinks of claude code"          # planner picks sources
vivly route "claude code launch reactions" --x           # pin to X
vivly route "san antonio spurs" --x --reddit             # pin both
vivly route "..." --limit 50 --pretty                    # 50 items, pretty JSON
vivly route "..." --out results.json                     # to file
vivly route "..." --no-interactive                       # take planner defaults

While a query runs you'll see a per-source progress block:

  ▰▰▰▱▱▱▱▱ reddit  fetching
  ▰▰▰▱▱▱▱▱ x       fetching

…finalising to per-source counts when the response lands.

Python (async)

import asyncio
from vivly import VivlyClient

async def main():
    async with VivlyClient() as v:
        # Reddit: one-shot retrieval. Auto-discovers subreddits, searches them,
        # and LLM-filters the results for relevance.
        r = await v.reddit.search("claude code agents", max_posts=10)
        for post in r["posts"]:
            print(post["score"], post["title"], post["url"])

        # X / Twitter: async helper that starts a scrape, polls, returns items.
        # (Runs a paid third-party actor server-side; expect a few seconds to
        # minutes — pass on_progress to surface per-poll status.)
        tweets = await v.x.scrape(
            '"san antonio" arena Spurs lang:en',
            max_items=50,
            on_progress=lambda ev: print(ev["phase"], ev["status"], f"{ev['elapsed']:.1f}s"),
        )
        for t in tweets:
            print(t["metrics"]["likes"], t["text"][:80])

        # Smart router: describe what you want; it plans + runs the right sources.
        result = await v.route(
            "what are people saying about claude code on reddit",
            force_sources=["reddit"],
            max_items=20,
            ask="auto",                          # never block on MCQs in scripts
        )

asyncio.run(main())

If you'd rather drive the X scrape yourself instead of the blocking helper:

async with VivlyClient() as v:
    started = await v.x.scrape_start("query lang:en", max_items=50)
    status  = await v.x.scrape_status(started["run_id"])
    items   = await v.x.scrape_items(started["dataset_id"])

MCP — expose Vivly to AI agents

Once pip install vivly[mcp] is in place, the vivly-mcp command runs a Model Context Protocol server over stdio exposing three tools: reddit_search, x_scrape, and route. Auth is read from VIVLY_API_KEY exactly like the CLI — the model never sees the key.

Smoke-test in the inspector:

npx @modelcontextprotocol/inspector vivly-mcp

Register with Claude Code:

claude mcp add vivly vivly-mcp -e VIVLY_API_KEY=vk_live_...

Register with Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "vivly": {
      "command": "vivly-mcp",
      "env": { "VIVLY_API_KEY": "vk_live_..." }
    }
  }
}

Cursor uses the same shape at ~/.cursor/mcp.json. After restart, your agent sees reddit_search / x_scrape / route in its tool list and calls them on its own.

Errors

from vivly import VivlyError, AuthError, RateLimitError, NotFoundError

AuthError (401/403) usually means a missing, revoked, or mistyped token.

License

MIT