emacsclient

Open a file in an existing Emacs server (using GUI if available)

$ emacsclient [path/to/file]

$ emacsclient [[-nw|--no-window-system]] [path/to/file]

$ emacsclient [[-c|--create-frame]] [path/to/file]

$ emacsclient [[-e|--eval]] '([command])'

$ emacsclient [[-a|--alternate-editor]] [editor] [path/to/file]

$ emacsclient [[-e|--eval]] '(save-buffers-kill-emacs)'

emacsclient [OPTION]... [FILE]...
emacsclient [OPTION]... --eval EXPRESSION

-a, --alternate-editor=EDITOR
    Specify an alternate editor to run if the Emacs daemon is not running. For example, `emacsclient -a nano file.txt`.

-c, --create-frame
    Create a new graphical (X) frame for opening files or evaluating expressions.

-t, --tty
    Create a new terminal frame for opening files. Requires Emacs to be built with terminal frame support.

-n, --no-wait
    Return immediately; do not wait for the Emacs server to finish processing the file. This is useful for opening multiple files quickly.

-w, --wait
    Wait for the Emacs server to finish processing the file (e.g., when you save and close the buffer). This is the default behavior when opening files if `-n` is not specified.

-s, --socket-name=NAME
    Connect to the Emacs server via the specified socket file or directory. Useful when running multiple Emacs daemon instances.

-e, --eval=EXPRESSION
    Evaluate an Emacs Lisp EXPRESSION in the running Emacs daemon. The result is printed to standard output.

-d, --display=DISPLAY
    Specify the X display on which to open a new frame. Only applicable when creating graphical frames.

--version
    Print the version information of `emacsclient`.

--help
    Display a help message with available options.

emacsclient is a command-line utility that connects to an already running Emacs daemon (server) to open files or evaluate Emacs Lisp code. The Emacs daemon is started using the `emacs --daemon` command, which runs Emacs in the background without a visible frame. When you invoke `emacsclient`, it sends a request to this background Emacs process to open a file in a new or existing Emacs frame, or to execute a specified Lisp expression.

The primary benefit of using `emacsclient` is speed. Instead of launching a new Emacs instance for every file you want to open (which can be slow due to initialization time), `emacsclient` allows you to reuse an existing, already loaded Emacs process. This significantly reduces the startup time for opening files, making Emacs feel more responsive and behave like a lightweight editor while retaining all its powerful features in the background server. It's particularly useful for integrating Emacs into desktop environments as the default text editor, or for opening files quickly from the terminal.

The primary limitation of `emacsclient` is its dependency on a running Emacs daemon. If `emacs --daemon` is not active, `emacsclient` will fail unless an alternate editor is specified using `-a`. Users must ensure the socket file used by `emacsclient` matches the one created by the Emacs daemon, especially in environments with multiple Emacs instances or differing user permissions.

To use `emacsclient`, you must first start an Emacs daemon. This is typically done by running `emacs --daemon` in your terminal or by adding it to your shell's startup script.

Example workflow:

1. Start the Emacs daemon:
`$ emacs --daemon`

2. Open a file using emacsclient:
`$ emacsclient file.txt`
(This will open `file.txt` in a new or existing Emacs frame.)

3. Open a file in a new graphical frame:
`$ emacsclient -c another_file.org`

4. Evaluate Emacs Lisp:
`$ emacsclient -e '(message "Hello from emacsclient!")'`
(The message will appear in the Emacs *Messages* buffer.)

5. Stop the Emacs daemon (optional):
`$ emacsclient --eval '(kill-emacs)'`
(This gracefully shuts down the Emacs server process.)

`emacsclient` has been an integral part of GNU Emacs for many years, evolving alongside Emacs's server capabilities. Its introduction and refinement were driven by the desire to make Emacs more performant and integrated into modern desktop environments, allowing users to keep a single, persistent Emacs instance running in the background for quick file access, thereby overcoming the perceived 'slow startup' of Emacs.

emacs(1)