Keybindings

Keybindings

<leader> is Space by default, and configurable through [keymaps] leader in config.toml. Press ? inside ctrlvim for the full, current list at any time. That help screen is generated from the live mapping table, so it always matches what the keys actually do, including any mappings you added yourself and any built ins you removed.

Modal editing

Normal, Insert, Visual, and Command line modes work the way Vim's do. Motions (w, b, e, <A-[>, <A-]>), operators (d, y, c), and text objects (iw, a", i() compose the way Vim's do, so 2d3w deletes six words.

Default leader bindings

Key	Does
<leader>e	fuzzy file browser
<leader>w / <leader>q / <leader>qq	write / write and quit / quit without saving
<leader>S	find and replace across the project
<leader>d / <leader>p	dashboard / command palette
<leader>1 through <leader>9	go to tab number
<leader><Tab>	go to the next file
<leader>a / <leader>ar / <leader>ac	pin this file / unpin it / unpin all
<leader>h	list pinned files

Other defaults

Key	Does
<A-1> through <A-5>, <A-n> / <A-p>	go to pinned file N / next / previous
<A-j> / <A-k>	move the line, or selection, down / up
<A-[> / <A-]>	previous / next paragraph, in place of Vim's { / }
<C-S-j> / <C-S-k>	duplicate the line, or selection, below / above
<C-b> / <C-g>	file drawer / markdown live rendering
Ctrl-] / Ctrl-T	jump to tag / jump back, over a ctags -R . table
zf / za / zR / zM	create fold / toggle fold / open all / close all

Surround

Select text and press ", ', a backtick, (, [, or { to wrap the selection rather than replace it, so apple becomes "apple". S{delim} does the same and also reaches < and >. This is why the paragraph motion lives on <A-[> / <A-]> rather than on Vim's { and }, those keys were freed up for surround.

Macros

q{register} records a macro, @{register} replays it, and @@ repeats the last one played.

The mapping layer

<C-x>, <A-x> (or <M-x>), <C-S-x>, arrow keys, F-keys, and <S-Tab> are all bindable, in Normal, Insert, and Visual mode. Overlapping chords resolve on the timeoutlen option the way Vim's do, so <leader>q and <leader>qq can coexist without one shadowing the other.

Every mapping carries a desc, set from config, from :nnoremap <desc=...>, or from a plugin's vim.keymap.set(..., { desc = ... }) call. Holding a chord opens a which key popup listing what can follow it, and ? shows the whole table. Both read the live mapping table, so a mapping added anywhere shows up with no code change, and there is no such thing as a stale row.

Any default in the tables above can be replaced with [[keymap]], removed with [[unmap]], or the whole table can start empty with [keymaps] defaults = false. See Configuration for the syntax.

Insert mode is left with <Esc>. There is no built in jk escape, because an insert mode mapping that starts with an ordinary letter delays that letter, the key has to be held back until the rest of the sequence either arrives or times out. Add it yourself if you want it:

[[keymap]]
mode = "i"
lhs = "jk"
rhs = "<Esc>"

<A-[> and <A-]> are the one exception to "everything is a mapping." They are built in motions rather than mappings, specifically so that they can take a count, 3<A-]> for example, since mappings are skipped while a count is pending. They will not appear in :map, and [keymaps] defaults = false will not remove them, but a [[keymap]] bound to the same keys still takes precedence over them.

Two things worth knowing

<C-S-j> is only distinguishable from <C-j> in a terminal that supports the kitty keyboard protocol: kitty, WezTerm, foot, Ghostty, and recent Alacritty. In any other terminal those two bindings simply never fire separately.

Bindings that would shadow a standard Vim motion, H, L, [[, ]], and ;, are deliberately not defaults. They ship commented out in the starter config.toml if you want to turn them on.

The shell keymap

Outside a file buffer, on the dashboard, the plugin manager, or an overlay, a separate keymap applies:

: opens the command palette, Ctrl+B opens the explorer, Tab / Shift+Tab cycle buffers, [ / ] cycle the dashboard section, w / s / a jump to a section directly, p opens the plugin manager, 2 / 3 switch layout, r / g / b expand panels, j / k move the current selection, Enter opens or toggles it, ? opens help, and Esc closes whatever overlay is open. Every list row, tab, pill, and toggle is also clickable, and the mouse wheel scrolls the editor view; setting mouse = false in [ui] gives wheel scrolling back to the terminal.

Inside a file buffer, keys go straight to the editing engine, Vim motions, operators, and Insert mode all work as described above. A handful of chords escape back to the shell from there: Ctrl+Left / Ctrl+Right cycle buffers, Ctrl+B opens the explorer, Ctrl+P or : opens the palette, and ? opens help, all from Normal mode. Esc returns to Normal mode, and Ctrl+C quits from anywhere.