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 (see 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, see emacsclient Options). If the Emacs process has no existing frame—which can happen if it was started as a daemon (see Emacs Server)—then Emacs opens a frame on the terminal in which you called
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. See 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 (see Interactive Shell) or Term mode (see 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.
You can also call
emacsclient with multiple file name arguments: ‘
emacsclient file1 file2 ...’ tells the Emacs server to visit
file2, and so forth. Emacs selects the buffer visiting
file1, and buries the other buffers at the bottom of the buffer list (see 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
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.
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.