Skip to content

Getting started

Install

virtufin-tui is published to a private index at gitea.haenerconsulting.com, not public PyPI -- every install method below needs credentials for it first. Gitea serves the package files from that same host, so one credential covers both. Use a Gitea personal access token (scope read:packages) as the password. Requires Python 3.12+.

One-off (inline credentials)

Simplest for a single machine / CI job -- embed credentials directly in the index URL:

export VIRTUFIN_REGISTRY_USER=<your-gitea-username>
export VIRTUFIN_REGISTRY_TOKEN=<your-gitea-token>
INDEX="https://${VIRTUFIN_REGISTRY_USER}:${VIRTUFIN_REGISTRY_TOKEN}@gitea.haenerconsulting.com/api/packages/virtufin/pypi/simple/"

# Recommended: use uvx (no install needed)
uvx --index "$INDEX" --from virtufin-tui virtufin-tui

# Or install via pip
pip install virtufin-tui --index-url "$INDEX" --extra-index-url https://pypi.org/simple
virtufin-tui

# Or install via uv into a project
uv add virtufin-tui --index "$INDEX"

Persistent (no credentials in shell history / process list)

pip, via ~/.netrc:

cat >> ~/.netrc <<'EOF'
machine gitea.haenerconsulting.com
login <your-gitea-username>
password <your-gitea-token>
EOF
chmod 600 ~/.netrc

pip install virtufin-tui \
  --index-url https://gitea.haenerconsulting.com/api/packages/virtufin/pypi/simple/ \
  --extra-index-url https://pypi.org/simple

uv, via the UV_INDEX env var (add to your shell profile):

export UV_INDEX="https://<your-gitea-username>:<your-gitea-token>@gitea.haenerconsulting.com/api/packages/virtufin/pypi/simple/"

uvx --from virtufin-tui virtufin-tui
uv add virtufin-tui   # inside a project

Either way, public dependencies (textual, grpcio, pydantic, tomlkit, etc.) still resolve from pypi.org as usual -- the private index is additive, not a replacement for it.

Check which version is installed with virtufin-tui --version.

First run

On first run, if ~/.config/virtufin/api/contexts.toml (or ~/.config/virtufin/tui/config.toml) doesn't exist yet, it's seeded from the shipped defaults (a single local context pointing at localhost:5002) -- edit the copy under ~/.config to add other environments. A fuller template lives at contexts.toml.example in the repo root. The worker catalog is not copied: the TUI merges the catalog it ships under ~/.config/virtufin/tui/workers.toml, so that file holds only your own entries (an entry there overrides the shipped one of the same name field by field; a full copy would go stale). 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"

[[contexts]]
name = "kubernetes"
api_host = "api.virtufin.com"
api_port = 443
tls = true
worker_api_host = "api.virtufin.svc.cluster.local"
worker_api_port = 5002
description = "k3s cluster via ingress; workers dial the in-cluster Service directly"

The active context itself isn't set here -- it's state, not config; see Contexts.

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
api_key string unset (falls back to VIRTUFIN_API_KEY env var) Sent as x-api-key metadata on every call; required when the endpoint enforces API-key auth. See Contexts for the env-var fallback and error reporting.
worker_api_host string unset (falls back to api_host) Address a spawned worker process dials for its own Gateway callback; set for contexts where the worker runs somewhere api_host isn't reachable from (e.g. cluster-internal)
worker_api_port int (1-65535) unset (falls back to api_port) Port for worker_api_host
description string "" Free-form label shown in the Config page's contexts table

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 the active context (see Persistence in Contexts)

Config file location: $XDG_CONFIG_HOME/virtufin/api/contexts.toml if $XDG_CONFIG_HOME is set, otherwise ~/.config/virtufin/api/contexts.toml on every OS (there's no platform-specific path like macOS's "Application Support" or Windows's %APPDATA% -- the same ~/.config/... layout is used everywhere). Runtime state (active context, active Scenario, subscribed event topics) lives separately under $XDG_STATE_HOME (default ~/.local/state), not in this file. The TUI's own log file (tui.log, everything logged during a session -- see Architecture) lives alongside that runtime state at $XDG_STATE_HOME/virtufin/tui/tui.log, for the same reason: it's generated output, not something you hand-author. It rotates at 10 MB and keeps three old files (tui.log.1 .. tui.log.3). A failure that repeats on every attempt (a rejected API key, say) is logged with its traceback once, then at DEBUG until it recovers or changes.

Switch context inside the TUI

Go to the contexts table (Config › Navigation in the default layout), highlight a row in the contexts table, and press Enter. Switching closes the current gRPC channel and opens a new one to the selected endpoint; the dashboard refreshes within 1 second.

Development

git clone https://git.haenerconsulting.com/virtufin/tui
cd tui
uv sync --extra dev
uv run virtufin-tui --context local
uv run pytest tests/
uv run ruff check src/ tests/ scripts/

CI (.github/workflows/test.yaml) runs the same lint and tests on every change to the code or the tests and on pull requests; the publish workflow runs the tests again before it publishes.

See Architecture for the data flow and Keybindings for the full keybinding table.