Written in V — MIT Licensed
This tool was developed with the assistance of AI

The hackable
Unix shell

vlsh is an interactive Unix shell written in V — simple, fast, and hackable, with a clean codebase you can read, modify, and extend.

vlsh — ~
  # inline autosuggestion from history
~$ git push origin main
 
  # press → or End to accept
~$ git push origin main
  Everything up-to-date.
 
  # tab completion works after trailing /
~$ cd .config/nvim
 
~$

Everything you need, nothing you don't

These features are included in v1.2.1, including the latest POSIX, stability, and interactive line continuation fixes.

⚡

Fast & Compiled

Built with V, vlsh compiles to a lean native binary. Cold start is near-instant — no interpreter overhead on every keystroke.

|

Pipes, Redirection & Chains

Concurrent pipelines (|), ordered file and descriptor redirection (>, >>, <, 2>, 2>&1), and command lists with &&, ||, and ;. Quoted arguments stay intact; unquoted expansion results split on IFS before pathname expansion.

💬

Smart History

Shared history file (~/.vlsh_history, last 5 000 entries), arrow keys, and Ctrl+R search. Bash-style history expansion at the interactive prompt: !!, !$, !n, !-n, !prefix, and !?sub.

⇥

Tab Completion

Files and directories; the first word also completes command names from $PATH. After cd , only directories are suggested. Plugins can register custom completions (for example SSH hostnames).

→

Inline Autosuggestions

Fish-style ghost text appears as you type, sourced from command history. Press → or End to accept the suggestion. Includes path validation for cd candidates and a filesystem fallback.

🔌

Plugin System

Install from the official repo with plugins install, plugins search, plugins update, plugins delete, or plugins reinstall. Plugins can add commands, prompt lines, pre/post hooks, output_hook, tab completions, mux_status for the multiplexer bar, and help text surfaced via help.

⎗

Built-in Multiplexer

Run mux to split panes (resizable), use the mouse, copy/paste, a status bar, and up to 1 000 lines of scrollback per pane — VT100-friendly so editors like vim and nano work inside panes.

📜

Scripts & Batch Commands

Use vlsh -c, a script file, or stdin. Scripts support positional arguments, multiline pipelines, conditional lists, quoted words, and comments. Batch execution returns the last command’s status and skips prompts and history. V scripts (.vsh) run through V.

🎨

Theming & Aliases

Configure prompt colors via RGB values in ~/.vlshrc. Manage aliases at runtime or persist them in your config — all without restarting the shell.

POSIX compatibility

vlsh is not POSIX-conformant, but it supports commonly used POSIX shell features — with a documented, tested subset growing over time (see posix-inventory.md on GitHub).

Supported operators

OperatorBehaviour
&&Run next command only on success
||Run next command only on failure
;Run next command unconditionally
|Stream output into the next command concurrently
<Redirect stdin from a file
>Redirect stdout, overwriting the file
>>Redirect stdout, appending to the file
2> fileRedirect stderr to a file
2>&1Duplicate the current stdout onto stderr
n>&m / n>&-Duplicate or close a descriptor (0–9)

Supported builtins

BuiltinDescription
export / unsetExport shell-local variables to child commands, or remove variables
:Expand arguments and apply redirections, then return success
set -- / shiftReplace or remove positional parameters
source / .Execute a script in the current shell context
cdChange directory; supports ~, $HOME, and cd -
exitExit with an optional status code; defaults to the last status

Redirections apply from left to right for builtins and external commands: cmd > log 2>&1 sends both streams to the file, while cmd 2>&1 > log keeps stderr on the original stdout. Pipeline stages stream concurrently, the final stage determines the status, and core builtins and expansion side effects stay isolated to their stage.

NAME=value stays local until export NAME. Unquoted expansions split on IFS; empty IFS disables splitting. Scripts receive $0, numbered parameters, $#, and "$@". $? holds the last status; missing commands return 127, and commands found but not executable return 126.

Command substitution, arithmetic expansion, loops, functions, subshells, here-documents, and background jobs remain unsupported. See testing and stability for regression coverage and native validation limits.

Get up and running

Latest published release v1.2.1 — Debian and RPM packages and a standalone binary for 64-bit Linux, plus cross-compiled FreeBSD and DragonFly binaries. Includes POSIX and stability improvements and a fix for pasted commands with backslash continuations. Full instructions: README on GitHub.

shell
# Release v1.2.1; installs /usr/bin/vlsh and registers it in /etc/shells
curl -LO https://github.com/vlshcc/vlsh/releases/download/v1.2.1/vlsh_1.2.1_amd64.deb
sudo dpkg -i vlsh_1.2.1_amd64.deb

# Set as login shell (optional)
chsh -s /usr/bin/vlsh
shell
# Release v1.2.1; pre-built 64-bit Linux RPM
curl -LO https://github.com/vlshcc/vlsh/releases/download/v1.2.1/vlsh-1.2.1-1.x86_64.rpm
sudo rpm -U vlsh-1.2.1-1.x86_64.rpm
shell
# Standalone 64-bit Linux binary (release v1.2.1)
curl -LO https://github.com/vlshcc/vlsh/releases/download/v1.2.1/vlsh_1.2.1_amd64_linux
chmod +x vlsh_1.2.1_amd64_linux
sudo mv vlsh_1.2.1_amd64_linux /usr/local/bin/vlsh

# Approve shell and set as default (optional)
echo /usr/local/bin/vlsh | sudo tee -a /etc/shells
chsh -s /usr/local/bin/vlsh
shell
# Requires V and make; CI uses V 0.5.2 — https://vlang.io
git clone https://github.com/vlshcc/vlsh.git
cd vlsh
make build
./vlsh

# Install the built binary and register /usr/local/bin/vlsh in /etc/shells
sudo make install

# Optional: set as your login shell
chsh -s /usr/local/bin/vlsh

# Python 3 is required for the integration tests
make test
# Linux: build only a .deb (requires dpkg-deb)
make dist-deb

Commands and scripts

shell
./vlsh -c 'printf hello | cat'
./vlsh path/to/script 'one two'
./vlsh -c 'printf "<%s>\n" "$@"' name 'one two' ''
printf 'echo hello\nfalse\n' | ./vlsh
./vlsh -c 'help syntax'
./vlsh --version

Batch execution skips startup exports, prompts, history writes, and automatic plugin loading. Existing aliases are read from ~/.vlshrc. Scripts use the command parser for multiline pipelines, conditional lists, quoted words, and comments. At the interactive prompt, a trailing unescaped backslash shows a > continuation prompt; the joined command executes and is saved as one history entry. Ctrl+C cancels the whole command. The built-in help, help syntax, help set, and help export describe the supported behavior. For a user-local installation, pass REGISTER_SHELL=0; staged installs with DESTDIR also skip shell registration.

Extend with pure V

Plugins install from the official repository into ~/.vlsh/plugins/<name>/<version>/; vlsh compiles them on startup. The remote catalogue lives at github.com/vlshcc/plugins. Plugins can:

  • 1 Register commands, prompt lines, and help text for the built-in help command
  • 2 Run pre/post hooks and output_hook around every command
  • 3 Provide tab completions and mux_status text for the multiplexer status bar
  • 4 Be searched, installed, updated, removed, or purged and re-fetched with plugins reinstall
~/.vlsh/plugins/myplugin/v1.0.0/myplugin.v
// Plugins implement main() and respond to argument tokens
module main

import os

fn main() {
    arg := if os.args.len > 1 { os.args[1] } else { '' }
    match arg {
        'capabilities' { println('prompt') }
        'prompt' {
            branch := os.execute('git branch --show-current')
            if branch.exit_code == 0 {
                print(' (' + branch.output.trim_space() + ')')
            }
        }
        else {}
    }
}

Plugin management

CommandDescription
plugins listShow all locally installed plugins with their installed version
plugins remoteList plugins in the remote repository with version info and available updates
plugins search <query>Search available plugins by name or description
plugins install <name>Download and install the latest semver version of a plugin
plugins update [name]Update one plugin or all installed plugins to their latest version
plugins reloadRecompile and reload all plugins (run after install or update)
plugins enable / disable <name>Activate or deactivate a plugin without deleting it
plugins enable / disable allActivate or deactivate all plugins at once
plugins delete <name>Remove an installed plugin and its entire directory
plugins reinstall <name>Remove the local copy and install the latest from the remote repository