# Commands

**URL:** <https://discuss.kakoune.com/t/commands/538>\
**Category:** Manual++\
**Created:** [May 8, 2019, 2:14am UTC](https://discuss.kakoune.com/t/commands/538 "2019-05-08T02:14:03Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![robertmeta](https://discuss.kakoune.com/user_avatar/discuss.kakoune.com/robertmeta/32/833_2.png) [@robertmeta](https://discuss.kakoune.com/u/robertmeta)\
**Post date:** [May 8, 2019, 2:14am UTC](https://discuss.kakoune.com/t/commands/538/1 "2019-05-08T02:14:03Z")

</div>

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`](https://discuss.kakoune.com/t/buffers/536/2#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`](#buffers#fifo-buffers))

**-scratch**  
Creates a new buffer named \<filename\>, which doesn’t correspond to  
any file on disk. (See  
[`:doc buffers scratch-buffers`](#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`](https://discuss.kakoune.com/t/buffers/536/2#debug-buffers))

**buffer-prev**  
**alias** bp  
switch to the previous buffer. Debug buffers are skipped. (See  
[`:doc buffers debug-buffers`](https://discuss.kakoune.com/t/buffers/536/2#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`](https://discuss.kakoune.com/t/options/549/2#declare-option))

**set-option** [\<switches\>] \<scope\> \<name\> \<value\>  
**alias** set  
change the value of an option in **scope** (See  
[`:doc options set-option`](#options#set-option) and  
[`:doc scopes`](https://discuss.kakoune.com/t/options/549/2))

**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`](https://discuss.kakoune.com/t/options/549/2#unset-option)  
and [`:doc scopes`](https://discuss.kakoune.com/t/options/549/2))

**update-option** \<scope\> \<name\>  
update the value of an option if its type supports that operation (See  
[`:doc options update-option`](#options#update-option) and  
[`:doc scopes`](https://discuss.kakoune.com/t/execeval-execute-keys-evaluation-commands/539/2))

# Commands and Keys

**define-command** [\<switches\>] \<name\> \<command\>  
**alias** def  
define a new command (See [Declaring new  
commands](#declaring-new-commands))

**alias** \<scope\> \<name\> \<command\>  
define a new alias named **name** in **scope** (See [Using  
aliases](#aliases) and [`:doc scopes`](https://discuss.kakoune.com/t/execeval-execute-keys-evaluation-commands/539/2))

**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](#aliases) and [`:doc scopes`](https://discuss.kakoune.com/t/execeval-execute-keys-evaluation-commands/539/2))

**evaluate-commands** [\<switches\>] \<command\> …  
**alias** eval  
evaluate commands, as if they were entered in the command prompt (See  
[`:doc execeval`](https://discuss.kakoune.com/t/execeval-execute-keys-evaluation-commands/539/2))

**execute-keys** [\<switches\>] \<key\> …  
**alias** exec  
execute a series of keys, as if they were hit (See  
[`:doc execeval`](https://discuss.kakoune.com/t/execeval-execute-keys-evaluation-commands/539/2))

**map** [\<switches\>] \<scope\> \<mode\> \<key\> \<keys\>  
bind a list of keys to a combination (See [`:doc mapping`](#mapping#)  
and [`:doc scopes`](https://discuss.kakoune.com/t/scopes/552/2))

**unmap** \<scope\> \<mode\> \<key\> [\<expected\>]  
unbind a key combination (See [`:doc mapping`](#mapping#) and  
[`:doc scopes`](https://discuss.kakoune.com/t/scopes/552/2))

**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`](https://discuss.kakoune.com/t/hooks/544/2) and [`:doc scopes`](https://discuss.kakoune.com/t/scopes/552/2))

**remove-hooks** \<scope\> \<group\>  
**alias** rmhooks  
remove every hooks in **scope** that are part of the given **group**  
(See [`:doc hooks`](https://discuss.kakoune.com/t/hooks/544/2) and [`:doc scopes`](https://discuss.kakoune.com/t/scopes/552/2))

# 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`](https://discuss.kakoune.com/t/faces/541/2#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`](#faces#) and  
[`:doc scopes`](https://discuss.kakoune.com/t/scopes/552/2))

**unset-face** \<scope\> \<name\>  
Remove a face definition from **scope** (See [`:doc faces`](#faces#) and  
[`:doc scopes`](https://discuss.kakoune.com/t/scopes/552/2))

**colorscheme** \<name\>  
load named colorscheme

**add-highlighter** \<highlighter\_name\> \<highlighter\_parameters\> …  
**alias** addhl  
add a highlighter to the current window (See  
[`:doc highlighters`](https://discuss.kakoune.com/t/highlighters/543/2))

**remove-highlighter** \<highlighter\_id\>  
**alias** rmhl  
remove the highlighter whose id is **highlighter\_id** (See  
[`:doc highlighters`](https://discuss.kakoune.com/t/highlighters/543/2))

# 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`](https://discuss.kakoune.com/t/registers/551/2))

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