Installation

Installation

There are no prebuilt release binaries yet. Every installation path builds ctrlvim from source, and every path needs the same two things first.

Requirements

Rust 1.80 or newer, and a C compiler. ctrlvim vendors Lua 5.4 and tree sitter as C dependencies, so a compiler is required even though none of ctrlvim's own code is C.

On Linux, cc, gcc, or clang is enough, and one of these is usually already present.

On macOS, run xcode-select --install if you have not already, since Xcode's Command Line Tools provide the compiler.

Install script

The simplest way to install ctrlvim:

curl -fsSL https://ctrluserknown.github.io/ctrlvim/install.sh | sh

This installs to ~/.local by default, with no root privileges needed. The script is a plain POSIX shell script. It clones the repository into ~/.cache/ctrlvim/src (or updates the existing clone there), then runs make install against it, the same thing described below under Manual Install. It is worth reading before piping it into sh, since it is short and does nothing surprising.

For a system wide install, run it as root explicitly:

sudo sh -c "$(curl -fsSL https://ctrluserknown.github.io/ctrlvim/install.sh)" -- --prefix /usr/local

Two options control where the script clones the source and where it installs:

install.sh --prefix /usr/local     # install destination, default ~/.local
install.sh --dir ~/src/ctrlvim     # source checkout location

The same values can be set with CTRLVIM_PREFIX and CTRLVIM_SRC_DIR environment variables.

Manual install

If you already have a clone of the repository, or you would rather not pipe a script into a shell, drive the Makefile directly:

sudo make install                 # /usr/local/bin/cvi
make install PREFIX=~/.local      # no root needed; put ~/.local/bin on PATH
make user-config                  # seed ~/.config/ctrlvim/config.toml
sudo make uninstall               # remove everything install placed

make install PREFIX=... and sudo make install both build a release binary first, so there is no separate build step to run beforehand.

Staged installs, for anyone packaging ctrlvim for a distribution, work the same way any Makefile based package expects:

make install DESTDIR=/tmp/pkg PREFIX=/usr/local

macOS universal binary

The targets above build for the host architecture only. For one binary that runs on both Apple Silicon and Intel Macs:

make macos-deps       # rustup target add, once per machine
make macos            # builds a universal, ad-hoc signed binary
sudo make macos-install

After installing

cvi writes a starter configuration file to ~/.config/ctrlvim/config.toml the first time it runs, and never overwrites an existing one. make user-config reports whether that file already exists without touching it.

cvi                  # dashboard for the current directory
cvi src/              # dashboard for a directory
cvi a.rs b.rs         # open files, cursor in the first
cvi --help
cvi --version

Uninstalling

sudo make uninstall               # matches sudo make install
make uninstall PREFIX=~/.local    # matches make install PREFIX=~/.local

make uninstall only removes the files and directories that make install created, so it will not touch a shared prefix directory that other software also installs into.