commands.asciidoc

Commands

Some commands take an exclamation mark (!), which can be used to force the execution of the command (i.e. to quit a modified buffer, the command q! has to be used). Aliases are mentionned below each commands.

doc <topic>

alias help
display documentation about a topic. The completion list displays the available topics

Files and Buffers

change-directory [<directory>]

alias cd
change the current directory to directory, or the home directory if unspecified

edit[!] <filename> [<line> [<column>]]

alias e
open buffer on file, go to given line and column. If file is already opened, just switch to this file. Use edit! to force reloading

write[!] [<filename>]

alias w
write buffer to <filename> or use its name if filename is not given. If the file is write-protected, its permissions are temporarily changed to allow saving the buffer and restored afterwards when the write! command is used.

write-all

alias wa
write all buffers that are associated to a file

quit! [<exit status>]

alias q
exit Kakoune, use quit! to force quitting even if there is some unsaved buffers remaining. If specified, the client exit status will be set to <exit status>

write-all-quit [<exit status>]

alias waq
write all buffers and quit. If specified, the client exit status will be set to <exit status>

buffer <name>

alias b
switch to buffer <name>

buffer-next

alias bn
switch to the next buffer

buffer-prev

alias bp
switch to the previous buffer

delete-buffer[!] [<name>]

alias db
delete the buffer <name>

rename-buffer <name>

set current buffer name

source <filename>

execute commands in <filename>

Clients and Sessions

rename-client <name>

alias nc
set current client name

rename-session <name>

set current session name

kill[!]

terminate the current session, all the clients as well as the server

Options

declare-option [<switches>] <type> <name> [<value>]

alias decl
declare a new option, the -hidden switch hides the option in completion suggestions (See :doc options declare-option)

set-option [<switches>] <scope> <name> <value>

alias set
change the value of an option note that the name of a particular buffer can be specified when the target scope is 'buffer', e.g. set buffer=/path/to/buffer foo "bar"; the scope can also take the current special value, which will automatically point to the narrowest scope available in the current context (See :doc options set-option)

unset-option <scope> <name>

alias unset
unset the value of an option (See :doc options unset-option)

update-option <scope> <name>

update the value of an option if its type supports that operation (See :doc options update-option)

Commands and Keys

define-command [<switches>] <name> <command>

alias def
define a new command (See Declaring new commands)

alias <scope> <name> <command>

define a new alias, within the context of a scope

unalias <scope> <name> [<command>]

remove an alias if its current value is the same as the one passed as an optional parameter, remove it unconditionally otherwise

evaluate-commands [<switches>] <command> …​

alias eval
evaluate commands, as if they were entered in the command prompt (See :doc execeval)

execute-keys [<switches>] <key> …​

alias exec
execute a series of keys, as if they were hit (See :doc execeval)

map [<switches>] <scope> <mode> <key> <keys>

bind a list of keys to a combination (See :doc mapping)

unmap <scope> <mode> <key> [<expected>]

unbind a key combination (See :doc mapping)

declare-user-mode <name>

declare a new user keymap mode

enter-user-mode [<switches>] <name>

enable <name> keymap mode for next key

-lock

stay in mode until <esc> is pressed

Hooks

hook [-group <group>] <scope> <hook_name> <filtering_regex> <command>

execute a command whenever an event is triggered (See :doc hooks)

remove-hooks <scope> <group>

alias rmhooks
remove every hooks in scope that are part of the given group (See :doc hooks)

Display

echo [<switches>] <text>

show text in status line, with the following switches:

-markup

expand the markup strings in text (See :doc expansions markup-strings)

-debug

print the given text to the \*debug* buffer

set-face <scope> <name> <facespec>

alias face
define a face in scope (See :doc faces)

unset-face <scope> <name>

Remove a face definition from scope (See :doc faces)

colorscheme <name>

load named colorscheme

add-highlighter <highlighter_name> <highlighter_parameters> …​

alias addhl
add a highlighter to the current window (See :doc highlighters)

remove-highlighter <highlighter_id>

alias rmhl
remove the highlighter whose id is highlighter_id (See :doc highlighters)

Helpers

Kakoune provides some helper commands that can be used to define composite commands in scripts. They are also available in the interactive mode, but not really useful in that context.

prompt [<switches>] <prompt> <command>

prompt the user for a string, when the user validates, executes the command. The entered text is available in the text value accessible through $kak_text in shells or %val{text} in commands.

The *-init <str>* switch allows setting initial content, the
*-password* switch hides the entered text and clears the register
after command execution.

The *-on-change* and *-on-abort* switches, followed by a command
will have this command executed whenever the prompt content changes
or the prompt is aborted, respectively.

on-key <command>

wait for next key from user, then execute <command>, the key is available through the key value, accessible through $kak_key in shells, or %val{key} in commands.

menu [<switches>] <label1> <commands1> <label2> <commands2> …​

display a menu using labels, the selected label’s commands are executed. The menu command can take an -auto-single argument, to automatically run commands when only one choice is provided, and a -select-cmds argument, in which case menu takes three argument per item, the last one being a command to execute when the item is selected (but not validated)

info [<switches>] <text>

display text in an information box with the following switches:

-anchor <line>.<column>

print the text at the given coordinates

-placement {above,below}

set the placement relative to the anchor

-title <text>

set the title of the message box

try <commands> [catch <on_error_commands>]…​

prevent an error in commands from aborting the whole command execution, execute on_error_commands instead. If nothing is to be done on error, the catch part can be omitted. If an error is raised in the on_error_commands, that error is propagated, except if another catch and on_error_commands parameter follows, in which case those commands get executed, and so-on.

nop

does nothing, but arguments will be evaluated (e.g. shell expansion)

fail <text>

raise an error, uses <text> as its description

set-register <name> <contents>…​

alias reg
set register name to content, each content parameter is assigned to a different string in the register. (See :doc registers)

select <anchor_line>.<anchor_column>,<cursor_line>.<cursor_column>…​

replace the current selections with the ones described in the arguments

debug {info,buffers,options,memory,shared-strings,profile-hash-maps,faces,mappings}

print some debug information in the \*debug* buffer

Multiple commands

Commands (c.f. previous sections) can be chained, by being separated either by new lines or by semicolons, as such a semicolon must be escaped with a backslash (\;) to be considered as a literal semicolon argument

Declaring new commands

New commands can be defined using the define-command command:

define-command [<switches>] <command_name> <commands>

commands is a string containing the commands to execute, and switches can be any combination of the following parameters:

-params <num>

the command accepts a num parameter, which can be either a number, or of the form <min>..<max>, with both <min> and <max> omittable

-file-completion

try file completion on any parameter passed to this command

-client-completion

try client name completion on any parameter passed to this command

-buffer-completion

try buffer name completion on any parameter passed to this command

-command-completion

try command completion on any parameter passed to this command

-shell-completion

following string is a shell command which takes parameters as positional params and output one completion candidate per line. The provided shell command will run after each keypress

during the executing of the shell command, the following env vars are
available:

• kak_token_to_complete:::: Index of the token being completed in the command line.

• kak_pos_in_token:::: Position of the cursor inside the token being completed, in bytes from token start.

-shell-candidates

following string is a shell command which takes parameters as positional params and output one completion candidate per line. The provided shell command will run once at the beginning of each completion session, candidates are cached and then used by kakoune internal fuzzy engine

during the executing of the shell command, the following env vars are
available:

• kak_token_to_complete:::: Index of the token being completed in the command line.

-override

allow the new command to replace an existing one with the same name

-hidden

do not show the command in command name completions

-docstring

define the documentation string for the command

Using shell expansion allows defining complex commands or accessing Kakoune’s state:

def " print_selection %{ echo %sh{ ${kak_selection} } }"