remote.txt ForVim version 9.2. Last change: 2026 Feb 14VIM REFERENCE MANUAL by Bram MoolenaarVimclient-server communicationclient-server1. Common functionalityclientserver2.X11 specific itemsx11-clientserver3.MS-Windows specific itemsw32-clientserver4. Socket server specific itemssocketserver-clientserver==============================================================================1. Common functionalityclientserverWhen compiled with the+clientserver option, Vim can actasa commandserver. It acceptsmessages froma client and executes them. At the sametime, Vim can functionasa client and send commands toa Vim server.The following command line arguments are available: argumentmeaning--remote [+{cmd}]{file}...--remoteOpen the filelist ina remote Vim. Whenthereis no Vim server, execute locally.Thereis one optional init command: +{cmd}.Thismust be anEx command that can befollowed by "|".The rest of the command lineis takenas thefile list. Thus any non-file argumentsmustcome before this.You cannot edit stdin this way--.The remote Vimis raised. If you don't wantthis use vim --remote-send "<C-\><C-N>:n filename<CR>"--remote-silent [+{cmd}]{file}...--remote-silentAs above, but don't complain if thereis noserver and the fileis edited locally.--remote-wait [+{cmd}]{file}...--remote-waitAs --remote, but wait for files to complete(unload) in remote Vim.--remote-wait-silent [+{cmd}]{file}...--remote-wait-silentAs --remote-wait, but don't complain if thereis no server.--remote-tab--remote-tabLike--remote but open each file ina newtabpage.--remote-tab-silent--remote-tab-silentLike--remote-silent but open each file inanew tabpage.--remote-tab-wait--remote-tab-waitLike--remote-wait but open each file ina newtabpage.--remote-tab-wait-silent--remote-tab-wait-silentLike--remote-wait-silent but open each fileina new tabpage.--servername--servername{name}Become the server{name}. When used togetherwith one of the--remote commands: connect toserver{name} instead of the default (seebelow). The name used will be uppercase. Ifusing the socketserver, you can specifyapath, seesocketserver-name for moredetails.--remote-send--remote-send{keys}Send{keys} to server and exit. The{keys}are not mapped.Special key names arerecognized, e.g., "<CR>" results ina CRcharacter.--remote-expr--remote-expr{expr}Evaluate{expr} in server and print the resulton stdout.--serverlist--serverlistOutputalist of server names.--clientserver--clientserver{method}Use the specifiedmethod{method}as thebackend forclientserver functionality. Caneither be "socket" or "x11".{only available when compiled with both+X11and+socketserver features}ExamplesEdit "file.txt" in an already running GVIM server: gvim --remote file.txtEdit "file.txt" in an already running server called FOOBAR: gvim --servername FOOBAR --remote file.txtEdit "file.txt" in server "FILES" ifit exists, become server "FILES"otherwise: gvim --servername FILES --remote-silent file.txtThis doesn't work, all arguments after--remote will be usedas file names: gvim --remote --servername FOOBAR file.txtEdit file "+foo" ina remote server (note the use of "./" to avoid the specialmeaning of the leading plus): vim --remote ./+fooTell the remote server "BLA" to write all files and exit: vim --servername BLA --remote-send '<C-\><C-N>:wqa<CR>'SERVER NAMEclient-server-nameBy default Vim will try to register the name under whichit was invoked (gvim,egvim ...). This can be overridden with the--servername argument. If thespecified nameis not available,a postfixis applied untila free nameisencountered, i.e. "gvim1" for the second invocation ofgvim ona particularX-server. The resulting nameis available in the servername builtin variablev:servername. Thecase of the server nameis ignored, thus "gvim" and"GVIM" are considered equal.Note ifa socket serveris being used, there aresome differences, seesocketserver-differences.When Vimis invoked with --remote,--remote-wait or--remote-sendit will tryto locate the server name determined by the invocation name and--servernameargumentas described above. If an exact matchis not available, the firstserver with the number postfix will be used. Ifa name with the numberpostfixis specified with the--servername argument,itmust match exactly.If no server can be located and--remote or--remote-wait was used, Vim willstart up according to the rest of the command line anddo the editing byitself. This wayitis not necessary to know whethergvimis already startedwhen sending command to it.The--serverlist argument will cause Vim to printalist of registered commandservers on the standard output (stdout) and exit. Ifa socket serveris beingused, there are caveats, seesocketserver-differences.{server}The{server} argumentis used by several functions. When thisis an emptystring then onUnix the default server nameis used, whichis "GVIM". OnMS-Windows an emptystring does not work.Win32Note: Making the Vim servergo to the foreground doesn't always work,becauseMS-Windows doesn't allow it. The client will move the server to theforeground when using the--remote or--remote-wait argument and the servername starts with "g".REMOTE EDITINGThe--remote argument will causea:drop command to be constructed from therest of the command line and sentas described above.The--remote-wait argument does the same thing and additionally sets up towait for each of the files to have been edited. This uses theBufUnloadevent, thusas soonasa file has been unloaded, Vim assumes you are doneediting it.Note that the--remote and--remote-wait arguments will consume the rest ofthe command line. I.e. all remaining arguments will be regardedas filenames.You can notputoptions there!FUNCTIONSE240E573There area number of Vimfunctions for scripting the command server. Seethe description inbuiltin.txt or useCTRL-] on the function name to jump tothe full explanation. synopsis explanation remote_startserver( name) runa server remote_expr( server, string, idvar) sendexpression remote_send( server, string, idvar) send key sequenceserverlist() getalist of available servers remote_peek( serverid, retvar) check for replystring remote_read( serverid) read replystring server2client( serverid, string) send replystring remote_foreground( server) bring server to the frontSee also the explanation ofCTRL-\_CTRL-N. Very usefulasa leading keysequence.The{serverid} forserver2client() can be obtained with expand("<client>")==============================================================================2.X11 specific itemsx11-clientserverE247E248E251E258E277The communication between client and server goes through theX server. Thedisplay of the Vim servermust be specified. The usual protection of theXserveris used, youmust be able to openawindow on theX server for thecommunication to work. Itis possible to communicate between differentsystems.By default,aGUI Vim will registera name on the X-server by whichit can beaddressed for subsequent execution of injected strings. Vim can also actasa client and send strings to other instances of Vim on the sameX11 display.When anX11GUI Vim (gvim)is started,it will try to registera send-servername on the 'VimRegistry' property on the root window.A nonGUI Vim with access to theX11 display(xterm-clipboard enabled), canalso actasa command server ifa server nameis explicitly given with the--servername argument, or when Vim was built with the+autoservernamefeature.An empty--servername argument will cause the command server to be disabled.To send commands toa Vim server from another application, read the sourcefile src/if_xcmdsrv.c,it contains some hints about the protocol used.==============================================================================3.Win32 specific itemsw32-clientserverEveryWin32 Vim can workasa server, also in the console. Youdo not needaversion compiled with OLE. Windowsmessages are used, this works on anyversion of MS-Windows. But only communication within one systemis possible.SinceMS-Windowsmessages are used, any other application should be able tocommunicate witha Vim server. An alternativeis using the OLE functionalityole-interface.When using gvim, the--remote-wait only works properly this way:start /w gvim --remote-wait file.txt==============================================================================4. Socket server specific itemssocketserver-clientserverE1563E1564E1565E1566E1567The communication between client and serveris done usingUnix domain sockets.These sockets are either placed in these directories in the following order ofavailability: 1. "$XDG_RUTIME_DIR/vim" if $XDG_RUNTIME_DIRis set in the environment. 2. "$TMPDIR/vim-[uid]", where "[uid]"is the uid of the user. This directory will have the access permissions set to 700 so only the user can read or write from/to it. If $TMPDIRis not set, "/tmp"is used.socketserver-nameWhen specifying the server id/name,it can be takenasa generic name or anabsolute or relative path. If the server id starts with eithera "/"(absolute) or "./" | "../" (relative), thenitis takenas path to the socket.Otherwise the server id will be the filename of the socket which will beplaced in the above common directories.Note thata server id/name can onlycontain slashes "/" ifitis takenasa path, so names suchas "abc/dir" willbe invalid.Socket server functionalityis available in bothGTKGUI andterminal versionsof Vim. Unless Vimis compiled with+autoservername feature, the socketserver will have to started explicitly, just like X11, even in the GUI.If Vim crashes or does not exit cleanly, the socket server will not remove thesocket file andit will be left around. Thisis generally nota problem,because ifa socket nameis taken, Vim checks if the socket in its placeisdead (not attached to any process), and can replaceit instead of findinganew name.To send commands toa Vim socket server from another application, read thesource file src/os_unix.c, thereis detailed description of the protocol used.socketserver-differencesMost of the functionalityis the sameas X11, however unlike X11, where theclient does not need to bea server in order to communicate with anotherserver, the socket server requires the server to be running evenasa client.The exceptionisserverlist() or the--serverlist argument, which does notrequire the server to be running.Additionally, the server id or client id will not bea number likeX11 orMS-Windows (shown in hex representation), insteaditis the absolute path tothe socket. This can be seen via thev:servername variable.The--serverlist argument will act just like X11, howeverit only checks thegiven common directories above. Ifa custom pathis used fora socket,itwill not be detected, suchasa path either not in $XDG_RUNTIME_DIR or<$TMPDIR or /tmp>/vim of the--serverlist Vim process.If you have both+socketserver and+X11 compiled, you will need to add--clientserver set to "socket" in combination with--serverlist tolistthe available servers. You cannotlist both types of backends in one command.socketserver-x11If Vimis compiled with both+X11 and+socketserver, then deciding whichbackend to useis doneatstartup time, via the--clientserver argument. Bydefault ifitis not specified, thenX11 will be used.A Vim instance usingasocket server cannot communicate with one using X11. vim:tw=78:sw=4:ts=8:noet:ft=help:norl: