remote.txt (13527B)
1 *remote.txt* For Vim version 9.2. Last change: 2026 Jun 05 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7 Vim client-server communication *client-server* 8 9 1. Common functionality |clientserver| 10 2. X11 specific items |x11-clientserver| 11 3. MS-Windows specific items |w32-clientserver| 12 4. Socket server specific items |socketserver-clientserver| 13 14 ============================================================================== 15 1. Common functionality *clientserver* 16 17 When compiled with the |+clientserver| option, Vim can act as a command 18 server. It accepts messages from a client and executes them. At the same 19 time, Vim can function as a client and send commands to a Vim server. 20 21 The following command line arguments are available: 22 23 argument meaning ~ 24 25 --remote [+{cmd}] {file} ... *--remote* 26 Open the file list in a remote Vim. When 27 there is no Vim server, execute locally. 28 There is one optional init command: +{cmd}. 29 This must be an Ex command that can be 30 followed by "|". 31 The rest of the command line is taken as the 32 file list. Thus any non-file arguments must 33 come before this. 34 You cannot edit stdin this way |--|. 35 The remote Vim is raised. If you don't want 36 this use > 37 vim --remote-send "<C-\><C-N>:n filename<CR>" 38 < 39 --remote-silent [+{cmd}] {file} ... *--remote-silent* 40 As above, but don't complain if there is no 41 server and the file is edited locally. 42 --remote-wait [+{cmd}] {file} ... *--remote-wait* 43 As --remote, but wait for files to complete 44 (unload) in remote Vim. 45 --remote-wait-silent [+{cmd}] {file} ... *--remote-wait-silent* 46 As --remote-wait, but don't complain if there 47 is no server. 48 *--remote-tab* 49 --remote-tab Like --remote but open each file in a new 50 tabpage. 51 *--remote-tab-silent* 52 --remote-tab-silent Like --remote-silent but open each file in a 53 new tabpage. 54 *--remote-tab-wait* 55 --remote-tab-wait Like --remote-wait but open each file in a new 56 tabpage. 57 58 *--remote-tab-wait-silent* 59 --remote-tab-wait-silent Like --remote-wait-silent but open each file 60 in a new tabpage. 61 *--servername* 62 --servername {name} Become the server {name}. When used together 63 with one of the --remote commands: connect to 64 server {name} instead of the default (see 65 below). The name used will be uppercase. If 66 using the socketserver, you can specify a 67 path, see |socketserver-name| for more 68 details. 69 *--remote-send* 70 --remote-send {keys} Send {keys} to server and exit. The {keys} 71 are not mapped. Special key names are 72 recognized, e.g., "<CR>" results in a CR 73 character. 74 *--remote-expr* 75 --remote-expr {expr} Evaluate {expr} in server and print the result 76 on stdout. 77 *--serverlist* 78 --serverlist Output a list of server names. 79 *--clientserver* 80 --clientserver {method} Use the specified method {method} as the 81 backend for clientserver functionality. Can 82 either be "socket", "x11", or "mswin". 83 *$VIM_CLIENTSERVER* 84 If the "$VIM_CLIENTSERVER" environment 85 variable is set, then Vim will interpret the 86 value just like the --clientserver argument. 87 If it is set and --clientserver is provided in 88 the command line, then --clientserver takes 89 priority. 90 {only available when compiled with both |+X11| 91 and |+socketserver| features, or 92 |+socketserver| on MS-Windows} 93 94 Examples ~ 95 96 Edit "file.txt" in an already running GVIM server: > 97 gvim --remote file.txt 98 99 Edit "file.txt" in an already running server called FOOBAR: > 100 gvim --servername FOOBAR --remote file.txt 101 102 Edit "file.txt" in server "FILES" if it exists, become server "FILES" 103 otherwise: > 104 gvim --servername FILES --remote-silent file.txt 105 106 This doesn't work, all arguments after --remote will be used as file names: > 107 gvim --remote --servername FOOBAR file.txt 108 109 Edit file "+foo" in a remote server (note the use of "./" to avoid the special 110 meaning of the leading plus): > 111 vim --remote ./+foo 112 113 Tell the remote server "BLA" to write all files and exit: > 114 vim --servername BLA --remote-send '<C-\><C-N>:wqa<CR>' 115 116 117 SERVER NAME *client-server-name* 118 119 By default Vim will try to register the name under which it was invoked (gvim, 120 egvim ...). This can be overridden with the --servername argument. If the 121 specified name is not available, a postfix is applied until a free name is 122 encountered, i.e. "gvim1" for the second invocation of gvim on a particular 123 X-server. The resulting name is available in the servername builtin variable 124 |v:servername|. The case of the server name is ignored, thus "gvim" and 125 "GVIM" are considered equal. Note if a socket server is being used, there are 126 some differences, see |socketserver-differences|. 127 128 When Vim is invoked with --remote, --remote-wait or --remote-send it will try 129 to locate the server name determined by the invocation name and --servername 130 argument as described above. If an exact match is not available, the first 131 server with the number postfix will be used. If a name with the number 132 postfix is specified with the --servername argument, it must match exactly. 133 134 If no server can be located and --remote or --remote-wait was used, Vim will 135 start up according to the rest of the command line and do the editing by 136 itself. This way it is not necessary to know whether gvim is already started 137 when sending command to it. 138 139 The --serverlist argument will cause Vim to print a list of registered command 140 servers on the standard output (stdout) and exit. If a socket server is being 141 used, there are caveats, see |socketserver-differences|. 142 *{server}* 143 The {server} argument is used by several functions. When this is an empty 144 string then on Unix the default server name is used, which is "GVIM". On 145 MS-Windows an empty string does not work. 146 147 Win32 Note: Making the Vim server go to the foreground doesn't always work, 148 because MS-Windows doesn't allow it. The client will move the server to the 149 foreground when using the --remote or --remote-wait argument and the server 150 name starts with "g". 151 152 153 REMOTE EDITING 154 155 The --remote argument will cause a |:drop| command to be constructed from the 156 rest of the command line and sent as described above. 157 The --remote-wait argument does the same thing and additionally sets up to 158 wait for each of the files to have been edited. This uses the BufUnload 159 event, thus as soon as a file has been unloaded, Vim assumes you are done 160 editing it. 161 Note that the --remote and --remote-wait arguments will consume the rest of 162 the command line. I.e. all remaining arguments will be regarded as filenames. 163 You can not put options there! 164 165 166 FUNCTIONS 167 *E240* *E573* 168 There are a number of Vim functions for scripting the command server. See 169 the description in |builtin.txt| or use CTRL-] on the function name to jump to 170 the full explanation. 171 172 synopsis explanation ~ 173 remote_startserver( name) run a server 174 remote_expr( server, string, idvar) send expression 175 remote_send( server, string, idvar) send key sequence 176 serverlist() get a list of available servers 177 remote_peek( serverid, retvar) check for reply string 178 remote_read( serverid) read reply string 179 server2client( serverid, string) send reply string 180 remote_foreground( server) bring server to the front 181 182 See also the explanation of |CTRL-\_CTRL-N|. Very useful as a leading key 183 sequence. 184 The {serverid} for server2client() can be obtained with expand("<client>") 185 186 ============================================================================== 187 2. X11 specific items *x11-clientserver* 188 *E247* *E248* *E251* *E258* *E277* 189 190 The communication between client and server goes through the X server. The 191 display of the Vim server must be specified. The usual protection of the X 192 server is used, you must be able to open a window on the X server for the 193 communication to work. It is possible to communicate between different 194 systems. 195 196 By default, a GUI Vim will register a name on the X-server by which it can be 197 addressed for subsequent execution of injected strings. Vim can also act as 198 a client and send strings to other instances of Vim on the same X11 display. 199 200 When an X11 GUI Vim (gvim) is started, it will try to register a send-server 201 name on the 'VimRegistry' property on the root window. 202 203 A non GUI Vim with access to the X11 display (|xterm-clipboard| enabled), can 204 also act as a command server if a server name is explicitly given with the 205 --servername argument, or when Vim was built with the |+autoservername| 206 feature. 207 208 An empty --servername argument will cause the command server to be disabled. 209 210 To send commands to a Vim server from another application, read the source 211 file src/if_xcmdsrv.c, it contains some hints about the protocol used. 212 213 ============================================================================== 214 3. Win32 specific items *w32-clientserver* 215 216 Every Win32 Vim can work as a server, also in the console. You do not need a 217 version compiled with OLE. Windows messages are used, this works on any 218 version of MS-Windows. But only communication within one system is possible. 219 220 Since MS-Windows messages are used, any other application should be able to 221 communicate with a Vim server. An alternative is using the OLE functionality 222 |ole-interface|. 223 224 When using gvim, the --remote-wait only works properly this way: > 225 226 start /w gvim --remote-wait file.txt 227 < 228 ============================================================================== 229 4. Socket server specific items *socketserver-clientserver* 230 *E1564* *E1565* *E1566* 231 232 NOTE: Vim version before patch 9.2.511 use a different socketserver backend 233 which is incompatible with the new one, which is based on channels and JSON. 234 235 The communication between client and server is done using channels internally. 236 When using the traditional/generic clientserver naming (only available on 237 Unix), sockets are placed in these directories in the following order of 238 availability: 239 1. "$XDG_RUNTIME_DIR/vim" if $XDG_RUNTIME_DIR is set in the environment. 240 2. "$TMPDIR/vim-[uid]", where "[uid]" is the uid of the user. This 241 directory will have the access permissions set to 700 so only the user 242 can read or write from/to it. If $TMPDIR is not set, "/tmp" is used. 243 244 *socketserver-name* 245 When specifying the server id/name, it can be taken as a generic name or an 246 absolute or relative path. If the server id starts with either a "/" 247 (absolute) or "./" | "../" (relative), then it is taken as path to the socket. 248 Otherwise the server id will be the filename of the socket which will be 249 placed in the above common directories. Note that a server id/name can only 250 contain slashes "/" if it is taken as a path, so names such as "abc/dir" will 251 be invalid. This feature is only available on Unix. 252 253 *socketserver-address* 254 In addition, the socketserver can also be created as a |channel-address|. To 255 do this, prefix the address with "channel:" (which will be ignored). This is 256 available on both Unix and MS-Windows, and is the only available naming for the 257 socketserver backend on Windows. However, note that |ch_listen()| 258 restrictions apply, meaning only port numbers can be used for TCP sockets. 259 260 If the name is prefixed with "name:", then the legacy servername behaviour is 261 used, so "name:VIM" is the same as "VIM". 262 263 Unless Vim is compiled with |+autoservername| feature, the socket server will 264 have to started explicitly, similar to X11. This is unless a X11 GUI Vim is 265 being used. 266 267 If Vim crashes or does not exit cleanly, the socket server will not remove the 268 socket file and it will be left around. This is generally not a problem, 269 because if a socket name is taken, Vim checks if the socket in its place is 270 dead (not attached to any process), and can replace it instead of finding a 271 new name. This is only relevant for Unix. 272 273 *socketserver-differences* 274 Most of the functionality is the same as the other clientserver backends. 275 276 However, the server id or client id will not be a number like X11 or 277 MS-Windows (shown in hex representation), instead it is the absolute path to 278 the socket. This can be seen via the |v:servername| variable. If the name is 279 a channel address, then it will be the address with the "a/" prefix as well. 280 281 Note when using |--remote-wait|, the client id will look like "t/<some 282 number>". This naming is specifically for this command, and attempting to use 283 it as an address will fail. 284 285 If on Unix, the |--serverlist| argument will act just like X11, however it 286 only checks the given common directories above. If a custom path is used for 287 a socket, it will not be detected, such as a path either not in 288 $XDG_RUNTIME_DIR or <$TMPDIR or /tmp>/vim of the |--serverlist| Vim process. 289 If on MS-Windows, then the |--serverlist| argument will output nothing. 290 291 The |+socketserver| feature is automatically enabled when on Unix or 292 MS-Windows, and the |+channel| feature is enabled 293 294 *socketserver-x11* 295 If Vim is compiled with |+socketserver| and another clientserver backend, then 296 deciding which backend to use is done at startup time, via the 297 |--clientserver| argument. By default if it is not specified, then the native 298 backend (X11 or MS-Window messages) will be used, if available. A Vim 299 instance using a socket server cannot communicate with one using another 300 clientserver backend. 301 302 vim:tw=78:sw=4:ts=8:noet:ft=help:norl: