man > EMACSCLIENT

EMACSCLIENT(1)                                   GNU                                  EMACSCLIENT(1)

NAME
       emacsclient - tells a running Emacs to visit a file

SYNOPSIS
       emacsclient [options] files ...

DESCRIPTION
       This  manual page documents briefly the emacsclient command.  Full documentation is available
       in the GNU Info format; see below.

       emacsclient works in conjunction with the built-in Emacs server.

       You can either call emacsclient directly or let other programs run it for you when necessary.
       On GNU and Unix systems many programs consult the environment variable EDITOR (sometimes also
       VISUAL) to obtain the command used for editing.  Thus, setting this environment  variable  to
       'emacsclient'  will  allow these programs to use an already running Emacs for editing.  Other
       operating systems might have their own methods for defining the default editor.

       For emacsclient to work, you need an already running Emacs with a server.  Within Emacs, call
       the functions "server-start" or "server-mode".  (Your ".emacs" file can do this automatically
       if you add either "(server-start)" or "(server-mode 1)" to it.)

       When you've finished editing the buffer, type "C-x #" ("server-edit").  This saves  the  file
       and  sends  a  message back to the emacsclient program telling it to exit.  The programs that
       use EDITOR wait for the "editor" (actually, emacsclient) to exit.  "C-x #"  also  checks  for
       other pending external requests to edit various files, and selects the next such file.

       If  you  set the variable "server-window" to a window or a frame, "C-x #" displays the server
       buffer in that window or in that frame.


OPTIONS
       Most options follow the usual GNU command line syntax, with long options  starting  with  two
       dashes ("-").

       +line[:column]
              Go  to  the specified line and column.  A missing column is treated as column 1.  This
              option applies only to the next file specified.

       -a, --alternate-editor=COMMAND
              If the Emacs server is not running, run the specified shell command instead.   If  the
              empty string is specified, run "emacs --daemon" to start Emacs in daemon mode, and try
              to connect to it.

              See  also  the  ALTERNATE_EDITOR  environment  variable,  over which this option takes
              precedence.

       -c, --create-frame
              Create a new frame instead of trying to use the current Emacs frame.

       -r --reuse-frame
              Reuse an existing frame if one exists, otherwise create a new frame.

       -F, --frame-parameters=ALIST
              Set the parameters of a newly-created frame.

       -d, --display=DISPLAY
              Tell the server to display the files on the given display.

       -e, --eval
              Do not visit files but instead evaluate the arguments as Emacs Lisp expressions.

       -f, --server-file=FILENAME
              Use TCP configuration file FILENAME for communication.  Relative filenames  are  rela‐
              tive  to  "~/.emacs.d/server/" or "$XDG_CONFIG_HOME/emacs/server/", and the default is
              "server".

              See also the EMACS_SERVER_FILE environment variable,  over  which  this  option  takes
              precedence.

       -n, --no-wait
              Return  immediately  without waiting for you to "finish" the buffer in Emacs.  If com‐
              bined with --eval, this option is ignored.

       -w, --timeout=N
              How long to wait, in seconds, for Emacs to respond before giving up.  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.

       -q, --quiet
              Do  not  let emacsclient display messages about waiting for Emacs or connecting to re‐
              mote server sockets.

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

       -s, --socket-name=FILENAME
              Use socket named FILENAME for  communication.   Relative  filenames  are  relative  to
              "$XDG_RUNTIME_DIR/emacs/" or "$TMPDIR/".

              See  also  the  EMACS_SOCKET_NAME  environment  variable, over which this option takes
              precedence.

       -nw, -t, --tty
              Open a new Emacs frame on the current terminal.

       -T, --tramp=PREFIX
              Set PREFIX to add to filenames for Emacs to locate  files  on  remote  machines  using
              TRAMP.   This  is mostly useful in combination with using the Emacs server on a remote
              host (either using TCP with --server-file, or a socket forwarded over SSH).

              See also the EMACSCLIENT_TRAMP environment variable,  over  which  this  option  takes
              precedence.

       -V, --version
              Print version information and exit.

       -H, --help
              Print this usage information message and exit.

EXIT STATUS
       Normally,  the  exit status is 0.  If emacsclient shuts down due to Emacs signaling an error,
       the exit status is 1.

ENVIRONMENT
       ALTERNATE_EDITOR
              If the Emacs server is not running, run the shell command in this environment variable
              instead.  If set to the empty string, run "emacs --daemon" to start  Emacs  in  daemon
              mode,  and try to connect to it.  Will be overridden by the --alternate-editor option,
              if present.

       EMACSCLIENT_TRAMP
              A prefix to add to filenames, intended to allow Emacs to locate files  on  remote  ma‐
              chines using TRAMP.  Will be overridden by the --tramp option, if present.

       EMACS_SERVER_FILE
              Look  in  this  file to discover where to find a TCP Emacs server.  Relative filenames
              are relative to "~/.emacs.d/server/" or "$XDG_CONFIG_HOME/emacs/server/", and the  de‐
              fault is "server".  Will be overridden by the --server-file option, if present.

       EMACS_SOCKET_NAME
              The  filename  of the socket to use for communication with the Emacs server.  Relative
              filenames are relative to "$XDG_RUNTIME_DIR/emacs/" or "$TMPDIR/".  Will be overridden
              by the --socket-name option, if present.

SEE ALSO
       The program is documented fully in Using Emacs as a Server available via the Info system.

       The XDG_ environment variables are described in detail in  the  XDG Base Directory Specifica‐
       tion.


AUTHOR
       This  manual  page was originally written by Stephane Bortzmeyer <bortzmeyer AT debian.org>, for
       the Debian GNU/Linux system, but is not specific to that system.

COPYING
       This manual page is in the public domain.


GNU Emacs                                    2023-12-23                               EMACSCLIENT(1)