Home

Awesome

Build status Supported Python versions

<div align='center'> <h1>neovim-remote</h1><br> </div>

This package provides an executable called nvr which solves these cases:



Installation

pip3 install neovim-remote

If you encounter any issues, e.g. permission denied errors or you can't find the nvr executable, read INSTALLATION.md.

Theory

Nvim always starts a server. Get its address with :echo v:servername. Or specify an address at startup: nvim --listen /tmp/nvimsocket.

nvr (the client) will use any address given to it via --servername, $NVIM_LISTEN_ADDRESS (obsolete in nvim but still supported in nvr), or defaults to /tmp/nvimsocket.

If the targeted address does not exist, nvr starts a new process by running "nvim". You can change the command by setting $NVR_CMD. (This requires forking, so it won't work on Windows.)

First steps

Start a nvim process (which acts as a server) in one shell:

nvim --listen /tmp/nvimsocket

And do this in another shell:

# nvr uses /tmp/nvimsocket by default, so we're good.

# Open two files:
nvr --remote file1 file2

# Send keys to the current buffer:
nvr --remote-send 'iabc<esc>'
# Enter insert mode, insert 'abc', and go back to normal mode again.

# Evaluate any VimL expression, e.g. get the current buffer:
nvr --remote-expr 'bufname("")'
README.md
<details> <summary>click here to see all nvr options</summary>
$ nvr -h
usage: nvr [arguments]

Remote control Neovim processes.

If no process is found, a new one will be started.

    $ nvr --remote-send 'iabc<cr><esc>'
    $ nvr --remote-expr 'map([1,2,3], "v:val + 1")'

Any arguments not consumed by options will be fed to --remote-silent:

    $ nvr --remote-silent file1 file2
    $ nvr file1 file2

All --remote options take optional commands.
Exception: --remote-expr, --remote-send.

    $ nvr +10 file
    $ nvr +'echomsg "foo" | echomsg "bar"' file
    $ nvr --remote-tab-wait +'set bufhidden=delete' file

Open files in a new window from a terminal buffer:

    $ nvr -cc split file1 file2

Use nvr from git to edit commit messages:

    $ git config --global core.editor 'nvr --remote-wait-silent'

optional arguments:
  -h, --help            show this help message and exit
  --remote [<file> [<file> ...]]
                        Use :edit to open files. If no process is found, throw
                        an error and start a new one.
  --remote-wait [<file> [<file> ...]]
                        Like --remote, but block until all buffers opened by
                        this option get deleted or the process exits.
  --remote-silent [<file> [<file> ...]]
                        Like --remote, but throw no error if no process is
                        found.
  --remote-wait-silent [<file> [<file> ...]]
                        Combines --remote-wait and --remote-silent.
  --remote-tab [<file> [<file> ...]]
                        Like --remote, but use :tabedit.
  --remote-tab-wait [<file> [<file> ...]]
                        Like --remote-wait, but use :tabedit.
  --remote-tab-silent [<file> [<file> ...]]
                        Like --remote-silent, but use :tabedit.
  --remote-tab-wait-silent [<file> [<file> ...]]
                        Like --remote-wait-silent, but use :tabedit.
  --remote-send <keys>  Send key presses.
  --remote-expr <expr>  Evaluate expression and print result in shell.
  --servername <addr>   Set the address to be used. This overrides the default
                        "/tmp/nvimsocket" and $NVIM_LISTEN_ADDRESS.
  --serverlist          Print the TCPv4 and Unix domain socket addresses of
                        all nvim processes.
  -cc <cmd>             Execute a command before every other option.
  -c <cmd>              Execute a command after every other option.
  -d                    Diff mode. Use :diffthis on all to be opened buffers.
  -l                    Change to previous window via ":wincmd p".
  -o <file> [<file> ...]
                        Open files via ":split".
  -O <file> [<file> ...]
                        Open files via ":vsplit".
  -p <file> [<file> ...]
                        Open files via ":tabedit".
  -q <errorfile>        Read errorfile into quickfix list and display first
                        error.
  -s                    Silence "no server found" message.
  -t <tag>              Jump to file and position of given tag.
  --nostart             If no process is found, do not start a new one.
  --version             Show the nvr version.

Development: https://github.com/mhinz/neovim-remote

Happy hacking!
</details>

Typical use cases

Demos

(Click on the GIFs to watch them full-size.)

Using nvr from another shell: Demo 1

Using nvr from within :terminal: Demo 2

FAQ