LXCONFIG.TOML(5)

NAME
lxconfig.toml - configuration file for lx(1)

SYNOPSIS
~/.lxconfig.toml

$XDG_CONFIG_HOME/lx/config.toml

~/Library/Application Support/lx/config.toml

DESCRIPTION
The lx configuration file is written in TOML. lx searches for it in these locations (first found wins):
1.  LX_CONFIG — explicit path override
2.  ~/.lxconfig.toml
3.  $XDG_CONFIG_HOME/lx/config.toml (default ~/.config/lx/config.toml)
4.  ~/Library/Application Support/lx/config.toml (macOS only)

Run lx --init-config to generate a commented starter file at ~/.lxconfig.toml. It has the following top-level sections:

version
    Config schema version (required).

[format]
    Named column layouts for long view (flat section; each key is a format name).

[personality.NAME]
    Named bundles of format, columns, and settings.

[theme.NAME]
    Named colour themes for UI elements.

[class]
    File-type class definitions — named lists of glob patterns.

[style.NAME]
    Named sets of file colour rules. Can reference classes by name and/or match files directly by glob pattern or exact filename.

VERSIONING
Every configuration file must declare a schema version at the top:

    version = "0.6"

This is the config schema version, not the lx release version. It only increments when the config format changes in a way that requires migration.

(none)
    lx 0.1.x — original format with [defaults]
0.2 lx 0.2.0+ — personalities replace [defaults]
0.3 lx 0.3.0+ — classes, flat formats, exa style chain
0.4 lx 0.7.0+ — conditional overrides ([[when]] blocks)
0.5 lx 0.8.0+ — time and numeric settings removed; timestamps and UID/GID now ordinary columns
0.6 lx 0.9.0+ — [[when]] env conditions accept TOML arrays and glob patterns

Versions 0.3, 0.4, and 0.5 are still accepted by lx 0.9+ (0.6 is a strict superset), with caveats: [[when]] blocks in a 0.3 config trigger a warning, and the time = "..." and numeric = ... settings (valid in 0.3/0.4) trigger deprecation warnings at load time and are ignored.

If lx encounters a config file with an older version (or no version field), it refuses to load it and prints a message directing the user to run:

    lx --upgrade-config

This command migrates the config from any older version (0.1 through 0.5) to the current format and saves the original as ~/.lxconfig.toml.bak. Migrations from 0.1 and 0.2 restructure the file (flattening formats, converting [defaults] to personalities). Migrations from 0.3, 0.4, and 0.5 bump the version string and inject auto-selection [[when]] blocks into [personality.default]; they also warn if the removed time or numeric settings are present.

FORMATS
A format defines a column layout for long view. Formats are defined as keys in a flat [format] section. Each key is a format name; its value is either a TOML array or a comma-separated string of column names:

    [format]
    long  = ["permissions", "size", "user", "modified"]
    long2 = ["permissions", "size", "user", "group", "modified", "vcs"]
    long3 = ["permissions", "links", "size", "blocks", "user", "group",
             "modified", "changed", "created", "accessed", "vcs"]
    compact = "permissions,size,modified"

Three compiled-in formats correspond to the -l tier system:
Tier 1: -l
    long — permissions, size, user, modified
Tier 2: -ll
    long2 — permissions, size, user, group, modified, vcs
Tier 3: -lll
    long3 — permissions, links, size, blocks, user, group, modified, changed, created, accessed, vcs

Defining a format with a compiled-in name in the config file overrides the built-in. Custom formats are used via --format=NAME or referenced from personality definitions.

  Valid column names
permissions (aliases perms, mode)
    File permissions.
size (alias filesize)
    File size.
user
    Owning user.
group
    Owning group.
links
    Hard link count.
inode
    Inode number.
blocks
    File system block count.
octal
    Octal permissions.
modified
    Last modification timestamp.
changed
    Last status change timestamp.
accessed
    Last access timestamp.
created
    Creation timestamp.
vcs VCS status column.

PERSONALITIES
A personality bundles a named set of settings — including a column layout — under a name. Invoke a personality with --personality=NAME, -p NAME, or via an argv[0] symlink.

    [personality.ll]
    inherits = "lx"
    format = "long2"
    group-dirs = "first"

  Structural fields

description
    Optional one-line summary, surfaced by --show-config and emitted by --dump-personality.

inherits
    Name of a parent personality (see Inheritance below).

format
    Reference to a named format (looked up in [format]).

columns
    Inline column list; overrides format if both are given. Accepts a TOML array or comma-separated string.

All other keys in a personality section are settings — each corresponds to a CLI flag (see lx(1) for the full flag reference). Value flags take a string or integer. Boolean flags have three states:
true
    Enable (emit the flag).
false
    Suppress, even if inherited from a parent personality or format. For example, size = false in a child personality suppresses the size column that the parent's format would otherwise include.
absent
    No opinion — inherit from the parent personality, or use the compiled-in default if the key does not appear in any ancestor.

The legacy no-* keys (no-size = true, etc.) are still accepted and equivalent to setting the positive key to false.

  Setting keys
Display options:
oneline (bool), long (bool), grid (bool), across (bool), recurse (bool), tree (bool), classify (string: always/auto/never), colour (string: always/auto/never), gradient (string: comma-separated size/date/modified/accessed/changed/created, or all/none), smooth (bool: interpolate gradients between anchors on 24-bit themes), icons (string: always/auto/never), width (integer), absolute (bool), hyperlink (string: always/auto/never), quotes (string: always/auto/never), theme (string: named theme), count (bool).

Filtering and sorting:
all (bool), dot-entries (bool), list-dirs (bool), level (integer), reverse (bool), sort (string), group-dirs (string: first/last/none), only-dirs (bool), only-files (bool), ignore (string: pipe-separated globs), prune (string: pipe-separated globs), symlinks (string: show/hide/follow), filesystem (string: same/local/all).

Long view options:
size-style (string: decimal/binary/bytes), binary (bool), bytes (bool), header (bool), inode (bool), links (bool), blocks (bool), group (bool), uid (bool), gid (bool), time-style (string: default/iso/long-iso/full-iso/relative/+FORMAT), modified (bool), changed (bool), accessed (bool), created (bool), total (bool), extended (bool), xattr-indicator (bool), octal (bool), flags (bool), permissions (bool), size (bool), user (bool).

filesize, total-size, and octal-permissions are accepted as backward-compatible aliases for size, total, and octal respectively.

Layout tuning:

grid-rows (integer)
    Minimum rows before the grid-details view activates. Equivalent to the LX_GRID_ROWS environment variable; the config key takes precedence.

icon-spacing (integer)
    Number of spaces between an icon and its filename. Equivalent to LX_ICON_SPACING; the config key takes precedence.

Numeric formatting:

decimal-point (string)
    Override the locale's decimal separator. Exactly one character.

thousands-separator (string)
    Override the locale's thousands separator. Zero or one character; empty string disables grouping.

Both apply to counts (file sizes in all size-style modes, --total totals, -CZ summaries, block counts, link counts) but not to IDs (inodes, UID, GID). Always 3-digit grouping. Setting these in [personality.default] makes them global.

Removed in 0.5: time (string naming a single timestamp field) and numeric (boolean). The time setting is replaced by the individual modified/changed/accessed/created booleans (which are additive in 0.8+); set no-time = true to start from an empty timestamp set. The numeric setting is replaced by the new first-class uid and gid columns. For the old ls -n-style numeric-only view, use uid = true, gid = true, no-user = true, no-group = true — or better, use --columns to pick exactly the columns you want.

VCS:
vcs (string: auto/git/jj/none), vcs-status (bool), vcs-ignore (bool), vcs-repos (bool).

Special case: no-time = true clears all timestamp columns from the base format as a bulk shortcut; it runs before individual adds, so combining it with accessed = true leaves just the accessed column. no-time has no positive counterpart and cannot be expressed as time = false.

  Inheritance
Personalities support single inheritance via inherits = "NAME". The child's format and columns replace the parent's entirely. Settings are merged key-by-key, with the child's values winning on conflict.

Inheritance chains of arbitrary depth are supported. Cycle detection prevents infinite loops.

A common pattern is to define a shared base personality:

    default ---+---> lx ---+---> ll ---+---> lt
               |           |           \---> la
               |           \---> lll
               \---> tree
    ls  (standalone -- no inherits)

Example:

    [personality.default]
    colour = "auto"
    time-style = "default"
    group-dirs = "none"
    icons = "never"
    [personality.lx]
    inherits = "default"
    [personality.ll]
    inherits = "lx"
    format = "long2"
    group-dirs = "first"
    [personality.lt]
    inherits = "ll"
    sort = "age"
    [personality.ls]
    grid = true
    across = true

In this example, lt inherits group-dirs = "first" and format = "long2" from ll, which in turn inherits colour = "auto" and the other defaults from lx and default. The ls personality stands alone — it has no inherits and receives no inherited settings.

Compiled-in personalities (ll, la, lll, tree, ls) are used as fallbacks when a name is not defined in the config file.

  Conditional overrides
A personality's settings can vary based on environment variables using [[personality.NAME.when]] blocks. Each block specifies conditions and settings to overlay when all conditions match.

Conditions use env.VAR = value where the TOML value type determines the check:

env.VAR = "string"
    Exact string match against the variable's value. If the string contains any of ‘*’, ‘’?, or ‘[’, it is matched as a glob pattern instead (added in 0.6).

env.VAR = ["string", "string"]
    TOML array — matches if any element matches. Each element is independently matched as a literal or a glob. Added in 0.6.

env.VAR = true
    Variable must be set (to any value, including empty).

env.VAR = false
    Variable must be truly unset (not just empty).

A block can also gate on the host operating system using the platform key, matched against Rust's std::env::consts::OS (values macos, linux, freebsd, openbsd, netbsd, etc.):

platform = "string"
    Exact match against the host OS name.

platform = ["string", "string"]
    TOML array — matches if any element matches.

All conditions within a single block must match (AND logic). env and platform conditions can be combined freely.

Examples:

    # Icons only in terminals with Nerd Font support.
    [personality.lx]
    icons = "never"
    [[personality.lx.when]]
    env.TERM_PROGRAM = "ghostty"
    icons = "always"
    # Disable colour over SSH.
    [[personality.lx.when]]
    env.SSH_CONNECTION = true
    colour = "never"
    # Auto-select theme tier based on terminal capability.
    # Glob match against TERM, array of accepted COLORTERM values.
    [personality.default]
    theme = "exa"
    [[personality.default.when]]
    env.TERM = "*-256color"
    theme = "lx-256"
    [[personality.default.when]]
    env.COLORTERM = ["truecolor", "24bit"]
    theme = "lx-24bit"
    # Platform-conditional default: enable the xattr `@` indicator
    # everywhere except on macOS, where listxattr is expensive.
    [personality.lx]
    xattr-indicator = true
    [[personality.lx.when]]
    platform = "macos"
    xattr-indicator = false

Evaluation rules:
•   All conditions in a block must match (AND logic).
•   Multiple when blocks are tried in order; all matching blocks apply, with later blocks overriding earlier ones.
•   The base personality (without when) is the default when no block matches.
•   when blocks are inherited: a parent personality's when blocks are applied first, then the child's.

Requires version = "0.4" or later in the config file.

  argv[0] dispatch
When lx is invoked via a symlink whose name matches a personality, that personality is applied automatically. For example, if ll is a symlink to lx, running ll is equivalent to lx -pll.

THEMES
A theme defines colours for UI elements. Themes are selected through personalities (theme = "NAME") or the --theme=NAME CLI flag.

    [theme.ocean]
    inherits = "exa"
    directory = "bold dodgerblue"
    executable = "bold springgreen"
    symlink = "mediumturquoise"
    date = "steelblue"

  Structural fields

description
    Optional one-line summary, surfaced by --show-config and emitted by --dump-theme.

inherits
    Inherit from another theme. The parent's UI keys are applied first; this theme's keys override. The special name "exa" refers to the compiled-in default theme. Without inherits, a theme starts from a blank slate.

use-style
    Name of a [style.NAME] set to apply.

  Theme keys
All other keys in a theme section set the colour for a specific element. Each key takes a colour value (see COLOUR VALUES below).

File kinds:
normal
    regular files with no special properties
directory
    directories
symlink
    symbolic links (the link itself, not its target)
pipe
    named pipes (FIFOs)
block-device
    block device files
char-device
    character device files
socket
    UNIX domain sockets
special
    other special file types
executable
    files with the execute bit set
broken-symlink
    symlinks whose target does not exist

Filename display:
symlink-path
    the target path shown after a symlink arrow
control-char
    escaped control characters in filenames
broken-overlay
    a style modifier applied on top of broken-symlink and control-char when rendering broken symlink targets (default: underline)

Permissions:

Nine keys for the rwx bits, split by user/group/other:
permissions-user-read, permissions-user-write, permissions-user-execute, permissions-group-read, permissions-group-write, permissions-group-execute, permissions-other-read, permissions-other-write, permissions-other-execute.

Plus five special keys:
permissions-user-execute-other
    the execute bit on files owned by another user
permissions-special-user
    setuid bit
permissions-special-other
    setgid and sticky bits
permissions-attribute
    extended attributes marker (@)
octal
    octal permission digits (-o)

The legacy short forms perm-user-read, perm-user-exec, etc. and mode-user-read, mode-user-exec, etc. are also accepted as aliases.

Size (magnitude-based gradient):

File sizes are rendered in two parts: a number and a unit suffix. Each part has five magnitude tiers:
size-number-byte, size-unit-byte
    < 1 KB (bytes)
size-number-kilo, size-unit-kilo
    kilobytes / kibibytes
size-number-mega, size-unit-mega
    megabytes / mebibytes
size-number-giga, size-unit-giga
    gigabytes / gibibytes
size-number-huge, size-unit-huge
    terabytes and above
size-number
    bulk setter — sets all five number tiers at once
size-unit
    bulk setter — sets all five unit tiers at once
size-major
    the single colour all size numbers collapse to when the size gradient is disabled; also used for device major numbers
size-minor
    the single colour all size units collapse to when the size gradient is disabled; also used for device minor numbers

Setting size-number alone is backwards compatible — all number tiers render in the same colour, and size-major is also set so the column collapses correctly when the gradient is turned off. The same applies to size-unit and size-minor.

Users and groups:
user-you
    the current user's own name
user-other
    any other user
group-yours
    your primary group
group-member
    a supplementary group you belong to (you have group-permission access)
group-other
    a group you do not belong to

The uid-* and gid-* keys use the same three tiers (*-you/*-yours, *-member, *-other) and style the dedicated --uid and --gid numeric ID columns:
uid-you, uid-other, gid-yours, gid-member, gid-other.

Links:
links
    hard-link count (single link)
links-multi
    hard-link count when the file has multiple hard links

VCS:
vcs-new
    newly added / untracked file
vcs-modified
    modified file
vcs-deleted
    deleted file
vcs-renamed
    renamed file
vcs-typechange
    file whose type changed (e.g. regular → symlink)
vcs-ignored
    file matched by ignore rules
vcs-conflicted
    file with unresolved merge conflicts

Other columns:
inode
    inode numbers (-i)
blocks
    file-system block counts (-S)

Display:
header
    column header text (-h)
punctuation
    separator characters: permission dashes, the device-ID comma, the symlink arrow, and placeholder dashes in empty columns

Timestamps (age-based gradient):
date
    bulk setter — sets all tiers at once on every timestamp column
date-now
    < 1 hour
date-today
    < 24 hours
date-week
    < 7 days
date-month
    < 30 days
date-year
    < 365 days
date-old
    > 1 year
date-flat
    the single colour each timestamp column uses when its gradient is disabled

Setting date alone is backwards compatible — all timestamps render in the same colour, including the flat fallback. Setting individual tiers creates a gradient that shows file age at a glance, and date-flat lets a theme define what colour the column collapses to when the gradient is turned off.

Per-timestamp-column overrides: Each of the four timestamp columns (modified, accessed, changed, created) can be themed independently. For each column, the same eight slots exist with a date-col- prefix:
date-modified
    bulk setter for the modified column
date-modified-now, date-modified-today, date-modified-week, date-modified-month, date-modified-year, date-modified-old
    per-tier overrides for the modified column
date-modified-flat
    flat fallback for the modified column when its gradient is disabled

The same eight keys exist for date-accessed-*, date-changed-*, and date-created-* (32 per-column keys total). Per-column overrides write directly to the named field; only the unprefixed date-* keys above fan out to all four columns at once.

Fall-through is automatic. lx applies theme keys by specificity: the bulk date = ... setter first, then bulk per-tier setters (date-now, date-today, ...), then bulk per-column setters (date-modified, date-accessed, ...), then per-column per-tier overrides (date-modified-now, ...). This means you can write them in any order in the theme block — the most specific key always wins. Example:

    [theme.example]
    date              = "blue"           # every column, every tier
    date-now          = "bright cyan"    # now-tier on every column
    date-modified-now = "bright green"   # only the modified column's now

End state: the modified column's now tier is bright green, the other three columns' now tiers are bright cyan, and every other tier on every column is blue.

  The compiled-in exa theme
The special theme name "exa" provides the following defaults. Use inherits = "exa" and override individual keys to customise:

    [theme.exa]
    # File kinds
    normal = ""
    directory = "bold blue"
    symlink = "cyan"
    pipe = "yellow"
    block-device = "bold yellow"
    char-device = "bold yellow"
    socket = "bold red"
    special = "yellow"
    executable = "bold green"
    # Permissions
    permissions-user-read = "bold yellow"
    permissions-user-write = "bold red"
    permissions-user-execute = "bold underline green"
    permissions-user-execute-other = "bold green"
    permissions-group-read = "yellow"
    permissions-group-write = "red"
    permissions-group-execute = "green"
    permissions-other-read = "yellow"
    permissions-other-write = "red"
    permissions-other-execute = "green"
    permissions-special-user = "purple"
    permissions-special-other = "purple"
    permissions-attribute = ""
    # Size (set per-tier keys size-number-byte..huge for a
    # gradient; see --gradient(1) to switch the gradient on/off)
    size-number = "bold green"
    size-unit = "green"
    size-major = "bold green"
    size-minor = "green"
    # Users and groups
    user-you = "bold yellow"
    user-other = ""
    group-yours = "bold yellow"
    group-other = ""
    # Links
    links = "bold red"
    links-multi = "bold red"
    # VCS status
    vcs-new = "green"
    vcs-modified = "blue"
    vcs-deleted = "red"
    vcs-renamed = "yellow"
    vcs-typechange = "purple"
    vcs-ignored = "dimmed"
    vcs-conflicted = "red"
    # UI elements
    punctuation = "38;5;244"
    date = "blue"
    inode = "purple"
    blocks = "cyan"
    header = "underline"
    octal = "purple"
    symlink-path = "cyan"
    control-char = "red"
    broken-symlink = "red"
    broken-overlay = "underline"

CLASSES
The [class] section defines named lists of glob patterns that represent file-type categories. Classes are referenced from styles (see below).

    [class]
    source = ["*.rs", "*.py", "*.js", "*.go", "*.c"]
    data   = ["*.csv", "*.json", "*.xml", "*.yaml"]

User-defined classes in [class] override any compiled-in definition of the same name.

  Compiled-in class definitions
lx ships with the following compiled-in classes. To override one, redefine it in [class] with the same name.

    image:
        *.png *.jfi *.jfif *.jif *.jpe *.jpeg *.jpg *.gif *.bmp
        *.tiff *.tif *.ppm *.pgm *.pbm *.pnm *.webp *.raw *.arw
        *.svg *.stl *.eps *.dvi *.ps *.cbr *.jpf *.cbz *.xpm
        *.ico *.cr2 *.orf *.nef *.heif *.avif *.jxl *.j2k *.jp2
        *.j2c *.jpx
    video:
        *.avi *.flv *.m2v *.m4v *.mkv *.mov *.mp4 *.mpeg *.mpg
        *.ogm *.ogv *.vob *.wmv *.webm *.m2ts *.heic
    music:
        *.aac *.m4a *.mp3 *.ogg *.wma *.mka *.opus
    lossless:
        *.alac *.ape *.flac *.wav
    crypto:
        *.asc *.enc *.gpg *.pgp *.sig *.signature *.pfx *.p12
    document:
        *.djvu *.doc *.docx *.dvi *.eml *.eps *.fotd *.key
        *.keynote *.numbers *.odp *.odt *.pages *.pdf *.ppt
        *.pptx *.rtf *.xls *.xlsx
    compressed:
        *.zip *.tar *.Z *.z *.gz *.bz2 *.a *.ar *.7z *.iso *.dmg
        *.tc *.rar *.par *.tgz *.xz *.txz *.lz *.tlz *.lzma
        *.deb *.rpm *.zst *.lz4 *.cpio
    compiled:
        *.class *.elc *.hi *.o *.pyc *.zwc *.ko
    temp:
        *.tmp *.swp *.swo *.swn *.bak *.bkp *.bk
    immediate:
        Makefile Cargo.toml SConstruct CMakeLists.txt build.gradle
        pom.xml Rakefile package.json Gruntfile.js Gruntfile.coffee
        BUILD BUILD.bazel WORKSPACE build.xml Podfile
        webpack.config.js meson.build composer.json RoboFile.php
        PKGBUILD Justfile Procfile Dockerfile Containerfile
        Vagrantfile Brewfile Gemfile Pipfile build.sbt mix.exs
        bsconfig.json tsconfig.json

STYLES
Named sets of file colour rules, referenced from themes via use-style = "NAME".

Styles can reference classes using bare dotted TOML keys, or match files directly using quoted keys:

class.NAME = "colour"
    Reference a named class. Applies the colour to every pattern in the class definition.

"*.ext" = "colour"
    Glob pattern (quoted key containing metacharacters ‘*’, ‘’?, ‘[’).

"Makefile" = "colour"
    Exact filename match (quoted key without metacharacters).

All file pattern keys must be quoted. Bare unquoted keys are reserved for class references.

    [style.exa]
    class.temp       = "38;5;244"
    class.immediate  = "bold underline yellow"
    class.image      = "38;5;133"
    class.video      = "38;5;135"
    class.music      = "38;5;92"
    class.lossless   = "38;5;93"
    class.crypto     = "38;5;109"
    class.document   = "38;5;105"
    class.compressed = "red"
    class.compiled   = "38;5;137"
    [style.dev]
    class.source     = "#ff8700"
    "*.toml"         = "sandybrown"
    "*.md"           = "cornflowerblue"
    "Makefile"       = "bold underline yellow"
    "Cargo.toml"     = "bold #ff8700"

The compiled-in "exa" style provides default file-type colouring. To disable it, use a theme that references a different style (or no style at all). If two classes have overlapping patterns, the result is unspecified.

COLOUR VALUES
Colour values in themes and style sets accept a space-separated string of modifiers and a colour specifier. Tokens may appear in any order.

Modifiers:
bold, dimmed (alias dim), italic, underline, strikethrough, blink, reverse, hidden.

Named ANSI colours:
black, red, green, yellow, blue, purple (alias magenta), cyan, white.

X11/CSS colour names: The full set of ~148 standard X11 colour names is supported (case-insensitive). Examples: tomato, cornflowerblue, darkslategray, dodgerblue, springgreen, salmon, peru, steelblue, wheat.

Hex: #RRGGBB or #RGB. Examples: #ff8700, #f00.

256-colour: Raw ANSI 256-colour code: 38;5;NUMBER (foreground) or 48;5;NUMBER (background). Example: 38;5;208.

RGB: Raw ANSI true-colour code: 38;2;R;G;B (foreground) or 48;2;R;G;B (background). Example: 38;2;255;135;0.

Modifiers can be combined with any colour specifier:

    "bold blue"
    "bold underline red"
    "dimmed cyan"
    "bold #ff8700"
    "bold tomato"
    "italic 38;5;208"

A value containing only modifiers (e.g. "bold underline") uses the terminal's default foreground colour.

PRECEDENCE
Colour settings are resolved in the following order, from lowest to highest priority:

1.  Built-in defaults — the compiled-in exa theme.

2.  LS_COLORS — standard file-type colour scheme.

3.  Theme — config-file theme (selected via personality or --theme). The theme's UI element keys and style set colours override all environment variable settings.

Within a theme, inherits is resolved first (parent applied, then child overrides). Style sets referenced by use-style are applied after UI element keys. The compiled-in "exa" style provides default file-type colouring; to disable it, use a theme that references a different style or no style at all.

SEE ALSO
lx(1)

REFERENCES
Björn Ottosson, A perceptual color space for image processing, 2020, https://bottosson.github.io/posts/oklab/.

AUTHORS
lx is maintained by Johann Visagie, based on exa by Benjamin Sago. Source code: https://github.com/wjv/lx