EMACSCLIENT(1)

💖 EMACSCLIENT(1) 💖

okay bestie, welcome to the emacsclient page 💅 this is the GNU one, and yes it's literally the little buddy that walks up to a running Emacs and is like "hey. open this file for me." iconic behaviour, no notes 🎀

---

✨ NAME ✨

emacsclient — tells a running Emacs to visit a file 🌸

---

✨ SYNOPSIS ✨

emacsclient [options] files ...

---

✨ DESCRIPTION ✨

so this page is the quick lil overview of emacsclient, okay? the full docs live in the GNU Info format, and there's a pointer down in SEE ALSO for that 👀

emacsclient works in conjunction with the built-in Emacs server. they're a duo. a package deal. 🫶

you can either call emacsclient yourself directly, or just let other programs run it for you whenever they need to. on GNU and Unix systems, a lot of programs check the environment variable EDITOR (and sometimes also VISUAL) to figure out which command they should use for editing. so if you set that environment variable to emacsclient, those programs will get to use an already running Emacs for editing. slay. other operating systems might have their own lil methods for defining the default editor, iykyk.

for emacsclient to work at all, you need an already running Emacs with a server. inside Emacs, call the functions server-start or server-mode. (your .emacs file can totally do this automatically for you if you add either (server-start) or (server-mode 1) to it. one line, main character energy ✨)

when you're done 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 are literally just waiting for the "editor" (which is actually emacsclient, surprise) to exit. C-x # also checks for other pending external requests to edit various files, and selects the next such file. very organised of it 💅

and 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. cute.

---

✨ OPTIONS ✨

most options follow the usual GNU command line syntax, with long options starting with two dashes (-). classic.

• +line[:column] — go to the specified line and column. a missing column is treated as column 1. ngl this option applies only to the next file specified, so don't be shocked when it doesn't stick around 🌸
• -a, --alternate-editor=COMMAND — if the Emacs server isn't 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. new frame, who dis 💅
• -r --reuse-frame — reuse an existing frame if one exists, otherwise create a new frame. (note: that's literally how it's written up there, no comma, I don't make the rules 🙈)
• -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. we're doing math now 🧮✨
• -f, --server-file=FILENAME — use TCP configuration file FILENAME for communication. relative filenames are relative 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 combined with --eval, this option is ignored. bye, not waiting ✌️
• -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. forever forever? forever 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 remote server sockets. shhh 🤫
• -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, --no-window-system — open a new Emacs frame on the current terminal. terminal girlies rise 🌈
• -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. so basically: chill = 0, drama = 1. 💀

---

✨ ENVIRONMENT ✨

• ALTERNATE_EDITOR — if the Emacs server isn't 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 machines 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 default 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. go read it, it's giving thorough 📚
• the XDG_ environment variables are described in detail in the XDG Base Directory Specification.

---

✨ AUTHOR ✨

this manual page was originally written by Stephane Bortzmeyer <bortzmeyer@debian.org>, for the Debian GNU/Linux system, but it is not specific to that system. shoutout to the og 🫶

---

✨ COPYING ✨

this manual page is in the public domain. do whatever, bestie, it's free 🌈✨

---

okay that's the whole page!! 💖 this was EMACSCLIENT(1) from GNU Emacs, dated 2024-08-20 — go forth and let your Emacs server carry you, periodt 👑🎀