---
name: "mle"
section: "1"
platform: "linux"
package: "mle"
version: "1.7.2-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/mle"
---

# mle(1)

flexible terminal-based text editor

## NAME

**mle** – flexible terminal-based text editor

## SYNOPSIS

**mle** \[**-abceHhiKklMmNnpSstuvwxyz**\] \[*file\[:line\]*\] ...

## DESCRIPTION

**mle** is a small, flexible, terminal-based text editor written in C. It runs on Linux, Windows (Cygwin or WSL), FreeBSD, macOS, and more.

### Basic usage

```
  $ mle             # Open blank buffer
  $ mle one.c       # Edit one.c
  $ mle one.c:100   # Edit one.c at line 100
  $ mle one.c two.c # Edit one.c and two.c
  $ mle -h          # Show command line help
```

The default key bindings are intuitive. Input text as normal, use directional keys to move around, use \`Ctrl-S\` to save, \`Ctrl-O\` to open, \`Ctrl-X\` to exit.

Press \`F2\` for full help.

### Options

- **-h**

  Show help

- **-a** ⟨1\|0⟩

  Enable/disable tab to space (default: 1)

- **-b** ⟨1\|0⟩

  Enable/disable highlight bracket pairs (default: 1)

- **-c** *column*

  Color column (default: -1, disabled)

- **-e** ⟨1\|0⟩

  Enable/disable mouse support (default: 0)

- **-H** ⟨1\|0⟩

  Enable/disable headless mode (default: 1 if no tty, else 0)

- **-i** ⟨1\|0⟩

  Enable/disable auto indent (default: 0)

- **-K** *kdef*

  Make a kmap definition (use with -k).

  *kdef* is formatted as \`\<name\>,\<default\_cmd\>,\<allow\_fallthru\>\`, where *name* is the name of the kmap, *default\_cmd* is the default command handler (can be empty), and *allow\_fallthru* is a 0 or 1 specifying whether unhandled key input should be forwarded to the previous kmap on the stack or not.

- **-k** *kbind*

  Add key binding to current kmap definition (use after -K).

  *kbind* is formatted as \`\<cmd\>,\<key\>,\<param\>\`, where *cmd* is a command name, *key* is a key name, and *param* is a static parameter passed to the command (can be empty).

- **-l** *ltype*

  Set linenum type (default: 0, absolute).

  *ltype* can be 0 (absolute), 1 (relative), or 2 (both)

- **-M** *macro*

  Add a macro.

  *macro* is formatted as \`\<name\> \<key1\> \<key2\> ... \<keyN\>\`, where *name* is the name of the macro, and *keyN* are space-separated key names.

- **-m** *key*

  Set macro toggle key (default: M-r). *key* is a key name.

- **-N**

  Skip reading of rc file

- **-n** *kmap*

  Set init kmap (default: mle\_normal). *kmap* is a kmap name.

- **-p** *macro*

  Set startup macro. *macro* is a macro name.

- **-S** *syndef*

  Make a syntax definition (use with -s).

  *syndef* is formatted as \`\<name\>,\<path\_pattern\>,\<tab\_width\>,\<tab\_to\_space\>\`, where *name* is a syntax name, *path\_pattern* is a path matching regex (PCRE), *tab\_width* is the default tab width, *tab\_to\_space* is a 0 or 1 specifying whether to convert tabs to spaces or not.

- **-s** *synrule*

  Add syntax rule to current syntax definition (use after -S).

  *synrule* is formatted as \`\<start\>,\<end\>,\<fg\>,\<bg\>\`, where *start* and *end* are text matching regexes (PCRE), and *fg* and *bg* are attributes to apply to matching text.

  If both *start* and *end* are supplied, the rule applies to all text matched in between the regexes, potentially spanning multiple lines. If only *start* is specified, the rule applies to text matched by the regex on a single line.

  Attributes for *fg* and *bg* are as follows:

  - 0

    default

  - 1

    black

  - 2

    red

  - 4

    yellow

  - 5

    blue

  - 6

    magenta

  - 7

    cyan

  - 8

    white

  - 256

    bold

  - 512

    underline

  - 1024

    reverse

  - 2048

    italic

- **-t** *size*

  Set tab size (default: 4)

- **-u** ⟨1\|0⟩

  Enable/disable coarse undo/redo (default: 0)

- **-v**

  Print version and exit

- **-w** ⟨1\|0⟩

  Enable/disable soft word wrap (default: 0)

- **-x** *uscript*

  Run a Lua user script (experimental)

- **-y** *syntax*

  Set override syntax for files opened at start up. If '-' is specified, use the built-in generic syntax. *syntax* is any syntax name.

- **-z** ⟨1\|0⟩

  Enable/disable trimmed paste (default: 1)

## KEY NAMES

Key names for -k, -M, and -m are formatted as \`\<key\>\` or \`\<mod\>-\<key\>\`.

*key* is any character or one of the following: space, tab, enter, backspace, comma, up, down, left, right, insert, delete, home, end, pgup, pgdn, backtab, f1, f2, f3, f4, f5, f6, f7, f8, f9, f10, f11, f12.

*mod* is one of

- S

  Shift

- M

  Alt (Meta)

- MS

  Alt-Shift

- C

  Ctrl

- CS

  Ctrl-Shift

- CM

  Ctrl-Alt

- CMS

  Ctrl-Alt-Shift

Not all key names are valid or supported by all terminals. Run with \`-Qk\` to display key names for given input.

## ADVANCED USAGE

Below are some advanced things you can do with mle.

### rc file

To customize the editor, make an rc file named *~/.mlerc* or */etc/mlerc*. The contents of the rc file are any number of cli options separated by newlines. Lines that begin with a semi-colon are interpreted as comments.

If the rc file is executable, mle executes it and interprets the resulting stdout as described above. For example, consider the following snippet from an executable *~/.mlerc* [bash(1)](/bash/1.md) script:

```
  ...
  # Define 'test' kmap
  echo '-Ktest,,1'
  # M-q: replace grep with git grep if `.git` exists
  if [ -d ".git" ]; then
    echo '-kcmd_grep,M-q,git grep --color=never -P -i -I -n %s 2>/dev/null'
  fi
  # Set default kmap
  echo '-n test'
  ...
```

This overrides the built-in grep command with \`git grep\` if *.git* exists in the current working directory.

### Shell command integration

The following programs will enable or enhance certain features of mle if they exist in *PATH*.

- [bash(1)](/bash/1.md)

  file tab completion

- [fzf(1)](/fzf/1.md)

  fuzzy file search

- [grep(1)](/grep/1.md)

  file grep

- [less(1)](/less/1.md)

  less integration

- [perl(1)](/perl/1.md)

  perl 1-liners

- [readtags(1)](/readtags/1.md)

  ctags integration

- [tree(1)](/tree/1.md)

  file browsing

Arbitrary shell commands can also be run via \`cmd\_shell\` (M-e by default). If any text is selected, it is sent to stdin of the command. Any resulting stdout is inserted into the text buffer.

### Headless mode

mle provides support for non-interactive editing which may be useful for using the editor as a regular command line tool. In headless mode, mle reads stdin into a buffer, applies a startup macro if specified, and then writes the buffer contents to stdout. For example:

```
  $ echo -n hello | mle -M 'test C-e space w o r l d enter' -p test
  hello world
```

If stdin is a pipe, mle goes into headless mode automatically. Headless mode can be explicitly enabled or disabled with the \`-H\` option.

If stdin is a pipe and headless mode is disabled via -H0, mle reads stdin into a new buffer and then runs as normal in interactive mode.

### Scripting (experimental)

mle is extensible via the Lua programming language. Scripts are loaded via the \`-x\` cli option. Commands registered by scripts can be mapped to keys as normal via \`-k\`. See **https://github.com/adsr/mle** for more info.

## ACKNOWLEDGEMENTS

mle makes extensive use of the following libraries.

- *uthash*

  for hash maps and linked lists

- *termbox2*

  for TUI

- *PCRE2*

  for syntax highlighting and search