Velune CLI
Local-first multi-model AI developer CLI. Council-based agents. Persistent memory. Repository cognition.
No cloud required. No quota. No lock-in.
Quickstart · Commands · Architecture · Docs · Contributing
Project identity
Velune CLI is an open-source project originally created and maintained by
Surya HA. This repository is the canonical Velune CLI repository; official
releases are the tags and GitHub Releases published here and the
velune-cli package on PyPI.
- Source code: Apache-2.0. You are free to use, modify, fork, and redistribute it under the terms of the license (keep the copyright and NOTICE attributions).
- Project identity. The Velune name, wordmark, logo, and branding are not licensed by Apache-2.0 (see NOTICE and the License section). Forks are welcome; they are simply not the canonical project.
See AUTHORS.md, GOVERNANCE.md, and docs/project-origin.md.
Contents
- What it does
- 60-second quickstart
- Hardware requirements
- Startup flow
- Interface
- Providers
- Commands
- Architecture
- Memory system
- Execution modes
- Session modes
- MCP integration
- Windows
- Project docs
- Optional extras
- Contributing
- License
What it does
Velune CLI is a terminal-first AI coding assistant that runs a council of specialized agents (Planner, Coder, Reviewer, Challenger, Synthesizer) on your local machine using Ollama, or on free cloud tiers via Groq, OpenRouter, and others.
60-second quickstart
1. 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 doesn't need Python already installed: if
Python is missing or too old, uv downloads a private copy. It can't conflict
with packages other tools have installed, and it adds velune to your PATH.
Run the same command again to upgrade.
Any of these works. The first two give you the same isolation as the installer:
pipx install velune-cli # isolated, auto-managed PATH
uv tool install velune-cli # isolated, auto-managed PATH
python -m pip install velune-cli # into the current Python environment
Use python -m pip, not bare pip. That way the package goes into the same
Python you'll run it with, which matters on machines with several Pythons (common
on Windows). Plain pip needs Python 3.10+ and installs into whatever environment
is active. The usual problems with it:
-
ERROR: Could not find a version that satisfies the requirement velune-cli(with a note aboutRequires-Python): your Python is older than 3.10. Check withpython --version. Install a newer Python, or use the one-line installer, which brings its own. -
error: externally-managed-environment(Debian/Ubuntu, Homebrew Python): the OS won't let pip write to the system Python. Use the installer,pipxoruv toolabove, or a virtualenv. -
Another tool needs different versions of the same libraries: pip has only one copy of each package per environment, so two tools can break each other. An isolated install avoids this. If Velune detects an incompatible dependency at startup, it names the package and gives you the fix command.
-
velune: command not found/ "'velune' is not recognized…": the install worked, but your Python scripts directory isn't onPATH. Usepython -m velune(always works), or reinstall withpipx/the installer, which managePATHfor you.
Every dependency ships prebuilt wheels for CPython 3.10–3.14 on Windows, macOS and Linux (x86-64 and ARM64), so no compiler or build step is needed. CI checks this for the lowest version of each dependency.
Verify the install
velune --version
velune doctor
velune doctor shows your Velune version, Python interpreter, OS, and where
Velune is installed and keeps its data. It then checks the installation and
ends with "✓ Core installation is healthy" or a list of what's broken.
Optional integrations (provider keys, a local Ollama, extras such as [rag])
are reported but never count as installation failures. The exit code is
non-zero only when the core installation has a problem. velune doctor --json
gives the same report as JSON for scripts and bug reports.
2a. Local models (Ollama, free, no key)
# Install Ollama, then pull a model
curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen2.5-coder:7b
cd your-project
velune init
velune
Ollama on another machine or port? Set OLLAMA_HOST (for example
OLLAMA_HOST=192.168.1.20:11434); Velune uses it for setup, discovery, health
checks and chat alike.
Models on an external drive. Run /model locate (or
/model register <path>) on the Ollama store folder (the one containing
manifests/ and blobs/). Velune remembers it. If the drive is unplugged,
the model stays listed as unavailable with the reason. Plug it back in at the
same path and /model recheck (or just your next message) picks it up again.
If the drive comes back under a different path, use
/model relocate <model> <new-path>. A single .gguf file or a safetensors
model folder can be registered with /model register <path>. That imports it
into Ollama, which copies the file, so Velune shows the size and asks first.
2b. Cloud free tier (Groq, fastest, no GPU needed)
velune init --provider groq
velune setup # enter your free Groq key
velune
Get a free Groq key at https://console.groq.com/keys, no credit card needed.
Check your setup any time with velune doctor.
Hardware requirements
Velune CLI detects your hardware on startup and prints tier, GPU, and recommendations. On underpowered machines, it routes tasks to cloud providers automatically.
Startup flow
Velune CLI starts instantly and does no work until you ask for it. Repository cognition (indexing) is explicit and on-demand — it never runs automatically on launch.
flowchart TD
Start([velune]) --> CLI[CLI opens instantly]
CLI --> Connect[Connect a model]
Connect -.-> C1("`/connect`")
Connect -.-> C2("`/model connect`")
Connect -.-> C3("`/model use`")
Connect --> Open[Open a project]
Open -.-> O1("`/project open`")
Open -.-> O2("`/project status`")
Open --> Cog[Index the codebase]
Cog -.-> R1("`/index quick`")
Cog -.-> R2("`/index standard`")
Cog -.-> R3("`/index deep`")
classDef action fill:#0a3d62,stroke:#3c6382,stroke-width:2px,color:#fff;
classDef cmd fill:#079992,stroke:#38ada9,stroke-width:1px,color:#fff;
class Start,CLI,Connect,Open,Cog action;
class C1,C2,C3,O1,O2,R1,R2,R3 cmd;
Interface
- Startup banner shows your hardware tier, active model, and available providers
- Responsive prompt with intelligent context indicators (only displays when relevant)
- Restrained, single-accent color palette — clarity over decoration
- Tab-completion for every
/command and for model IDs - Session modes for balancing speed vs. quality (
/fast·/normal·/max) - Live dashboard (
/dashboard) — background jobs, proactive alerts, provider health in one view
The status bar shows bg:N for active background jobs, alerts:N for unread proactive alerts, and
mcp connected/total when MCP servers are configured. Alerts drain automatically after each prompt and
render above the input line.
Providers
Keys are stored AES-GCM-encrypted in your user config directory; the encryption key lives in your OS keyring (or is derived from
VELUNE_MASTER_PASSPHRASEon headless machines). Never plain text, never in git.velune setup,velune provider add <id>and the REPL's/connectall walk you through it. Model lists for OpenAI, Anthropic, Gemini, Groq and NVIDIA NIM are read live from the provider, so retired models drop out automatically. If a listing fails (offline, rate limit, a key without list permission), Velune keeps the last known list and tells you why instead of shrinking it.A key you save through Velune is the key Velune uses, even if an older
OPENAI_API_KEY(etc.) is set in your shell. SetVELUNE_PREFER_ENV_KEYS=1if you want environment variables to win instead./model statusshows which key is in effect. If the provider can't be reached when you add a key, the key is still saved and re-checked automatically later. Only a key the provider actually rejects is refused.
Commands
CLI (terminal, before the REPL)
Every top-level command below is grouped exactly as velune --help groups
it. Most groups take subcommands — run velune <command> --help for the
full signature.
velune # Start the interactive REPL session
velune chat # Older line-based chat mode (the full-screen REPL is bare `velune`)
velune run "<task>" # Run a task non-interactively and exit
velune ask "<question>" # Ask a one-shot question and exit
velune init # Set up Velune CLI in the current project
velune onboard # Run (or resume) the first-time setup wizard
velune project init|status|graph|tree|list|open|resume|explain|forget
velune session list|resume|show|delete|import|rename|search|archive|unarchive|export
velune setup # Configure providers and models interactively
velune models scan|list|refresh|pull|delete|assign|use|benchmark|health|show
velune provider list|add|remove|test|models|status|api|edit|inspect|default|backup|restore|repair
velune config show|set|get
velune trust add|list|forget
velune usage # Token usage and estimated cost for recent sessions
velune quota # Provider rate-limit and quota status
velune health # Provider reachability and response time
velune doctor # Diagnose the installation (alias: doctor check)
velune doctor providers|network
velune logs [recent|live]
velune status # Index freshness + workspace health
velune pipeline trace "<query>" # Trace a query through the retrieval pipeline
velune daemon start|stop|status
velune mcp serve|connect <url> <name>
velune memory stats|inspect|clear|compact
velune backup [--output <path>] [--include a,b] [--with-secrets] # Snapshot all Velune CLI state to one archive
velune restore <archive> [--include a,b] [--overwrite] [--dry-run] # Restore state from a backup archive
velune recover [id] [--all] [--all-workspaces] [--discard <id>] # Recover an unsaved session after a crash
Inside the REPL
52 slash commands across 11 categories (the full table is in docs/slash-commands.md). The essentials:
Run /help in the REPL for every alias, shortcut, and usage string.
Architecture
velune/
├── cli/ REPL, full-screen UI, slash commands, palettes, themes, onboarding
│ ├── commands/ Typer subcommands (workspace, session, models, doctor, mcp, memory, ...)
│ ├── handlers/ Slash-command implementations (lazily imported)
│ ├── display/ Live dashboards and the council pipeline view
│ └── rendering/ Markdown (tables, charts, Mermaid), error panels, diff fragments
├── providers/ 18 providers: adapters, discovery, credentials/crypto, validation, retry,
│ endpoint resolution (OLLAMA_HOST, base URLs), local-model import
│ ├── adapters/ Per-provider inference + streaming implementations
│ └── discovery/ Model catalog discovery (live-reconciled for OpenAI/Anthropic/Gemini/Groq)
├── models/ Model registry (non-destructive refresh), local-model registrations,
│ capability scoring, council role mapping
├── cognition/ Council: Planner -> Coder -> Reviewer -> Challenger -> Synthesizer
│ └── council/ DebateSession, per-role agents, tier classifier, contracts
├── council/ Deliberative Council engine (R0–R3 stages; behind the
│ `cognition.council_engine` flag, off by default)
├── permissions/ Execution-mode and approval policy (Manual / Plan / Auto)
├── orchestration/ Native tool-calling loop
├── prompt_intelligence/ Provider-aware prompt compiler
├── context/ Context assembly, budgets, token counting, @mentions, prompt caching
├── memory/ working -> episodic -> semantic -> graph -> lineage; SQLite pool, embeddings
├── retrieval/ Hybrid retrieval: BM25 + vector + graph, heuristic reranker
├── repository/ Scanner, AST/symbol index, import graph, blast radius, .veluneignore
├── intelligence/ Repository Intelligence Engine: change detection -> incremental reindex
├── knowledge/ Repository Knowledge Graph: AI-queryable files/symbols/relationships
├── proactive/ Alert store + watcher (CognitiveBus event subscriptions)
├── execution/ Managed execution (allowlist + PATH guard), diff preview, rollback
│ └── edit_formats/ Edit formats: search_replace, udiff, whole_file
├── tools/ File-system, git, web-fetch, and terminal tool implementations
├── mcp/ MCP server + client; stdio / SSE / HTTP / WebSocket transports
├── hooks/ Lifecycle hook dispatcher and executor (pre/post tool events)
├── plugins/ Declarative plugin loader, SKILL.md injection, hook wiring
├── resources/ Resource connectors: Docker, Postgres, MySQL, Supabase (approval-gated)
├── integrations/ GitHub and GitLab REST clients (push, PR, issues)
├── analysis/ Linting, code-smell detection, type inference
├── observability/ Context reports, execution trace log, workspace dependency graph
├── telemetry/ Token tracking, cost estimation, latency profiling
├── recovery/ Unified backup / restore / crash recovery for all persistent state
├── hardware/ Hardware detection, tier classification, GPU probe
├── kernel/ core/ DI container, bootstrap, lifecycle; paths, trust, retry, task registry, errors
├── events.py The CognitiveBus event bus
└── daemon/ Background service (server + IPC transport)
Memory system
Velune CLI maintains five memory tiers across sessions:
- Working — current conversation turns (in-process, TTL-evicted)
- Episodic — session history (SQLite, stored per workspace in your user data directory)
- Semantic — vector search over past interactions (local LanceDB and Qdrant)
- Graph — entities and relationships seen in conversations and executions
- Lineage — decision history, what was tried and why
This means "fix the auth issue from yesterday" actually works — Velune CLI retrieves recent sessions, git changes, and related context to reconstruct intent without you explaining it again.
Execution modes
Velune can read, create, edit, move and delete files and folders and run commands in your project. What it may do without asking depends on the execution mode. Press Shift+Tab to cycle, or use the commands:
In every mode Velune still asks before:
- touching anything outside the project folder (allow once / for this task / deny);
- high-risk operations:
git reset --hard,git clean, force-push, recursive deletes, global or system installs, environment/registry/firewall changes; - reading or changing secrets (
.env, keys,~/.ssh).
sudo, disk formatting and similar commands never run. These rules are
enforced in code at the tool layer, not by instructions to the model, and
every decision is logged (velune trace --type permission). Start in a mode
with velune --mode manual|plan|auto, or set the default in velune.toml:
[execution]
mode = "manual" # or "plan" / "auto"
Session modes
Switch modes at any time mid-session — the prompt badge updates immediately.
MCP integration
Velune CLI works as both an MCP server and an MCP client:
- Server (
velune mcp serve) — exposes Velune CLI's local tool council over stdio so Claude Desktop, VS Code, and other MCP-capable editors can call Velune CLI's models without sending your code to a third party. - Client (
velune mcp connect <url> <name>, or/mcp connectin the REPL) — connects to any external MCP server, lists its tools, and makes them available inside the REPL. - Transports — stdio, SSE, HTTP, and WebSocket (
ws:///wss://) are all supported. Servers can also be declared in.mcp.jsonand loaded automatically.
Outbound connections to external MCP servers are trust-gated — see MCP trust gating in the security policy.
Windows
Velune CLI runs natively on Windows — native command execution sandboxing, local Ollama integration, and OS keyring credentials. It also runs unmodified under WSL2 if preferred.
Project docs
Optional extras
The default install is intentionally lean and pure-python-friendly so it resolves fast and cleanly on every platform. Heavy or feature-specific dependencies live in extras — every feature that needs one degrades gracefully when it is absent (e.g. semantic search becomes a no-op, but lexical search and chat keep working).
pip install velune-cli # lean base (Ollama, cloud providers, chat, lexical search)
pip install 'velune-cli[rag]' # + semantic memory & vector retrieval
pip install 'velune-cli[all]' # + every optional feature
If you used the one-line installer (or uv tool), add extras with
uv tool install --force 'velune-cli[rag]'. With pipx, use
pipx install --force 'velune-cli[rag]'.
The former
[llamacpp]extra has been permanently removed:llama-cpp-pythonpulls indiskcache ≤ 5.6.3(unsafe pickle deserialization, no patched version). Installllama-cpp-pythonmanually, in a trusted single-user environment only, if you accept that risk.
Contributing
See CONTRIBUTING.md. This developer setup is only for working on Velune itself. To use Velune, follow the quickstart instead.
Before opening a PR:
pip install -e ".[dev]"
ruff check velune/
ruff format --check velune/
pyright velune/
pytest -q
Report security issues via GitHub Security Advisories — not public issues.
License
Velune CLI is licensed under the Apache License 2.0.
Copyright 2026 Surya HA
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0, or in the LICENSE file in this repository. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
The Apache-2.0 license applies to the source code. It does not by itself grant rights to the "Velune" project name, wordmark, or logo — Section 6 ("Trademarks") of the LICENSE reserves those. This is a name/branding reservation for the project, not a claim of registered trademark status.
