Customise less Safely with lesskey

less ships with a key layout most people never touch, but lesskey lets you rebind it or set safe defaults. It can add a completion shortcut too, without editing anything system-wide. You will build a small source file, test it live with less before installing it, and know exactly how to back out. The installed program is lesskey version 590 from the less package, version 590-2ubuntu2.1. In less version 582 and later, compiling the file is normally unnecessary because less reads the source format directly.

Allow about fifteen minutes. You need a shell, the less package and a text editor. The examples work under /tmp first, so nothing touches your normal less configuration until the last step. No command needs sudo. Do not put secrets in a lesskey file: values in its #env section are passed to less and can affect the files or commands it opens.

1. Check the installed behaviour

Confirm the command and package version before trusting older instructions:

$ command -v lesskey
/usr/bin/lesskey
$ lesskey --version
lesskey  version 590
$ dpkg-query -W -f='${Package} ${Version}\n' less
less 590-2ubuntu2.1

lesskey's historical job was to compile a source file into a binary one, which is why its name and options still talk about output. The local manual marks it as deprecated, because current less reads a source file directly. Treat it as a format reference and compatibility tool, not a required build step.

2. Write a minimal source file

Create a temporary file with one command binding. The key sequence goes on the left, whitespace separates it from the action, and the action is a name less understands:

$ work=/tmp/lesskey-demo
$ mkdir -p "$work"
$ cat > "$work/lesskey" <<'EOF'
#command
^X^Q quit
EOF

• The caret notation is a control key. This maps Control-X then Control-Q to quit.
• #command can be omitted when it is the first section, but keeping it makes the file easier to extend.

3. Test the source without installing it

Use less's explicit source option so the test does not depend on anything already in your home directory. Prepare a tiny input file, then open it with --lesskey-src:

$ printf '%s\n' 'first line' 'second line' > "$work/input.txt"
$ less --lesskey-src="$work/lesskey" "$work/input.txt"

less opens normally. Press Control-X, then Control-Q, to leave it. The source file is read for this invocation only. If you want a non-interactive smoke test for the file parser, the deprecated compiler still accepts the same source:

$ lesskey -o "$work/compiled" "$work/lesskey"
NOTE: lesskey is deprecated.
      It is no longer necessary to run lesskey,
      when using less version 582 and later.
$ file "$work/compiled"
/tmp/lesskey-demo/compiled: data

That output path is a throwaway test artefact; do not copy it into a system directory. A successful exit status shows that version 590 accepted the syntax, nothing more. It does not prove every key sequence is comfortable, or even available, in every terminal.

4. Add a useful navigation binding

Once the minimal file works, add a binding you can test by eye. This assigns the letter J to the documented forw-line-force action, which moves forward even while a line is being wrapped:

$ cat > "$work/lesskey" <<'EOF'
#command
^X^Q quit
J forw-line-force
EOF
$ less --lesskey-src="$work/lesskey" "$work/input.txt"

Press J and watch the prompt or text move, then Control-X, Control-Q to leave. If a key behaves differently from what you expected, remove that line and retest one change at a time. Custom bindings take precedence over less's defaults, so one line can quietly change a key you rely on.

• \en denotes newline, \et denotes Tab, \ekD denotes Page Down.
• A backslash plus one to three octal digits specifies a character by value.
• Escape spaces, tabs, carets and backslashes whenever they are part of the key string itself.
• Command sequences cap out at 15 keys.

5. Keep line editing separate from commands

Use a #line-edit section when you mean the prompt's editing keys, not ordinary less commands. The two sections are not interchangeable:

$ cat > "$work/lesskey" <<'EOF'
#command
^X^Q quit

#line-edit
\et forw-complete
EOF

This uses the documented Tab binding as a simple completion example. Command and line-edit action names are separate lists, and a spelling mistake there is not a helpful shortcut to anything. When unsure, start from the examples in the lesskey manual, or run man less and read its line-editing section.

6. Set a less environment default cautiously

The #env section can set variables visible only to less, useful when you want a setting to travel with the key configuration:

$ cat > "$work/lesskey" <<'EOF'
#command
^X^Q quit

#env
LESS = -i
EOF
$ less --lesskey-src="$work/lesskey" "$work/input.txt"

Whitespace around the equals sign is ignored. Here searches become case-insensitive for that one less invocation. A variable set in the lesskey file overrides the same variable in the process environment, so keep this section short: something that makes sense for one workflow can be surprising when you are looking at logs, source code or sensitive data instead.

7. Install the configuration only after the test

On Unix, less looks for a source file named $XDG_CONFIG_HOME/lesskey or, failing that, $HOME/.lesskey. You can also point at a file explicitly with LESSKEYIN. Check the destination before copying anything:

$ printf 'XDG_CONFIG_HOME=%s\n' "${XDG_CONFIG_HOME-}"
$ printf 'HOME=%s\n' "$HOME"
$ test -e "$HOME/.lesskey" && ls -l "$HOME/.lesskey" || printf '%s\n' 'no existing ~/.lesskey'

Installing a user configuration changes future less sessions, so back it up first. This is the first state-changing step in the whole guide:

$ cp --preserve=all "$work/lesskey" "$HOME/.lesskey.new"
$ test ! -e "$HOME/.lesskey" || cp --preserve=all "$HOME/.lesskey" "$HOME/.lesskey.backup"
$ mv "$HOME/.lesskey.new" "$HOME/.lesskey"
$ less "$work/input.txt"

$ test -e "$HOME/.lesskey.backup" && mv "$HOME/.lesskey.backup" "$HOME/.lesskey"
$ test ! -e "$HOME/.lesskey.backup" && printf '%s\n' 'backup restored or no previous file existed'

If there was no previous file and you want the new configuration gone, check the path carefully and remove only $HOME/.lesskey. Do not run a broad recursive deletion while cleaning up a configuration test.