Getting started¶
Install¶
# Recommended: use uvx (no install needed)
uvx --from virtufin-tui virtufin-tui
# Or install via pip
pip install virtufin-tui
virtufin-tui
# Or install via uv into a project
uv add virtufin-tui
First run¶
If no ~/.config/virtufin-tui/contexts.toml exists, the TUI opens the contexts
picker and prompts you to add a virtufin-api endpoint. Example contexts.toml:
[[contexts]]
name = "local"
api_host = "localhost"
api_port = 5002
description = "Local dev virtufin-api"
[[contexts]]
name = "staging"
api_host = "staging.virtufin.com"
api_port = 5002
tls = true
description = "Staging cluster"
default_worker_topic = "workmanager.lifecycle"
active_context = "local"
Configuration¶
| Field | Type | Default | Description |
|---|---|---|---|
name |
string | required | Display name (must be unique within [[contexts]]) |
api_host |
string | required | Hostname of the virtufin-api gRPC endpoint |
api_port |
int (1-65535) | required | Port of the gRPC endpoint (typically 5002) |
tls |
bool | false |
Use TLS for the gRPC channel |
default_worker_topic |
string | unset | Subscribe to this topic on start (typically workmanager.lifecycle) |
description |
string | "" |
Shown in the contexts picker |
Environment variables override file values:
| Env var | Overrides |
|---|---|
VIRTUFIN_TUI_API_HOST |
api_host of the active context |
VIRTUFIN_TUI_API_PORT |
api_port of the active context |
VIRTUFIN_TUI_CONTEXT |
active_context |
Config file location (XDG-aware via platformdirs):
| OS | Path |
|---|---|
| Linux | ~/.config/virtufin-tui/contexts.toml |
| macOS | ~/Library/Application Support/virtufin-tui/contexts.toml |
| Windows | %APPDATA%\virtufin-tui\contexts.toml |
Switch context inside the TUI¶
Press c to open the contexts picker. Switching closes the current gRPC channel
and opens new ones to the selected endpoint. The dashboard refreshes within 1
second of the switch.
Development¶
git clone https://gitea.haenerconsulting.com/virtufin/virtufin-tui
cd virtufin-tui
uv sync
uv run virtufin-tui --context local
uv run pytest tests/
uv run ruff check src/ tests/
See architecture.md for the data flow and keybindings.md for the full keybinding table.