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
For the following write commands, the -sync switch forces the
synchronization of the file onto the filesystem
change-directory [<directory>]
alias cd
change the current directory to directory, or the home directory if
unspecified
edit[!] [<switches>] <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
-debug
The new buffer (if any) will be created as a debug buffer. (See
:doc buffers debug-buffers)
-existing
If the named file does not exist, fail instead of creating a new buffer.
-readonly
The new buffer (if any) will be set read-only.
-fifo <fifoname>
Creates a new scratch buffer named <filename>, and continually
appends data from the fifo (named pipe) <fifoname> as it arrives.
(See :doc buffers fifo-buffers)
-scratch
Creates a new buffer named <filename>, which doesn’t correspond to
any file on disk. (See
:doc buffers scratch-buffers)
-scroll
If used with -fifo, when new data arrives Kakoune will scroll the
buffer down to make the new data visible. Otherwise, does nothing.
write[!] [-sync] [<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 [-sync]
alias wa
write all changed 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-quit[!] [-sync] [<exit status>]
alias wq
write current buffer and quit current client. If specified, the client
exit status will be set to <exit status>
write-all-quit [-sync] [<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. Debug buffers are skipped. (See
:doc buffers debug-buffers)
buffer-prev
alias bp
switch to the previous buffer. Debug buffers are skipped. (See
:doc buffers debug-buffers)
delete-buffer[!] [<name>]
alias db
delete current buffer or the buffer <name> if specified
rename-buffer <name>
set current buffer name
source <filename> <param>…
execute commands in <filename> parameters are available in the
sourced script as %arg{0}, %arg{1}, …
Clients and Sessions
rename-client <name>
alias nc
set current client name
rename-session <name>
set current session name
kill[!] [<exit status>]
terminate the current session, all the clients as well as the server. If
specified, the server and clients exit status will be set to <exit
status>
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 in scope (See
:doc options set-option and
:doc scopes)
unset-option <scope> <name>
alias unset
unset the value of an option in scope, so the value from an outer
scope is used (See :doc options unset-option
and :doc scopes)
update-option <scope> <name>
update the value of an option if its type supports that operation (See
:doc options update-option and
:doc scopes)
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 named name in scope (See Using
aliases and :doc scopes)
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 (See Using
aliases and :doc scopes)
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
and :doc scopes)
unmap <scope> <mode> <key> [<expected>]
unbind a key combination (See :doc mapping and
:doc scopes)
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 command whenever an hook_name is triggered in scope
(See :doc hooks and :doc scopes)
remove-hooks <scope> <group>
alias rmhooks
remove every hooks in scope that are part of the given group
(See :doc hooks and :doc scopes)
Display
echo [<switches>] <text>
show text in status line, with the following switches:
-markup
expand the markup strings in text (See
:doc faces markup-strings)
-debug
print the given text to the \*debug* buffer
-to-file <filename>
write the given text to the given file on the host filesystem.
set-face <scope> <name> <facespec>
alias face
define a face in scope (See :doc faces and
:doc scopes)
unset-face <scope> <name>
Remove a face definition from scope (See :doc faces and
:doc scopes)
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.
Completion support can be controlled with the same switches provided
by the *define-command* command, see
<<declaring-new-commands,Declaring new commands>>.
For *-shell-script-completions* and *-shell-script-candidates*
completions, token_to_complete will always be 1, and the full
prompt content will be passed as a single token. In other words,
word splitting does not take place.
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
-style <style>
set the style and placement of the message box.
menu
display the info next to the displayed menu, as documentation for the
currently selected entry.
above
display the info above the given anchor
below
display the info below the given anchor
modal
display the info modally, and do not auto-close the info or replace it
with non modal info boxes. To hide a modal info box, use
info -style modal with no arguments.
-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. During error commands, the
description of the last raised error is available as $kak_error in the
shell, or %val{error} in commands.
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
Module commands
provide-module [<switches>] <name> <commands>
declares a module name that is defined by commands. commands
will be evaluated as if by source the first time require-module
<name> is run.
-override
allow the module to replace an existing one with the same name. Fails if
the module has already been evaluated.
require-module <name>
guarantees the commands associated with name have been evaluated
before continuing command execution. Fails if name has not been
defined by a provide-module command. Does nothing if the associated
commands have already been evaluated.
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
try shell command completion on any parameter passed to this command
-shell-script-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-script-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} } }"
Aliases
With :alias, commands can be given additional names. As aliases are
intended to be used interactively most of the time, they are often
short. For example :reg is an alias for :set-register.
They are scoped, so that an alias can refer to one command for a buffer,
and to another for another buffer. For instance :next could be an
alias for grep-next-match in a *grep* buffer while pointing to
:make-next-error in a *make* buffer.
The following command defines <alias> as an alias for <command>:
:alias <scope> <alias> <command>
<scope> can be one of global, buffer or window.
:unalias <scope> <alias> [<expected>]
Will remove the given alias in the given scope. If <expected> is
specified the alias will only be removed if its current value is
<expected>.