Switch context¶
Goal: point the TUI at another virtufin-api endpoint (local, staging, the
cluster) without restarting it.
Prerequisites
- The target context is defined in
~/.config/virtufin/api/contexts.toml(name,api_host,api_port, andtls/api_keyas the endpoint needs; see Getting started). The file is read at start: restart the TUI after adding or editing a context. - If the endpoint enforces API keys:
api_keyin that context, orVIRTUFIN_API_KEYin the TUI's environment.
Steps¶
- Open the contexts table: Config top tab, then
2(Navigation) in the default layout. The contexts table is the first table on that pane:Name,Host,Port,TLS,Key(cfg,envor--),Topics,Status. The active one is marked▶. - Check the target is reachable: its
Statusdot is green. Red shows the reason next to it (Invalid or missing API key,Server unavailable (check host/port/network), ...); grey means not checked yet. -
Highlight the context and press
Enter.Shortcut from any tab:
ctrl+p, typeSwitch context to <name>,Enter.
What you should see¶
- The TUI first makes one keyed call to the new context. Only if it answers does it
switch: the context becomes active (saved as
active_contextin~/.local/state/virtufin/api/state.toml), channels reopen, and every pane refreshes within about a second. - The context row under the tab bar names the new context on every tab (Trading adds
the scenario). On a context with
protected = truethe row is red:PROTECTED: changes ask first. scenario.LIVEis created on the new context if it is missing, and yourinit_scriptsrun against it (Scripts).
Other ways to choose the context¶
| Way | Effect |
|---|---|
virtufin-tui --context <name> |
Start with that context active. |
VIRTUFIN_TUI_CONTEXT=<name> |
Same, from the environment (ignores the stored choice). |
VIRTUFIN_TUI_API_HOST / VIRTUFIN_TUI_API_PORT |
Override host/port of the active context (e.g. a port-forward). |
Troubleshooting¶
| Symptom | Cause and fix |
|---|---|
| A toast says the context does not answer, and the old one stays active | The new endpoint is down or refuses the key. Fix api_host/api_port/tls/api_key in contexts.toml; the row turns green when it answers. |
Invalid or missing API key |
Set api_key on the context or export VIRTUFIN_API_KEY; the Key column shows which source is used. |
no contexts configured in <path> |
contexts.toml is missing or empty: add a [[contexts]] entry at that path. |
| The TUI started on the Config page and other panes say they need a context | No context is active (the stored one no longer exists). Pick one with Enter. |
| An entry is missing from the table | It lacks name, api_host or api_port, or the file is not valid TOML; the problem was shown at start and is in ~/.local/state/virtufin/tui/tui.log. |
Reference: Contexts.