elio

DOCS

elio docs

A quick reference for the files you edit most and what each one controls.

FILES

Paths

elio uses two config files: config.toml and theme.toml

Config file

Linux / BSD ~/.config/elio/config.toml $XDG_CONFIG_HOME/elio/config.toml
macOS ~/Library/Application Support/elio/config.toml
Windows %APPDATA%\elio\config.toml

Use this file for startup behavior, Places, layout, and key overrides.

Theme file

Linux / BSD ~/.config/elio/theme.toml $XDG_CONFIG_HOME/elio/theme.toml
macOS ~/Library/Application Support/elio/theme.toml
Windows %APPDATA%\elio\theme.toml

Theme files layer on top of the built-in defaults, so you only need to set the values you want to change.

CONFIG

What goes in config.toml

Sections

  • [ui] Startup options like top bar, hidden files, grid view, and grid zoom.
  • [places] Pinned sidebar entries and whether the Devices section stays visible.
  • [layout.panes] Relative pane widths for Places, Files, and Preview.
  • [keys] Single-character overrides for browser action keys.

Rules

  • Leave a section out to keep the built-in default behavior.
  • grid_zoom is clamped to 0, 1, or 2.
  • places.entries can use built-ins like downloads or custom paths starting with ~/.
  • In [layout.panes], places = 0 hides Places and preview = 0 hides Preview, but files must stay above 0.

THEME

What goes in theme.toml

Sections

  • [palette] App-wide colors for chrome, panels, borders, text, and selection.
  • [preview.code] Syntax colors for code previews.
  • [classes.<name>] Default icon and color for a file class.
  • [extensions.<ext>] Overrides by file extension.
  • [files."name"] Overrides by exact filename.
  • [directories."name"] Overrides by exact directory name.

Rules

  • Exact filename and directory rules win over extension rules, and extension rules win over class defaults.
  • Matching is case-insensitive.
  • Invalid theme files fall back to the built-in defaults.
  • Built-in classes
    directorycodeconfigdocumentlicenseimageaudiovideoarchivefontdatafile

PREVIEWS

Image previews

Inline visual previews, including images, covers, thumbnails, and rendered pages, work automatically on supported terminals.

Supported terminals

Terminal Protocol Status
Kitty Kitty Graphics Protocol Auto-detected
Ghostty Kitty Graphics Protocol Auto-detected
Warp Kitty Graphics Protocol Auto-detected
WezTerm iTerm2 Inline Protocol Auto-detected
iTerm2 iTerm2 Inline Protocol Auto-detected
foot Sixel Auto-detected
Windows Terminal Sixel Auto-detected
Alacritty None Not supported
Other Kitty Graphics Protocol Manual enable

How it works

  • elio supports Kitty Graphics Protocol, iTerm2 Inline Protocol, and Sixel for inline image previews.
  • For other terminals, set ELIO_IMAGE_PREVIEWS=1 to opt into Kitty Graphics Protocol.
  • Alacritty does not support inline image previews.

REFERENCE

Open the full reference

Use this page for the short version, then open the exact file or guide you need.

Example config

Annotated config for UI, Places, layout, and keys.

Open reference

Default theme

Built-in theme with palette, preview, classes, and overrides.

Open reference

Bundled themes

Copyable themes with screenshots.

Open reference

Previews and tools

Preview coverage, image support, and optional tools.

Open reference

Full README

Install, workflow, previews, config, and theming.

Open reference