Vim Integration

Vim and Shelly

The repository includes a classic Vim adapter in extensions/vim. It uses yegappan/lsp to run Shelly's existing --language-server mode for semantic highlighting, diagnostics, hover, and completion. Use Vim 9 with jobs, channels, text properties, and popup windows; a recent Vim 9.1 is recommended.

Work directly from the repository

Install the Vim LSP client once:

git clone https://github.com/yegappan/lsp ~/.vim/pack/downloads/opt/lsp

Add this to ~/.vimrc, adjusting the checkout path for your machine:

set nocompatible
packadd lsp

let g:shelly_server_path = expand('~/workdir/shelly/target/release/shelly')
execute 'set runtimepath^=' . fnameescape(expand('~/workdir/shelly/extensions/vim'))
runtime plugin/shelly.vim

filetype plugin on
syntax enable

This reads the plugin directly from the checkout and uses your existing release binary. It does not build or replace the binary. For a development server, select target/debug/shelly after building with cargo build --locked.

Open a .shy file to start the server. Extensionless scripts with a Shelly shebang are recognized too. Restart Vim after changing plugin code or the server path. If you replace the binary at the same path, :ShellyLspRestart reconnects attached buffers to the new process.

Use the editor

• :LspHover shows information about the symbol under the cursor.
• Insert-mode Ctrl+X Ctrl+O requests completion.
• :LspDiag show displays document diagnostics.
• :LspServer show status helps diagnose startup problems.
• :ShellyLspStart starts manually when g:shelly_auto_start is 0.

No key mappings are replaced. The server analyzes source without executing the document or loading your startup scripts. Current server features do not include rename, definition navigation, or formatting.

Colors and layout

Shelly supplies language roles rather than terminal colors. The adapter maps its custom semantic token names to the standard names supported by the Vim client; token indices and source positions stay unchanged. Your Vim theme chooses colors through LspSemantic* groups. This translation requires no Vim-specific changes to the Shelly executable.

Comment/string syntax boundaries keep quoted brackets out of Vim's bracket matching. Semantic analysis handles richer distinctions, such as let being an ordinary argument in echo let, and references inside interpolated strings.

Semantic colors refresh while typing, including with the completion popup open. The client's highlight delay is 150 ms by default, so a brief pause requests the latest text. Set g:shelly_highlight_delay before loading the plugin to change it.

The header #tab-size N sets buffer tab stops for pipeline splits. Without a pragma, inherited $SHELLY_TAB_SIZE is used, defaulting to four. The adapter preserves your expandtab and shiftwidth settings and clears vartabstop to keep the diagram grid consistent. A file pragma is the most portable choice when sharing tabbed scripts.

If only strings and comments are colored, check :set filetype?. Shelly source should report filetype=shelly. For an already open misidentified buffer, use :set filetype=shelly followed by :ShellyLspStart. The plugin registers filetype detection even when a system vimrc enabled syntax or detection earlier.

See the adapter README for package installation, configuration, development checks, and Vim help.

---

Related: VS Code and the language server · Pipeline splits · Running Shelly