curl -fsSL https://raw.githubusercontent.com/Surya-Hariharan/Velune-CLI/main/scripts/install.sh | sh
On Windows, use the PowerShell installer. Velune CLI is beta software; read the
project status before relying on it for important work.
Installation
Install Velune CLI
macOS, Linux, WSL
curl -fsSL https://raw.githubusercontent.com/Surya-Hariharan/Velune-CLI/main/scripts/install.sh | sh
Windows (PowerShell)
irm https://raw.githubusercontent.com/Surya-Hariharan/Velune-CLI/main/scripts/install.ps1 | iex
The installer puts Velune in its own isolated environment using uv. It does not need
Python to be installed: if Python is missing or too old, uv downloads a private copy. It adds velune to your PATH,
and running the same command again upgrades the installation. The scripts are fetched from the main branch and uv's
own installer is fetched from astral.sh; read the scripts first if that trust is not acceptable.
pipx install velune-cli # isolated, PATH managed
uv tool install velune-cli # isolated, PATH managed
python -m pip install velune-cli # into the current Python environment
Use python -m pip, not bare pip, so the package goes into the same Python you will run it with. Plain pip needs
Python 3.10 or newer. Common problems:
Could not find a version that satisfies the requirement velune-cli (with a Requires-Python note): your Python
is older than 3.10. Check python --version.externally-managed-environment (Debian, Ubuntu, Homebrew Python): the OS protects its Python. Use the installer,
pipx, uv tool, or a virtualenv.- Conflicts with other tools' dependencies: pip keeps one copy of each package per environment. An isolated install
avoids this. If Velune detects an incompatible dependency at startup, it names the package and the fix command.
velune: command not found: your Python scripts directory is not on PATH. Use python -m velune, or reinstall
with pipx or the installer.
On the platforms marked Tested below, the core dependencies install from prebuilt wheels for CPython 3.10 to 3.14,
so no compiler is needed. CI checks this, including at the lowest allowed version of each dependency.
Platform support
| Platform | Status |
|---|
| Windows 10/11, x86-64 | Tested in CI |
| macOS, Apple Silicon (arm64) | Tested in CI |
| Linux, x86-64, glibc (Ubuntu, Debian, Fedora, …) | Tested in CI |
| Linux, arm64, glibc | Not tested. Prebuilt wheels exist for the core dependencies. |
| macOS, Intel (x86-64) | Unverified. In our lock file (uv.lock) the cryptography release has no macOS x86-64 wheel, so installing the base CLI may need a Rust toolchain to build it. The installer does not block it and it may work; we have not tested it or checked what PyPI currently offers. The optional [rag] extra is unavailable. |
| Alpine / other musl Linux | Not tested. Prebuilt wheels exist for the core dependencies. |
| WSL 2 | Not tested separately; treated as Linux. |
| Windows on ARM64 | Unsupported. The installer stops before downloading anything. Required dependencies (cryptography, tiktoken) publish no Windows ARM64 wheels, so an install would need a Rust and C++ build toolchain. |
| 32-bit systems, BSD, other architectures | Unsupported. The installer stops before downloading anything. |
Tested means a CI job installs and runs it. Not tested means the
installer lets you proceed and our lock file has prebuilt wheels for the core
dependencies, so we expect it to work, but no CI job covers it. Unverified
means we found a gap that could make the install fail or need build tools, and
have not confirmed either way. Unsupported means the installer refuses to
run. None of these is a guarantee.
Verify the install
velune --version
velune doctor
velune doctor shows the Velune version, Python interpreter, operating system, and where Velune is installed and keeps
its data. It ends with "✓ Core installation is healthy." or a list of problems. Optional integrations (provider keys, a
local Ollama, extras such as [rag]) are reported but never counted as installation failures, and the exit code is
non-zero only when the core installation has a problem. velune doctor --json prints the same report as JSON with home
paths shortened to ~, so it can be pasted into a bug report.
Optional extras
The base install is small. Features that need heavier or compiled dependencies live in extras and turn themselves off
when the extra is missing (semantic search is disabled while keyword search keeps working).
| Extra | Enables |
|---|
rag | Semantic memory and vector retrieval (lancedb, pyarrow, qdrant-client) |
parsing | Tree-sitter parsing for repository cognition; lighter heuristics are used without it |
telemetry | Export spans and metrics to an OTLP collector |
gguf, docker | GGUF metadata reading; the Docker sandbox |
all | Every optional feature |
pip install 'velune-cli[rag]'
uv tool install --force 'velune-cli[rag]' # add an extra to a uv tool or installer install
pipx install --force 'velune-cli[rag]' # add an extra to a pipx install
This is the beginning of the README. Read the rest at the original. Read the full README ↗
