Configuration

bext-tui is configured primarily through CLI flags. Anything you'd want to override per session lives there. The optional config file (~/.config/bext-tui/config.toml, planned) is for preferences that persist across sessions.

CLI flags

bext-tui [OPTIONS]
Flag Default Description
--host 127.0.0.1 Admin API host
--port 4000 Admin API port
--tls off Use HTTPS
--token from env Admin API bearer token
--insecure off Skip TLS certificate verification (DANGEROUS — dev/self-signed only). Without this flag, invalid certs are rejected.
--local off Local mode — read state from filesystem alongside the API
--instances none Path to a multi-instance config file
--mouse off Enable mouse support (click tabs, scroll lists)
--poll-ms 2000 Fast-tier polling interval in milliseconds
--config none Path to bext.config.toml (local mode)
--help Print usage
--version Print version

Security note: --insecure disables TLS chain verification entirely. Anyone on the network path can intercept the admin API, including the bearer token. Only use it for self-signed dev certs on a network you trust. Combined with --tls, it prints a warning at startup.

Environment variables

Variable Equivalent flag Notes
BEXT_TUI_HOST --host
BEXT_TUI_PORT --port
BEXT_TUI_TLS --tls Truthy = on
BEXT_ADMIN_TOKEN --token Same env var the CLI uses
BEXT_TUI_LOG — tracing filter (e.g. BEXT_TUI_LOG=debug)

CLI flags always win over env vars.

Polling tiers

The TUI polls the admin API on three tiers — different endpoints have different freshness needs:

Tier Default interval Endpoints
Fast 2 s (--poll-ms) /overview, /requests, /cache
Medium 10 s (5 × fast) /workers, /proxy, /waf
Slow 60 s (30 × fast) /sites, /certs, /deployments, /license, /config

Lowering --poll-ms makes the dashboard feel snappier but increases load on the bext server. The 2 s default is a good baseline. For very small instances, you can drop to 500 ms; for production fleets, 5 s is plenty.

Multi-instance config

bext-tui --instances ~/.config/bext-tui/instances.toml reads a TOML file describing every server you want to monitor:

# ~/.config/bext-tui/instances.toml

[[instance]]
name = "activ-2"
host = "activ-2.activcommunication.ch"
port = 443
tls = true
token = "$BEXT_ADMIN_TOKEN_ACTIV2"

[[instance]]
name = "vps-staging"
host = "staging.example.com"
port = 4000
token = "$BEXT_ADMIN_TOKEN_STAGING"

[[instance]]
name = "dev"
host = "127.0.0.1"
port = 4000

token may be a literal string or a $ENV_VAR reference (expanded at startup).

In multi-instance mode, the Dashboard view aggregates across all instances. Use :connect <name> in the command palette to drill into one server.

Logging

bext-tui writes its own diagnostic logs to stderr, not into the alternate-screen buffer (so they don't interfere with the TUI). Run with a filter to see them:

BEXT_TUI_LOG=debug bext-tui --host ... 2> bext-tui.log

The filter accepts the standard tracing-subscriber syntax: info, debug, bext_tui=trace,reqwest=warn, etc.

Theming

Colors are defined in crates/bext-tui/src/theme.rs. They use the standard 16-color terminal palette plus a few RGB selections, so they respect your terminal's color scheme. Re-theming is a recompile away — there's no runtime config for colors yet.

The semantic mappings are:

Style Used for
success (green) UP, healthy, 2xx, HIT, valid certs > 30d
warn (yellow) degraded, 4xx, MISS, certs 10–30d, > 60% util
error (red bold) down, 5xx, expired, > 85% util
info (blue) informational, 3xx, status bar accents
dim (dark gray) secondary text, timestamps, hints

Future config

Persistent preferences (column widths, default filters, theme overrides) will live in ~/.config/bext-tui/config.toml. That file isn't read yet — track [issue #N] for progress.