Documentation

Environment variables

Environment variables that affect Vectron behavior.

This page documents environment variables that directly affect Vectron. Child process environment composition is configured in vectron.toml.

CLI and tracing

Variable	Equivalent option	Values / format	Default	Notes
`VECTRON_LOG`	`--log-level`	tracing level	Unset	Examples: `trace`, `debug`, `info`.

--trace-subscriber has no environment variable. Its accepted values are pretty and json, with default pretty.

TUI metrics

These variables are read by vectron start and have the same meaning as the matching CLI options. CLI options override environment values when both are provided.

Variable	Equivalent option	Values / format	Default	Notes
`VECTRON_TUI_METRICS`	`--tui-metrics`	`on`, `off`	`on`	Enables process CPU/RSS metrics in the TUI.
`VECTRON_TUI_METRICS_MODE`	`--tui-metrics-mode`	`auto`, `foreground`, `background`, `frozen`	`auto`	Controls metrics behavior with terminal focus.
`VECTRON_TUI_METRICS_INTERVAL`	`--tui-metrics-interval`	duration	`1s`	Foreground partial refresh interval.
`VECTRON_TUI_METRICS_FULL_SCAN_INTERVAL`	`--tui-metrics-full-scan-interval`	duration	`10s`	Foreground full scan interval.
`VECTRON_TUI_METRICS_BACKGROUND_INTERVAL`	`--tui-metrics-background-interval`	duration	`20s`	Background partial refresh interval when focus events are supported.
`VECTRON_TUI_METRICS_BACKGROUND_FULL_SCAN_INTERVAL`	`--tui-metrics-background-full-scan-interval`	duration	`120s`	Background full scan interval when focus events are supported.

Duration values use the same parser as the CLI. Examples: 500ms, 1s, 10s, 120s.

Use vectron doctor --json to inspect the resolved terminal and metrics-related configuration.

Shell completion install paths

vectron completions install uses these variables when --dir is omitted.

Variable	Used for	Default / fallback	Notes
`XDG_CONFIG_HOME`	Fish completion base directory	Falls back to `~/.config`	Final path: `$XDG_CONFIG_HOME/fish/completions`.
`XDG_DATA_HOME`	Bash and Zsh completion base directory	Falls back to `~/.local/share`	Bash final path: `$XDG_DATA_HOME/bash-completion/completions`; Zsh final path: `$XDG_DATA_HOME/zsh/site-functions`.
`HOME`	Unix home directory resolution	Required when XDG vars are unset	Used to resolve `~` fallbacks.
`USERPROFILE`	Windows home directory resolution	Used by the home resolver on Windows	Present in the resolver, but Vectron’s main supported development targets are macOS and Linux.

Default completion files:

Shell	File
Bash	`vectron`
Fish	`vectron.fish`
Zsh	`_vectron`

Child process environment

Vectron constructs each child process environment in this order:

parent environment
global.env
global.env_file
process.env
process.env_file
instance-specific variables
variables derived by instance_env_suffix

Relevant configuration fields:

Field	Effect
`global.env`	Adds or overrides variables for all processes.
`global.env_file`	Loads variables after `global.env`.
`process.env`	Adds or overrides variables for one process.
`process.env_file`	Loads variables after `process.env`.
`process.port_env`	Exports the allocated instance port into the named variable.
`global.instance_env_suffix`	Derives per-instance variable names; must contain `{index}`.
`process.instance_env_suffix`	Overrides the global suffix for one process; must contain `{index}`.
`global.disable_color_env`	Disables ANSI color-related environment variables in child processes.
`process.disable_color_env`	Overrides color-env behavior for one process.