Skip to content

The TUI's API

The platform's user-level operations — list and start workers, connect feeds, schedule triggers, halt scenarios, read state and topics, ... — are one shared operation catalog (openspec operations), a document virtufin-domain-devkit ships. The TUI and the web app each implement every operation of it, so the same name with the same input does the same thing in both clients.

This page says how the catalog is reached from the TUI. It does not repeat the catalog.

Where it is implemented

virtufin_tui.operations implements every operation over TuiClient, the same client calls the panes make — there is no privileged path. Each input is validated against the operation's JSON Schema (with its defaults) before anything is sent; a malformed input is refused naming the field. Writes go through the client's write guard, so on a protected context they ask first, and they are recorded on Infra › Changes. tests/test_operations.py fails when an operation of the document is missing or its schema differs, so the TUI and the catalog cannot drift apart.

Groups (see the catalog for inputs): workers.* and registry.list, feeds.*, triggers.*, scenarios.*, killSwitch, strategies.*, state.*, topics.*.

From the AI tab

Each operation is one tool of the AI tab, named <group>__<action> — the operation name with . replaced by __:

Operation Tool
workers.list workers__list
triggers.schedule triggers__schedule
feeds.connect feeds__connect
scenarios.setStatus scenarios__setStatus
  • Every write asks first: a dialog shows the operation and its input (triggers.schedule {"name": ...}?); it runs only on yes. A declined call is reported to the model as not confirmed.
  • People-only operations are not offered as tools: killSwitch is K in the TUI only.
  • The model and its endpoint come from ~/.config/virtufin/tui/llm_providers.toml (OpenAI-compatible Chat Completions; P picks the provider). See Set up AI.
  • Each turn the model gets a small state snapshot (active scenario, triggers, topics, workers) so it uses real ids.

From a script

Scripts run as subprocesses with the active context in environment variables (VIRTUFIN_TUI_API_HOST, VIRTUFIN_TUI_API_PORT, VIRTUFIN_TUI_API_TLS, VIRTUFIN_TUI_API_KEY, ...; full table: Scripts › The env-var contract). They run with the TUI's own Python, so virtufin_tui.operations imports:

import asyncio
import json
import os

from virtufin_tui.client import TuiClient
from virtufin_tui.operations import run_operation


async def run():
    client = TuiClient(
        os.environ.get("VIRTUFIN_TUI_API_HOST", "localhost"),
        int(os.environ.get("VIRTUFIN_TUI_API_PORT", "5002")),
        tls=os.environ.get("VIRTUFIN_TUI_API_TLS") == "true",
        api_key=os.environ.get("VIRTUFIN_TUI_API_KEY") or None,
    )
    await client.connect()
    try:
        workers = await run_operation(client, "workers.list", {})
        print(json.dumps(workers, indent=2, default=str))
    finally:
        await client.disconnect()


if __name__ == "__main__":
    asyncio.run(run())

run_operation(client, "<group>.<action>", {...}) takes the operation's dotted name (not the tool name) and validates the input first. Unlike in the TUI, a script's writes are not confirmed on a protected context and not recorded on Changes: a script has its own client. For calls outside the catalog, use _rpc.invoke() (any api RPC by service and method, Scripts).

From the panes

Most pane actions do what an operation does, over the same client calls: e.g. a on Infra › Triggers is triggers.schedule, C on Trading › Feeds is feeds.connect, h on Trading › Scenario is scenarios.halt / scenarios.resume, u on Infra › Workers is workers.upgrade. Some pane actions have no operation (a feed's start/stop publish, tag undo, the view settings). See the How-tos and Keybindings.