NAME

       commands - a

PRIMITIVES

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

       cd [<directory>]
           change the current directory to directory, or the home directory if unspecified

       doc <topic>
           display documentation about a topic. The completion list displays the available topics

       e[dit][!] <filename> [<line> [<column>]]
           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

       w[rite] [<filename>]
           write buffer to <filename> or use it’s name if filename is not given

       w[rite]a[ll]
           write all buffers that are associated to a file

       q[uit][!]
           exit Kakoune, use quit! to force quitting even if there is some unsaved buffers
           remaining

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

       w[a]q[!]
           write the current buffer (or all buffers when waq is used) and quit

       b[uffer] <name>
           switch to buffer <name>

       b[uffer]n[ext]
           switch to the next buffer

       b[uffer]p[rev]
           switch to the previous buffer

       d[el]b[uf][!] [<name>]
           delete the buffer <name>

       source <filename>
           execute commands in <filename>

       runtime <filename>
           execute commands in <filename>, <filename> is relative to kak executable path

       colorscheme <name>
           load named colorscheme

       rename-client <name>
           set current client name

       rename-buffer <name>
           set current buffer name

       rename-session <name>
           set current session name

       echo [options] <text>
           show text in status line, with the following options:

           -color <face>
               print the given text with face, most commonly Error or Information

           -markup
               expand the markup strings in text (c.f. the expansions documentation page)

           -debug
               print the given text to the \*debug* buffer

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

       set <scope> <name> <value>
           change the value of an option (c.f. the options documentation page), 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

       unset <scope> <name>
           unset the value of an option (c.f. the options documentation page)

       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

       declare-option [-hidden] <type> <name> [<value>]
           declare a new option, the -hidden hides the option in completion suggestions (c.f. the
           options documentation page)

       face <name> <facespec>
           define a face (c.f. the faces documentation page)

       exec [<flags>] <key> ...
           execute a series of keys, as if they were hit (c.f. the execeval documentation page)

       eval [<flags>] <command> ...
           execute commands, as if they were entered in the command prompt (c.f. the execeval
           documentation page)

       define-command [<flags>] <name> <command>
           define a new command (c.f. the Declaring new commands section below)

       map <scope> <mode> <key> <keys>
           make key behave as if keys were typed. with scope being one of global, buffer or
           window, mode being insert, normal, prompt, menu or user.

               *user* mode allows for user mapping behind the *,* key. Keys
               will be executed in normal mode.

       unmap <scope> <mode> <key> [<expected>]
           remove the mapping of key in given scope and mode, if expected is specified, only
           remove the mapping it if matches the expected keys.

       hook [-group <group>] <scope> <hook_name> <filtering_regex> <command>
           execute a command whenever an event is triggered (c.f. the hooks documentation page)

       remove-hooks <scope> <group>
           remove every hooks in scope that are part of the given group (c.f. the hooks
           documentation page)

       add-highlighter [<flags>] <highlighter_name> <highlighter_parameters> ...
           add a highlighter to the current window (c.f. the highlighters documentation page)

       remove-highlighter <highlighter_id>
           remove the highlighter whose id is highlighter_id (c.f. the highlighters documentation
           page)

HELPERS

       Kakoune provides some helper commands that can be used to define composite commands:

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

       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 <label1> <commands1> <label2> <commands2> ...
           display a menu using labels, the selected label’s commands are executed. menu 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 [options] <text>
           display text in an information box with the following options:

           -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 commands execution, execute
           on_error_commands instead. If nothing is to be done on error, the catch part can be
           omitted

       reg <name> <content>
           set register name to content

       select <anchor_line>.<anchor_column>,<cursor_line>.<cursor_column>:...
           replace the current selections with the one described in the argument

       debug {info,buffers,options,memory,shared-strings}
           print some debug information in the \*debug* buffer

       Note that those commands are also available in the interactive mode, but are not really
       useful in that context.

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 [flags] <command_name> <commands>
           commands is a string containing the commands to execute, and flags 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

           -shell-completion
               following string is a shell command which takes parameters as positional params
               and output one completion candidate per line

           -allow-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 one to define complex commands or to access Kakoune state:

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

                                                                                  KAK_COMMANDS(1)