An Emacs server usually listens to connections on a local Unix domain socket. Some operating systems, such as MS-Windows, do not support local sockets; in that case, the server uses TCP sockets instead. In some cases it is useful to have the server listen on a TCP socket even if local sockets are supported, e.g., if you need to contact the Emacs server from a remote machine. You can set server-use-tcp to non-nil to have Emacs listen on a TCP socket instead of a local socket. This is the default if your OS does not support local sockets. If the Emacs server is set to use TCP, it will by default listen on a random port on the localhost interface. This can be changed to another interface and/or a fixed port using the variables server-host and server-port. A TCP socket is not subject to file system permissions. To retain some control over which users can talk to an Emacs server over TCP sockets, the emacsclient program must send an authorization key to the server. This key is normally randomly generated by the Emacs server. This is the recommended mode of operation. If needed, you can set the authorization key to a static value by setting the server-auth-key variable. The key must consist of 64 ASCII printable characters except for space (this means characters from ! to ~, or from decimal code 33 to 126). You can use M-x server-generate-key to get a random key. When you start a TCP Emacs server, Emacs creates a server file containing the TCP information to be used by emacsclient to connect to the server. The variable server-auth-dir specifies the default directory containing the server file; by default, this is ~/.emacs.d/server/. In the absence of a local socket with file permissions, the permissions of this directory determine which users can have their emacsclient processes talk to the Emacs server. If server-name is an absolute file name, the server file is created where specified by that file name. To tell emacsclient to connect to the server over TCP with a specific server file, use the -f or --server-file option, or set the EMACS_SERVER_FILE environment variable (emacsclient Options). If server-auth-dir is set to a non-standard value, or if server-name is set to an absolute file name, emacsclient needs an absolute file name to the server file, as the default server-auth-dir is hard-coded in emacsclient to be used as the directory for resolving relative filenames.

The simplest way to use the emacsclient program is to run the shell command emacsclient /file/, where file is a file name. This connects to an Emacs server, and tells that Emacs process to visit file in one of its existing frames—either a graphical frame, or one in a text terminal (Frames). You can then select that frame to begin editing. If there is no Emacs server, the emacsclient program halts with an error message (you can prevent this from happening by using the --alternate-editor""= option to emacsclient, emacsclient Options). If the Emacs process has no existing frame—which can happen if it was started as a daemon (Emacs Server)—then Emacs opens a frame on the terminal in which you called emacsclient. You can also force emacsclient to open a new frame on a graphical display using the -c option, or on a text terminal using the -t option. emacsclient Options. If you are running on a single text terminal, you can switch between emacsclient's shell and the Emacs server using one of two methods: (i) run the Emacs server and emacsclient on different virtual terminals, and switch to the Emacs server's virtual terminal after calling emacsclient; or (ii) call emacsclient from within the Emacs server itself, using Shell mode (Interactive Shell) or Term mode (Term Mode); emacsclient blocks only the subshell under Emacs, and you can still use Emacs to edit the file. When you finish editing file in the Emacs server, type C-x # (server-edit) in its buffer. This saves the file and sends a message back to the emacsclient program, telling it to exit. Programs that use EDITOR usually wait for the editor—in this case emacsclient—to exit before doing something else. If you want to abandon the edit instead, use the M-x server-edit-abort command. This sends a message back to the emacsclient program, telling it to exit with abnormal exit status, and doesn't save any buffers. You can also call emacsclient with multiple file name arguments: emacsclient /file1/ /file2/ ... tells the Emacs server to visit file1, file2, and so forth. Emacs selects the buffer visiting file1, and buries the other buffers at the bottom of the buffer list (Buffers). The emacsclient program exits once all the specified files are finished (i.e., once you have typed C-x # in each server buffer). Finishing with a server buffer also kills the buffer, unless it already existed in the Emacs session before the server was asked to create it. However, if you set server-kill-new-buffers to nil, then a different criterion is used: finishing with a server buffer kills it if the file name matches the regular expression server-temp-file-regexp. This is set up to distinguish certain temporary files. Each C-x # checks for other pending external requests to edit various files, and selects the next such file. You can switch to a server buffer manually if you wish; you don't have to arrive at it with C-x #. But C-x # is the way to tell emacsclient that you are finished. If you set the value of the variable server-window to a window or a frame, C-x # always displays the next server buffer in that window or in that frame. When emacsclient connects, the server will normally output a message that says how to exit the client frame. If server-client-instructions is set to nil, this message is inhibited.

You can pass some optional arguments to the emacsclient program, such as:

emacsclient -c +12 @var{file1} +4:3 @var{file2}

The +/line/ or +/line/:/column/ arguments specify line numbers, or line and column numbers, for the next file argument. These behave like the command line arguments for Emacs itself. Action Arguments. The other optional arguments recognized by emacsclient are listed below:

-a command, --alternate-editor=command

Specify a shell command to run if emacsclient fails to contact Emacs. This is useful when running emacsclient in a script. The command may include arguments, which may be quoted "like this". Currently, escaping of quotes is not supported. As a special exception, if command is the empty string, then emacsclient starts Emacs in daemon mode (as emacs --daemon) and then tries connecting again. The environment variable ALTERNATE_EDITOR has the same effect as the -a option. If both are present, the latter takes precedence.

-c, --create-frame

Create a new graphical client frame, instead of using an existing Emacs frame. See below for the special behavior of C-x C-c in a client frame. If Emacs cannot create a new graphical frame (e.g., if it cannot connect to the X server), it tries to create a text terminal client frame, as though you had supplied the -t option instead. On MS-Windows, a single Emacs session cannot display frames on both graphical and text terminals, nor on multiple text terminals. Thus, if the Emacs server is running on a text terminal, the -c option, like the -t option, creates a new frame in the server's current text terminal. Windows Startup. If you omit a filename argument while supplying the -c option, the new frame displays the *scratch* buffer by default. You can customize this behavior with the variable initial-buffer-choice (Entering Emacs).

-r, --reuse-frame

Create a new graphical client frame if none exists, otherwise use an existing Emacs frame.

-F alist, --frame-parameters=alist

Set the parameters for a newly-created graphical frame (Frame Parameters).

-d display, --display=display

Tell Emacs to open the given files on the X display display (assuming there is more than one X display available).

-e, --eval

Tell Emacs to evaluate some Emacs Lisp code, instead of visiting some files. When this option is given, the arguments to emacsclient are interpreted as a list of expressions to evaluate, not as a list of files to visit.

-f server-file, --server-file=server-file

Specify a server file (TCP Emacs server) for connecting to an Emacs server via TCP. Alternatively, you can set the EMACS_SERVER_FILE environment variable to point to the server file. (The command-line option overrides the environment variable.) An Emacs server usually uses a local socket to listen for connections, but also supports connections over TCP. To connect to a TCP Emacs server, emacsclient needs to read a server file containing the connection details of the Emacs server. The name of this file is specified with this option, either as a file name relative to ~/.emacs.d/server or as an absolute file name. TCP Emacs server.

-n, --no-wait

Let emacsclient exit immediately, instead of waiting until all server buffers are finished. You can take as long as you like to edit the server buffers within Emacs, and they are not killed when you type C-x # in them.

-w, --timeout=N

Wait for a response from Emacs for N seconds before giving up. If there is no response within that time, emacsclient will display a warning and exit. The default is 0, which means to wait forever.

--parent-id=id

Open an emacsclient frame as a client frame in the parent X window with id id, via the XEmbed protocol. Currently, this option is mainly useful for developers.

-q, --quiet

Do not let emacsclient display messages about waiting for Emacs or connecting to remote server sockets.

-u, --suppress-output

Do not let emacsclient display results returned from the server. Mostly useful in combination with -e when the evaluation performed is for side-effect rather than result.

-s server-name, --socket-name=server-name

Connect to the Emacs server named server-name. (This option is not supported on MS-Windows.) The server name is given by the variable server-name on the Emacs server. If this option is omitted, emacsclient connects to the default socket. If you set server-name of the Emacs server to an absolute file name, give the same absolute file name as server-name to this option to instruct emacsclient to connect to that server. You need to use this option if you started Emacs as daemon (Initial Options) and specified the name for the server started by the daemon. Alternatively, you can set the EMACS_SOCKET_NAME environment variable to point to the server socket. (The command-line option overrides the environment variable.)

-t, --tty, -nw

Create a new client frame on the current text terminal, instead of using an existing Emacs frame. This behaves just like the -c option, described above, except that it creates a text terminal frame (Text Terminals). On MS-Windows, -t behaves just like -c if the Emacs server is using the graphical display, but if the Emacs server is running on a text terminal, it creates a new frame in the current text terminal.

-T tramp-prefix, --tramp=tramp-prefix

Set the prefix to add to filenames for Emacs to locate files on remote machines (Remote Files) using TRAMP (The Tramp Manual). This is mostly useful in combination with using the Emacs server from a remote host. By ssh-forwarding the listening socket, or ssh-forwarding the listening port TCP Emacs server and making the server-file available on a remote machine, programs on the remote machine can use emacsclient as the value for the EDITOR and similar environment variables, but instead of talking to an Emacs server on the remote machine, the files will be visited in the local Emacs session using TRAMP. Setting the environment variable EMACSCLIENT_TRAMP has the same effect as using the -T option. If both are specified, the command-line option takes precedence. For example, assume two hosts, local and remote. local$ ssh -R "/home/%r/.emacs.socket":"$@{XDG_RUNTIME_DIR:-$@{TMPDIR:-/tmp@}/emacs%i@}$@{XDG_RUNTIME_DIR:+/emacs@}/server" remote remote$ export EMACS_SOCKET_NAME=$HOME/.emacs.socket remote$ export EMACSCLIENT_TRAMP=/ssh:remote: remote$ export EDITOR=emacsclient remote$ $EDITOR tmp/foo.txt #Should open in local emacs. If you are using a platform where emacsclient does not use Unix domain sockets (i.e., MS-Windows), or your SSH implementation is not able to forward them (e.g., OpenSSH before version 6.7), you can forward a TCP port instead. In this example, assume that the local Emacs listens on tcp port 12345. Assume further that /home is on a shared file system, so that the server file =~.emacs.d/server/server= is readable on both hosts. local$ ssh -R12345:localhost:12345 remote remote$ export EMACS_SERVER_FILE=server remote$ export EMACSCLIENT_TRAMP=/ssh:remote: remote$ export EDITOR=emacsclient remote$ $EDITOR /tmp/foo.txt #Should open in local emacs.

The new graphical or text terminal frames created by the -c or -t options are considered client frames. Any new frame that you create from a client frame is also considered a client frame. If you type C-x C-c (save-buffers-kill-terminal) in a client frame, that command does not kill the Emacs session as it normally does (Exiting). Instead, Emacs deletes the client frame; furthermore, if the client frame has an emacsclient waiting to regain control (i.e., if you did not supply the -n option), Emacs deletes all other frames of the same client, and marks the client's server buffers as finished, as though you had typed C-x # in all of them. If it so happens that there are no remaining frames after the client frame(s) are deleted, the Emacs session exits. As an exception, when Emacs is started as a daemon, all frames are considered client frames, and C-x C-c never kills Emacs. To kill a daemon session, type M-x kill-emacs. Note that the -t and -n options are contradictory: -t says to take control of the current text terminal to create a new client frame, while -n says not to take control of the text terminal. If you supply both options, Emacs visits the specified files(s) in an existing frame rather than a new client frame, negating the effect of -t.