Skip to content

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, and tls / api_key as 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_key in that context, or VIRTUFIN_API_KEY in the TUI's environment.

Steps

  1. 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, env or --), Topics, Status. The active one is marked ▶.
  2. Check the target is reachable: its Status dot 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.
  3. Highlight the context and press Enter.

    Shortcut from any tab: ctrl+p, type Switch 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_context in ~/.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 = true the row is red: PROTECTED: changes ask first.
  • scenario.LIVE is created on the new context if it is missing, and your init_scripts run 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.