Configuration#

Config Files#

toe reads configuration in this order:

$XDG_CONFIG_HOME defaults to ~/.config.

Later TOML values override earlier ones. Ale initialization runs user-level init.ale before workspace init.ale; an existing binding cannot be rebound, so user-level bindings win conflicts.

Open your user config directly: :config-open Open workspace config: :config-open-workspace Reload after editing: :config-reload

Changes to init.ale take effect the next time toe starts. See Scripting for the scripting interface.

Interface Language#

toe selects English, German, French, or Italian from LC_ALL, LC_MESSAGES, then LANG. Unsupported locales use English.

Workspace Trust#

toe treats a directory with .git or .toe as a workspace. Workspace trust is the explicit opt-in that lets workspace-controlled config and tooling affect toe.

Until a workspace is trusted:

• normal file editing, :write, :write-all, and :move still work
• automatic workspace session restore/save is skipped
• workspace-local config files (.toe/config.toml, .toe/init.ale, and .toe/languages.toml) are not loaded
• workspace-configured language servers and formatter commands are not started from workspace config
• :config-open-workspace refuses to create or open workspace config until you trust the workspace

User config still applies in untrusted workspaces.

Trust the current workspace:

:workspace-trust

Remove trust:

:workspace-untrust

Trusted workspaces are stored in $XDG_DATA_HOME/toe/trusted_workspaces (normally ~/.local/share/toe/trusted_workspaces). If a workspace is untrusted at startup, toe shows a status message asking you to run :workspace-trust.

To bypass trust checks entirely, set in your user config:

[editor]
insecure = true

Editor Configuration#

Except for the top-level theme key, the settings below belong under [editor] in config.toml. They can also be changed for the current session with :set <key> <value>, :get <key>, and :toggle <key> for booleans, or :toggle <key> <value>... to cycle a key through the given values. Lists and tables use TOML syntax. Completion after :set shows the available keys.

Examples:

:set gutters.layout ["diagnostics", "line-numbers", "diff"]
:set statusline.left ["mode!", "file-name"]
:set whitespace.render.tab all
:set whitespace.characters.tab "→"
:set auto-pairs {"(" = ")", "[" = "]"}
:set buffer-picker.start-position previous
:toggle file-explorer.hidden
:toggle default-line-ending lf crlf

Theme#

theme = "mocha"   # frappe | latte | macchiato | mocha

General#

Display#

Soft Wrap#

Whitespace and Indentation#

Whitespace rendering can be set separately for space, nbsp, tab, and newline, and each display character can be replaced:

[editor.whitespace]
render = { default = "none", tab = "all", newline = "all" }

[editor.whitespace.characters]
space = "·"
nbsp = "⍽"
tab = "→"
tabpad = " "
newline = "⏎"

Use whitespace.render.<type> and whitespace.characters.<type> to change individual values at runtime.

To change gutter order or visibility:

[editor.gutters]
layout = ["diagnostics", "spacer", "line-numbers", "spacer", "diff"]

[editor.gutters.line-numbers]
min-width = 3

Editing#

auto-pairs also accepts a table of custom opening and closing characters:

auto-pairs = { "(" = ")", "[" = "]", "{" = "}" }

At runtime, auto-pairs accepts a boolean or an inline table of custom pairs.

Auto-Save#

Completion#

Automatic completion is in addition to Ctrl+x, which requests completions at any time, and to the trigger characters a language server advertises.

Search#

Scrolling#

Cursor Shape#

Status Bar#

Valid statusline elements: mode, file-name, file-base-name, file-absolute-path, file-modified-indicator, read-only-indicator, file-encoding, file-line-ending, file-indent-style, file-type, diagnostics, selections, primary-selection-length, position, position-percentage, total-line-numbers, separator, spacer, spinner, version-control, macro-recording, and pane-maximized.

macro-recording and pane-maximized report editor-wide state rather than the pane’s own. macro-recording draws only on the statusline in the bottom-right corner of the frame, so a split shows it once.

When the pane is too narrow, toe drops unpinned status items from the right section and then the left. Suffix an element with ! (for example "mode!" or "position!") to keep it visible.

[editor.statusline]
left = ["mode!", "file-name", "read-only-indicator", "file-modified-indicator"]
right = ["diagnostics", "selections", "position!"]

The selected register and the macro-recording indicator appear on the statusline in the bottom-right corner of the frame.

Example:

[editor.statusline]
left = ["mode", "file-name", "file-modified-indicator"]
right = ["version-control", "diagnostics", "position"]

Pickers#

Dragging a picker’s split divider adjusts its list/preview ratio, and dragging its border resizes it. Both are remembered per picker by auto-session rather than set in config.

Shell#

[editor]
shell = ["sh", "-c"]   # default on Unix; ["cmd", "/C"] on Windows

Config Example#

theme = "mocha"

[editor]
cursorline = true
soft-wrap.enable = true
auto-session = true
rulers = [80, 120]

[editor.cursor-shape]
normal = "block"
insert = "bar"

Language Config#

See Language Servers for languages.toml configuration.