Configuration reference

`examples.config.toml` is the canonical complete example; this reference explains every 0.3.0 configuration family.

Resolution and failure mode

--config PATH
CMDSCOPE_CONFIG=PATH
$XDG_CONFIG_HOME/cmdscope/config.toml
built-in defaults

Explicit paths must exist. Unknown TOML fields, invalid key chords, unknown action names, unsupported window kinds, and missing menu/window/wrap references fail closed during startup.

Keys

All non-text-input actions accept a string or an array of aliases.

[keys]
actions = "ctrl-space"
select_next = ["down", "ctrl-n"]
select_previous = ["up", "ctrl-k"]
context = "ctrl-o"
quit = ["esc", "ctrl-c"]

Local modal keymaps use the same key-token grammar.

Columns

[ui.columns]
date = true
pwd = true
exit = false
duration = true
order = ["date", "pwd", "duration", "exit"]
date_format = "relative"
min_width = 12

[ui.column.pwd]
width = 28
min_width = 10
max_width = 36
align = "left"
truncation = "start"
priority = 20

[ui.column.duration]
width = 8
align = "right"
priority = 50

Property	Values	Behavior
`order`	column names	Deterministic visible order; omitted columns are appended.
`width`	integer	Preferred width.
`min_width`/`max_width`	integer	Responsive bounds.
`align`	`left`, `center`, `right`	Cell alignment.
`truncation`	`start`, `end`, `none`	Long-value handling.
`priority`	0–255	Higher values are removed first when the row must shed metadata.

Menus

[ui.menus.actions]
confirm = "enter"
next = ["down", "j"]
previous = ["up", "k"]
cancel = "esc"
on_open = ["window:preview"]

[[ui.menus.actions.items]]
label = "Inspect →"
action = "menu:inspect"

[[ui.menus.actions.items]]
label = "stderr"
action = "wrap:stderr"

Use menu:name for nested menus, window:name for modal windows, and wrap:name for pure string composition. Each item may also have on_select and on_leave action arrays.

Windows

[ui.windows.timeline]
kind = "timeline"
title = " Timeline · previous / selected / next "
width = 88
height = 16
[ui.windows.timeline.keymap]
close = "esc"

Built-in kinds are location, timeline, and preview. Window lifecycle hooks use on_open and on_close.

Wraps

[ui.wraps.tee]
template = "{command} | tee -a {query}"

Templates are not shell programs. They only transform selected history text into stdout text.

Modal precedence

Active menu-local bindings.
Active window-local bindings.
Base semantic keymap.
Text input only when no modal is active.

This ordering keeps modal behavior deterministic and prevents a local key such as esc from leaking into the search editor.

Complete example

Start from the repository's examples.config.toml, then change only the sections you need. Run cmdscope --config ./examples.config.toml --db ./history.db to validate the entire document at startup.