KEYMAP

The keymap command manages SQLcl editor key bindings for the inline command editor.

Use this command to:

View current key bindings
Bind keys to editor actions
Remove bindings
Detect terminal key sequences
Reset keymaps to defaults
Find keys associated with an action
Export and import keymap configurations

The keymap command is available only in interactive SQLcl sessions.

Syntax

keymap list [emacs|vicmd|viins|visual] [-bound|-unbound] [filter]
keymap bind <mode> (<key>|-detect) <action-id>
keymap unbind <mode> <key>
keymap detect [<key>]
keymap reset [emacs|vicmd|viins|visual|all]
keymap keys <action-id> [mode]
keymap export [<file>]
keymap import <file>

Parameters

Parameter	Description
mode	Editor mode to inspect or modify. Valid values are emacs, vicmd, viins, visual.
key	Key sequence in SQLcl/JLine notation, such as ^R, ^[a, or ^[[A.
action-id	Widget or action to bind. Use `keymap list -unbound` to view available unbound actions.
filter	Limits `keymap list` output to entries whose displayed key, action, or description matches the filter text.
file	File path used for export or import operations.

Subcommands

Keymap List

Displays current bindings for the specified editor mode.
If no mode is specified, SQLcl displays the bindings for the active editor family. Key bindings apply only to the editor mode in which they are defined.
- When SQLcl uses Emacs editing, bindings for macs are displayed.
- When SQLcl uses vi editing, bindings for vicmd, viins, and visual are displayed.
By default, only bound actions are displayed.

Options
- -bound: Displays bound actions
- -unbound: Displays actions that do not have a key binding in the selected mode.
You can specify both options together.

Examples
```
keymap list 
keymap list viins 
keymap list viins -unbound 
keymap list viins history
```
KEYMAP bind

Binds a key sequence to an action in the selected mode.
```
keymap bind <mode> (<key>|-detect) <action-id>
```
If you specify -detect, SQLcl prompts you to press a key sequence and binds the detected sequence to the specified action.

Examples
```
keymap bind viins ^o cl-run-immediately 
keymap bind emacs ^r history-incremental-search-backward 
keymap bind viins -detect cl-run-immediately 
keymap unbind viins ^o
```
KEYMAP unbind

Removes the current binding for the specified key in the selected editor mode.
KEYMAP detect
Displays the JLine key representation of a key sequence and shows the current binding for that sequence by mode. If no key is supplied, SQLcl prompts:
```
Press key sequence to detect
```
Examples
```
keymap detect 
keymap detect ^r
```
KEYMAP reset

Restores one editor mode or all editor modes to the default key bindings established when SQLcl initialized.

Examples
```
keymap reset viins 
keymap reset all
```
KEYMAP keys

Displays the key or keys currently bound to an editor action.

Optionally, you can limit the search to a single editor mode.
KEYMAP export

Exports key bindings to a JSON file.

If no file is specified, SQLcl writes the export to:
```
~/.dbtools/sqlcl/keymap.json
```
The exported file stores raw JLine key sequences rather than the display format shown by keymap list.

For example:
- Command output may display a key as ^[[A
- The exported JSON stores the same key as \u001B[A
Using raw JLine sequences ensures that exported keymaps can be imported without losing terminal-specific key information.

Examples
```
keymap export 
keymap export ~/team-keymap.json 
keymap import ~/team-keymap.json
```
KEYMAP import

Imports key bindings from a JSON file and applies them to the current SQLcl session.

Loading Keymap Configuration

The default export file is also the default keymap configuration file loaded during SQLcl startup.

~/.dbtools/sqlcl/keymap.json

During startup, SQLcl:

Initializes built-in default keymaps.
Captures the baseline used by keymap reset.
Loads ~/.dbtools/sqlcl/keymap.json if present.
Applies the imported bindings on top of defaults.

As a result, exporting key bindings to the default location automatically makes them available in future SQLcl sessions.

12.14 KEYMAP