Customise less Safely with a lesskey Source File

You will create a readable lesskey source file, use it directly with less, and define a small custom command without replacing the normal navigation keys. 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: less reads the source format itself.

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

1. Check the installed behaviour

Confirm the command and package version before relying on 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

The historical job of lesskey was to compile source into a binary file. That is why its name and options still mention output. The local manual marks the program as deprecated, because current less reads a source file directly. Treat lesskey as a format reference and compatibility tool, not as a required build step.

Checkpoint: if your version is earlier than 582, stop and read that version's manual before using the direct-source examples. The workflow below is for the installed version shown above.

2. Write a minimal source file

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

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

This maps Control-X followed by Control-Q to quit. The caret notation denotes a control key. A source file can omit #command when that is its first section, but keeping the header makes the file easier to extend and review.

Do not add #stop casually. It disables all default commands from that point in the command section. You would then need to define every action you still require, including a way to quit. A typo in a key binding can be annoying; a careless #stop can leave a session without the expected controls.

3. Test the source without installing it

Use less's explicit source option so the test does not depend on files already present 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 will open 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

The output path is a temporary test artefact. Do not copy it into a system directory. A successful exit status shows that version 590 accepted the source syntax; it does not prove that every key sequence is comfortable or available in every terminal.

4. Add a useful navigation binding

Once the minimal file works, add a binding that is easy to test. This example assigns the letter J to the documented forw-line-force action, which moves forward even when 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 press Control-X followed by Control-Q. If a key behaves differently from what you expected, remove that line and retest. Custom command definitions take precedence over less's default commands, so a binding can quietly change a familiar key.

Keys can be written literally, as control notation, or with escapes. For example, \en denotes newline, \et denotes Tab, and \ekD denotes Page Down. A backslash followed by one to three octal digits specifies a character by value. Escape spaces, tabs, carets and backslashes when they are part of the key string. Command key sequences may contain up to 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. 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. The command and line-edit action names are separate lists, and a spelling mistake is not a helpful shortcut. If you are unsure, start with the examples in the lesskey manual or run man less and inspect its line-editing section.

Checkpoint: test one section at a time. When a binding stops working, temporarily remove the newest section rather than changing several key definitions at once. That keeps the cause visible.

6. Set a less environment default cautiously

The #env section can set variables visible only to less. This is 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. In this example, searches are case-insensitive for that less invocation. A variable in the lesskey file takes precedence over the same variable in the process environment. Keep this section short: a setting that makes sense for one workflow may be surprising when you inspect logs, source code or sensitive data.

Do not use #env to store credentials, tokens or passwords. Do not set input preprocessor variables until you have reviewed exactly what command they invoke. Environment-driven preprocessors can execute programs and alter what less reads, which is a separate security decision.

7. Install the configuration only after the test

On Unix, less looks for a source file named $XDG_CONFIG_HOME/lesskey or, if that is not found, $HOME/.lesskey. You can also select a file explicitly with the LESSKEYIN environment variable. Inspect 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 make a backup first. This is the first state-changing step in the 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"

There is no reason to use elevated privileges for a user file. To undo this exact installation, restore the backup if one existed:

$ 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 to remove the new configuration, check the path carefully, then remove only $HOME/.lesskey. Do not run a broad recursive deletion while cleaning up a configuration test.