Configuration

The client is configured with two TOML files in its per-user config directory:

• config.toml — keybindings, commands, locale, editor preset, theme, picker, and storage;
• macros.toml — named action sequences that can be bound like any action.

Both are read once at startup. There is no in-app editor and no hot reload: edit the file, then restart the client.

Where the file lives

The config directory is resolved with the directories crate for the application komp_ac_client. On a typical Linux setup:

File	Path
Configuration	~/.config/komp_ac_client/config.toml
Macros	~/.config/komp_ac_client/macros.toml
Themes	~/.config/komp_ac_client/themes/
Print templates	~/.config/komp_ac_client/print_templates/

XDG_CONFIG_HOME overrides the base directory. On macOS the same files live under ~/Library/Application Support/com.komp-ac.komp_ac_client/, and on Windows under %AppData%\komp-ac\komp_ac_client\config.

How it works

On its first run the client creates the directory and, if a file is missing, writes the default copy. Existing files are never overwritten, so upgrades do not clobber your settings.

At startup the client:

1. parses config.toml as TOML — a syntax error stops startup with an error;
2. validates the parts that can be wrong before use — an unknown [keybindings.<mode>] table or an invalid picker.default_order_by fails fast instead of being silently ignored;
3. translates your [keybindings] tables into the keymap schema the underlying UI library expects, and [editor] keybinding_mode into the modal editor preset;
4. loads macros.toml and applies [i18n], [colors], and [storage].

Every key is optional: a missing section or key falls back to its built-in default, so an empty config.toml is valid and the app remains fully usable.

The default file

This is what the client writes on first run, with its comments:

config.toml

[storage]
# User-facing exports are created here. Relative paths are resolved from this
# config file's directory. When omitted, the client uses Downloads, Documents,
# the home directory, or the temporary directory (in that order).
# output_dir = "exports"
# Print templates are loaded from the `print_templates` directory beside this file.

# Global keybindings: active in every mode. Bare arrays live directly under
# [keybindings]; mode-specific bindings go in the [keybindings.<mode>] tables.
# Names declared in macros.toml can be bound here in exactly the same way.
[keybindings]
enter_command_mode = [":", "ctrl+;"]
next_buffer = ["space+b+n"]
previous_buffer = ["space+b+p"]
close_buffer = ["space+b+d"]
split_vertical = ["space+w+v"]
split_horizontal = ["space+w+s"]
close_pane = ["space+w+d"]
focus_next_pane = ["space+w+n"]
focus_prev_pane = ["space+w+p"]
revert = ["space+b+r"]
picker_toggle = ["space+f"]
picker_toggle_current = ["space+p"]
keybindings_picker = ["space+?"]
toggle_sidebar = ["ctrl+t"]
toggle_buffer_list = ["ctrl+b"]

[keybindings.general]
nav_up = ["Up", "k"]
nav_down = ["Down", "j"]
nav_left = ["Left", "l"]
nav_right = ["Right", "h"]
move_next = ["Tab"]
move_previous = ["Shift+Tab", "ctrl+p"]
select = ["Enter"]
exit = ["esc"]

[keybindings.common]
save = ["ctrl+s"]
save_and_quit = ["ctrl+shift+s"]

# MODE SPECIFIC
# NOR MODE
[keybindings.nor]
previous_entry = ["q"]
next_entry = ["1"]
save_and_next_entry = ["Home"]
go_to_definition = ["g+d"]
revert_and_previous_entry = ["End"]

[keybindings.command]
command_backspace = ["backspace"]

[keybindings.picker]
nav_up = ["Up", "ctrl+p"]
nav_down = ["Down", "ctrl+n"]
command_autocomplete = ["tab"]

# Command-line aliases (the words typed after `:`), not keybindings.
[commands]
save = ["w"]
quit = ["q"]
force_quit = ["q!"]
save_and_quit = ["wq"]
revert = ["r"]
find_file_palette_toggle = ["ff"]
print = ["print"]
delete = ["delete"]
archive_entry = ["archive"]

[picker]
# Default ordering for the current-table form picker. Uncomment one example.
# default_order_by = "position desc"
default_order_by = "row_display_columns asc"
# default_order_by = "created_at desc"

[key_menu]
# Show Which-Key-style hints while a multi-key binding is in progress. This
# does not disable the keybindings themselves or the application data menu.
show_keybindings = true

[i18n]
language = "en"  # UI language. Options: "en" (English), "sk" (Slovak), "cs" (Czech)
date_order = "day-month-year"  # Date display/input. Options: "year-month-day", "day-month-year"

[editor]
keybinding_mode = "helix"  # Options: "default", "vim", "helix", "emacs", "vscode"

[colors]
# theme = "gruvbox"
# theme = "catppuccin_latte"
theme = "catppuccin_frappe"

Section reference

[storage]

Key	Default	Meaning
output_dir	unset	Where exports are written. Relative paths resolve against the config directory; an absolute path is used as-is. When unset, the client uses Downloads/komp_ac_exports, then Documents, then home, then the temp directory.

[keybindings] and [keybindings.<mode>]

Bare arrays under [keybindings] are global and active everywhere. The mode-specific sub-tables are:

Mode	Applies to
general	Page navigation (arrows, Tab, Enter, Esc)
common	Shared actions such as save
command	The : command line
picker	The picker overlay
nor / ins / sel	The modal editor’s normal / insert / select mode

Each entry maps an action name to one or more key sequences. Sequences are written as chords joined by + (ctrl+s, shift+tab, space+b+n) and can contain multiple chords separated by spaces (g+d). An unknown mode table is a startup error; an unknown action name is dropped with a notice rather than crashing.

The action names you can bind are the same names the keybindings picker (Space+?) shows, for example save, quit, revert, next_buffer, previous_entry, go_to_definition, and the nav_*/move_* intents. Macro names from macros.toml work in exactly the same place.

[commands]

Aliases for the : command line. These are not keybindings — they are the words typed after :. The values in the file are added to a built-in set, so w, write, q, q!, wq, x, e!, delete, archive, ff, print, bn, bp, and bd always work even if the section is empty.

The full list of command actions that can take aliases:

Action	Built-in aliases	Shipped extra aliases
save	w, write	w
save_and_next_entry	save_and_next_entry	—
quit	q	q
force_quit	q!	q!
save_and_quit	wq, x	wq
revert	e!	r
revert_and_previous_entry	revert_and_previous_entry	—
delete_entry	delete	delete
archive_entry	archive	archive
find_file_palette_toggle	ff	ff
print	print	print
next_buffer	bn	—
previous_buffer	bp	—
close_buffer	bd	—

[picker]

Key	Default	Meaning
default_order_by	position desc (code) / row_display_columns asc (shipped file)	Default ordering for the current-table picker. Must be exactly a column and asc or desc; the client rejects anything else at startup.

[key_menu]

Key	Default	Meaning
show_keybindings	true	Whether Which-Key-style hints appear during a multi-key sequence. Does not disable the bindings or the data menu.

[i18n]

Key	Default	Meaning
language	en	UI locale: en, sk, or cs. English is the fallback for missing translations.
date_order	year-month-day (code) / day-month-year (shipped file)	How date-like fields are displayed and entered.

[editor]

Key	Default	Meaning
keybinding_mode	default	Modal editing preset: default, vim, helix, emacs, or vscode. default behaves like vim.
show_line_numbers	true	Accepted editor option.
tab_width	4	Accepted editor option.

[colors]

Key	Default	Meaning
theme	light (code) / catppuccin_frappe (shipped file)	Theme file name from themes/, without the .toml extension.

macros.toml

macros.toml defines ordered action sequences under [macros]:

[macros]
saveandexit = ["save", "exit"]

Each name becomes bindable under [keybindings] exactly like a built-in action. The shipped file ships one commented-out example.

Editing and applying

1. Stop the client.
2. Edit config.toml (and macros.toml if needed) in the config directory.
3. Start the client again.

If the file is invalid, the client prints the error at startup and exits rather than starting with a half-applied configuration.

Note

The client only writes the default file when none exists. It never rewrites config.toml afterwards, so your comments and formatting are preserved.

Continue

• Client setup and first launch — where the config directory comes from and the startup order.