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 mentioned below each command.

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

arrange-buffers <buffer>…​

Reorder the buffers in the buffers list. The named buffers will be moved to the front of the buffer list, in the order given. Buffers that do not appear in the parameters will remain at the end of the list, keeping their current order.

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. If no filename is given, the buffer name will be generated based on format *scratch-$ID\*, where $ID is an integer automatically incremented for new buffers. (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[!] [-force] [-sync] [-method <writemethod>] [<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.

-force

Equivalent to !, allow overwiting existing files if <filename> is given and set permissions temporarily if necessary.

-sync

Synchronise the filesystem after the write

-method <writemethod>

Enforce write method instead of relying on the writemethod option

replace

Write to a temporary file then rename to the target file so that the modification appears atomically.

overwrite

Open the existing file and overwrite its content with the new content.

(See <<options#builtin-options,`:doc options builtin-options`>>)

write-all [-sync] [-method <writemethod>]

alias wa
write all changed buffers that are associated with a file

quit[!] [<exit status>]

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

write-quit[!] [-sync] [-method <writemethod>] [<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] [-method <writemethod>] [<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-previous

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 [-file|-scratch] <name>

set current buffer name, if -scratch or -file is given, ensure the buffer is set to the corresponding type.

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>

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)

complete-command [<switches>] <name> <type> [<param>]

alias compl
configure how a command completion works (See Configuring command completion)

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 [<switches>] <scope> <hook_name> <filtering_regex> <command>

execute command whenever a hook_name is triggered in scope (See :doc hooks and :doc scopes)

-group <groupname>

Add this hook to the groupname group, so it can be removed by the remove-hooks command (below) or disabled with the disabled_hooks option (see :doc options builtin-options).

-once

This hook will be automatically removed after it has been executed.

-always

This hook will run even while hooks are disabled. See :doc hooks disabling-hooks.

remove-hooks <scope> <group>

alias rmhooks
remove every hook in scope whose group matches the regex group (See :doc hooks and :doc scopes)

trigger-user-hook <param>

trigger the User hook with the given param as filter string in the current context. (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 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.

-to-shell-script <script>

execute the given shell script with the given text written to its standard input

-quoting <quoting>

define how arguments are quoted in echo output:

• raw (default):::: just join each argument with a space

• kakoune:::: also wrap each argument in single quotes, doubling-up embedded quotes.

• shell:::: also wrap each arguments in single quotes and escape embedded quotes in a shell compatible way.

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 [<switches>] <highlighter_path> <highlighter_parameters> …​

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

remove-highlighter <highlighter_path>

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-completion* 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.

NOTE: The prompt is displayed in and receives input from the
current client context, so inside a draft context like
`evaluate-commands -draft`, it is invisible and only responds to
an `execute-keys` command in the same context.

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.

NOTE: The key press must come from the current client context,
so inside a draft context like `evaluate-commands -draft`, it only
responds to an `execute-keys` command in the same context.

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)

NOTE: The menu is displayed in and receives input from the
current client context, so inside a draft context like
`evaluate-commands -draft`, it is invisible and only responds to
an `execute-keys` command in the same context.

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

-markup

parse markup in both title (if provided) and text. (See :doc faces markup-strings)

NOTE: The info box is displayed in the current client context,
so inside a draft context like `eval -draft`, it is invisible.

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 [<switches>] <anchor_line>.<anchor_column>,<cursor_line>.<cursor_column>…​

replace the current selections with the ones described in the arguments

-timestamp <timestamp>

specify which buffer timestamp those coordinates apply to. Uses current buffer timestamp if not specified.

-codepoint

provided columns are to be interpreted as codepoint counts, not byte counts.

-display-column

provided columns are to be interpreted as display column counts, not byte counts.

both *-codepoint* and *-display-column* are only valid if *-timestamp*
matches the current buffer timestamp (or is not specified).

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

print some debug information in the \*debug* buffer

Module commands

In Kakoune, modules are a grouping of stored commands to be executed the first time they are needed. This allows complex configurations to be evaluated lazily, and allows plugins to ensure their dependencies have been loaded before they execute. The builtin filetype handling for Kakoune is implemented via modules.

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.

To avoid trouble while writing map or execute-keys commands in scripts, the alternative key namings <semicolon> and <a-semicolon> can be used.

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

-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

-menu

-file-completion

-client-completion

-buffer-completion

-command-completion

-shell-completion

-shell-script-completion

-shell-script-candidates

old-style command completion specification, function as-if the switch and its eventual parameter was passed to the complete-command command (See Configuring command completion)

The use of those switches is discouraged in favor of the
*complete-command* command.

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

# create a directory for current buffer if it does not exist
define-command mkdir %{ nop %sh{ mkdir -p $(dirname $kak_buffile) } }

Configuring command completion

Command completion can be configured with the complete-command command:

complete-command [<switches>] <command_name> <completion_type> [<parameter>]

switches can be:

-menu

the suggestions generated by the completion options are the only permitted parameters. Kakoune will autoselect the best completion candidate on command validation.

*completion_type* can be:

file

try file completion on any parameter passed to the command

client

try client name completion on any parameter passed to the command

buffer

try buffer name completion on any parameter passed to the command

command

try command completion on any parameter passed to the command

shell

try shell command completion on any parameter passed to the command

shell-script

following string is a shell command which takes parameters as positional params and outputs one completion candidate per line. The provided shell command will run after each keypress. During the execution of the shell command, the following env vars are available:

$kak_token_to_complete

Index of the token being completed in the command line. Note that unlike the Unix argv tradition, 0 is the first argument, not the command name itself.

$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 script which takes parameters as positional params and outputs one completion candidate per line. The provided shell script will run once at the beginning of each completion session, candidates are cached and then used by kakoune internal fuzzy engine.

During the execution of the shell script, the following env vars are
available:

$kak_token_to_complete

Index of the token being completed in the command line. Note that unlike the Unix argv tradition, 0 is the first argument, not the command name itself.

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>.