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.