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
• 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.

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

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

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_PASSPHRASE on headless machines). Never plain text, never in git. velune setup, velune provider add <id> and the REPL's /connect all walk you through it. Model lists for OpenAI, Anthropic, Gemini and Groq are read live from the provider, so retired models drop out automatically.

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
│   ├── adapters/     Per-provider inference + streaming implementations
│   └── discovery/    Model catalog discovery (live-reconciled for OpenAI/Anthropic/Gemini/Groq)
├── models/           Model registry, capability scoring, council role mapping
├── cognition/        Council: Planner -> Coder -> Reviewer -> Challenger -> Synthesizer
│   └── council/      DebateSession, per-role agents, tier classifier, contracts
├── 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:

1. Working — current conversation turns (in-process, TTL-evicted)
2. Episodic — session history (SQLite, stored per workspace in your user data directory)
3. Semantic — vector search over past interactions (local LanceDB and Qdrant)
4. Graph — entities and relationships seen in conversations and executions
5. 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.

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 connect in 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.json and 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-python pulls in diskcache ≤ 5.6.3 (unsafe pickle deserialization, no patched version). Install llama-cpp-python manually, 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.