CLI.

The CLI is the piece of Kvendra that holds the secrets the LLM must never see. Strongly recommended for any non-trivial use of the platform, mandatory by policy for Team and Enterprise. Three reasons:

1. Capability-based MCP broker. Seven typed primitives plus an escape hatch. Every privileged action goes through the broker; the LLM declares intent, not credentials.
2. Zero-knowledge vault. Argon2id key derivation, AES-256-GCM encryption, client-side. Your master password never leaves the machine, the platform never sees plaintext.
3. Tamper-evident audit log. Every primitive call appends to an HMAC-chained log (kvendra/audit-hmac/v1). Deleted or rewritten entries fail verification immediately.

Path A — cargo install (recommended)

Works on macOS, Linux and Windows (msvc). Requires a working Rust toolchain.

cargo install kvendra

kvendra --version

Path B — pre-built binaries

Download the unsigned binary for your platform from the latest GitHub release:

• macOS — Gatekeeper may warn "unidentified developer". Bypass with xattr -d com.apple.quarantine kvendra or System Settings → Privacy & Security → "Open anyway".
• Windows — SmartScreen may flag "Unknown publisher". Click "More info" → "Run anyway".
• Linux — chmod +x kvendra && ./kvendra --version.

Path C — clone & build from source

The audit-friendly path: clone the repo, build the binary yourself, install into your ~/.cargo/bin/. Useful for regulated environments, locked-down corporate networks, or when you want to read the source before running it. Requires a Rust toolchain.

git clone https://github.com/KvendraAI/kvendra-cli.git

cd kvendra-cli && cargo build --release

cargo install --path .

kvendra --version

Pin to a release tag for reproducible builds — git checkout v0.4.1 before cargo build.

The broker exposes seven typed primitives plus an escape hatch. Each primitive is a capability the LLM can request; the CLI executes it against your local credentials, returns the typed result, and appends a signed row to the audit log. The LLM never receives the underlying secret.

1. Transport separation. When invoked as kvendra in your shell, the CLI assumes a TTY and prompts. When invoked under MCP stdio by an IDE client, every destructive op (write / push / destroy in the catalog) goes through an OS consent dialog — no /dev/tty interaction, mitigating the TTY-hijack pattern documented in PAT-KVD-007.
2. Allowlist signed with HMAC. The catalog lives in ~/.kvendra/allowlist.yaml, signed with a sub-key (kvendra/allowlist-hmac/v1). Edits outside the CLI fail signature verification.
3. RAM-only password cache. Default master_password_cache = "ram-only" keeps the master key in process memory after kvendra unlock only. No disk persistence, no swap exposure.

kvendra unlock runs in your own terminal — never inside an MCP client like Claude Code or Cursor. It derives the master key with Argon2id and writes a session blob to ~/.kvendra/sessions/active.blob encrypted with a machine-bound wrap key (hostname + uid + canonical home path). Every subsequent kvendra mcp serve subprocess reads the blob to install the derived key — the password never enters the MCP client's transcript or the LLM's context.

TTL configuration

The [session] block of ~/.kvendra/config.toml controls session length:

[session]
default_ttl_seconds = 14400   # 4h (default)
max_ttl_seconds     = 86400   # 24h (default; hard cap accepted by --ttl)
renew_on_activity   = false   # absolute TTL by default

Hard ceiling: 7 days (MAX_CONFIGURABLE_TTL_SECONDS). Anything larger is rejected.

Anti-captured-env defence

kvendra unlock refuses to run inside an MCP client subprocess. Three layers, evaluated in order (PAT-KVD-CLI-008):

1. /dev/tty (POSIX) / CONIN$ (Windows). Direct open. A captured subprocess has no controlling terminal, so this fails with ENXIO and the command stops before the password prompt.
2. Triple isatty + foreground process group match. Defence in depth — confirms stdin/stdout/stderr are real TTYs and the process is in the foreground.
3. Parent ancestry walk. Flags known MCP client binaries in the error message so you know exactly why the command refused.

If you ever see kvendra unlock: no controlling terminal detected. inside an IDE, that's the guard doing its job. Open a real terminal and run kvendra unlock there instead.

What v0.1.0 already enforces — all structural, all cross-platform, all under 284+ tests in multi-OS CI (Ubuntu / macOS / Windows):

1. Capability-based MCP broker — 7 primitives plus an escape hatch.
2. Zero-knowledge vault — Argon2id key derivation, AES-256-GCM encryption.
3. Allowlist YAML signed with HMAC sub-key (kvendra/allowlist-hmac/v1).
4. Audit log HMAC-chained with end-to-end verification (kvendra/audit-hmac/v1).
5. Transport separation: CLI assumes TTY, MCP requires explicit approval per destructive op.
6. Catalog destructive ops behind a consent gate (modal on macOS, native dialog on Windows / Linux).

Not yet, but planned

• Touch-ID-protected MCP password storage — requires a signed binary. v0.2.0.
• Apple notarization + Homebrew formula — v0.2.0.
• Windows Authenticode + Linux GPG signing — v0.3.0+.

The CLI ships under Apache-2.0. Source at github.com/KvendraAI/kvendra-cli. Fork it, audit it, build your own. The licence is permissive — internal modifications carry no obligations beyond preserving the copyright notice.

What this binary is — and isn't

The CLI is the capability broker and the local vault. It holds your secrets, runs privileged primitives on the LLM's behalf, and writes a tamper-evident audit log. It is not the KB engine (that's the Platform), and it is not the agent runtime (that's Claude Code with Kvendra Skills).

For most engineers the right stack is: install the CLI vault, self-host the Platform on docker, install Kvendra Skills in Claude Code. Three components, three licences (Apache · AGPL · Apache), one coherent stack.