Configure Pyx with TOML files

The idea#

Everything you can set in Pyx is text. Settings are TOML, keymaps are TOML, themes are TOML, and chart workspaces export as TOML. You can read every preference you have ever set, back it up, diff it, or put it in a dotfiles repo. The Settings screen is the friendly editor for the same files.

TOML is key = value lines grouped into [sections]. Any plain text editor works.

The three layers#

Pyx reads settings from three layers and stacks them. Higher layers win:

1. Defaults, built into the app. Never edited.
2. User, your personal file. This is the one you edit, in your config folder (a path like ~/.config/pyx/config.toml).
3. Local, an optional per-machine override. Rarely needed.

Anything you do not set falls back to the default, so a config file with three lines is complete. The Settings screen shows the provenance of every value: default, user, or local. Changes made in the app write back to the user file, so the screen and the file never drift apart.

Edits to the files hot-reload. Save the file, watch the app change.

The main sections#

Include only the lines you want to change. Real defaults shown.

[ui]
theme = "One Dark Pyx"
hide_amounts = false
font_family = "Inter"

[motion]
enabled = true
scale = 1.0            # 0.5 slower, 2.0 faster

[motion.flash]
enabled = true         # flash cells on value change

The holdings table remembers its shape:

[holdings]
default_view = "grouped"       # or "flat"
default_sort = "market_value"
sticky_columns = []

[holdings.drawer]
default_range = "1Y"           # "1Y", "5Y", or "MAX"
default_lot_method = "fifo"    # "fifo", "lifo", or "specific_id"

[holdings.sparkline]
days = 30
color = "trend"

Allocation targets are fractions, so 60% is 0.6:

[allocation]
default_scheme = "asset_class" # or "sector"
target_drift_threshold = 0.02  # banner when drift passes 2%

[allocation.targets]
equity = 0.6
fixed_income = 0.3
cash = 0.1

The Performance page benchmark has no Settings control, so the file is the way to change it:

[charts]
benchmark_symbol = "SPY"

Two smaller sections round it out: [search] tunes the local symbol index, and [palette] stores your starred palette commands, which you will normally set by right-clicking in the palette itself.

Keymap files#

Keyboard shortcuts live in separate keymap TOML files. Each binding names a key, its modifiers, a context, and an action:

[[bind]]
key = "k"
mods = ["meta"]
context = "Global"
action = "TogglePalette"

The full binding format and the shipped shortcut reference are in Keyboard shortcuts and the Vim keymap.

Theme files#

Each of the built-in themes is its own TOML file of design tokens. Copy one, change its colors or font size, and you have a custom theme. Details in Themes, fonts, and motion settings.

Workspace files#

Chart workspaces follow the same philosophy. CmdS exports the current workspace, panes, symbols, indicators, drawings, and range included, as a portable TOML file. CmdO opens one. A chart setup you spent an hour building is a file you own, not a row in someone's database.

Experimenting safely#

Copy a file before editing it. Pyx is forgiving: an invalid config falls back to defaults instead of crashing, and unknown keys are ignored. The backup just means you can return to a known state instantly.

Config files never contain portfolio data. Positions, transactions, and prices live in the encrypted database, and secrets live in an encrypted file sealed by a key in the OS keychain.