vanara — the Vanara CLI

Install and manage AI agent packs, agents, and skills in any project. Items install in Claude Code layout (.claude/agents/, .claude/skills/), so Claude Code picks them up with zero extra configuration. Zero runtime dependencies, Node ≥ 20.

npx vanara init                       # starter profiles: a complete harness in one command
npx vanara doctor                     # scan this project, recommend items
npx vanara install security-pack      # shows the exact file plan, confirms, then installs
npx vanara install code-reviewer --target cursor   # compile to Cursor rules instead
npx vanara scope --diff               # gate agent capability changes in PR review
npx vanara scope --budget             # what your .claude/ costs in context tokens
npx vanara memory promote debugger    # carry a project's lessons to every repo
npx vanara usage                      # actual Claude Code token spend for this project
npx vanara update --apply             # pull newer catalog versions

Command surface

| Command | Does | |---|---| | init [<profile>] | Set up a complete starter harness (items + CLAUDE.md): solo-shipper, security-first, startup-web — all free-tier. | | list / info <name> | Browse the catalog / one item (incl. per-item sha256). | | install <name...> | Plan → confirm → install into ./.claude. --dry-run previews; -y skips the prompt. | | install <name> --target cursor | Compile to .cursor/rules/*.mdc (Cursor). Same lockfile; uninstall works. | | uninstall <name> [--members] | Remove an item (or a pack and its members). | | installed / verify | What this project runs / re-hash every installed file against the recorded checksums. | | scope [--record\|--diff\|--budget] | Capability manifest of installed agents; record a baseline and fail CI on escalations; audit whole-project context cost. | | update [--apply] | Show (or apply) available catalog updates. | | memory [<agent>] [--prune] | What agents learned in this project. | | memory --global / memory promote <agent> | The cross-repo store (~/.vanara/memory) — fed only by explicit promote. | | memory --playbook [--init] | The team playbook agents honor (.claude/playbook.md). | | doctor / report / usage | Recommend items / what agents did here / real token spend + cost estimate. | | unlock <key> / account / sync | Pro licensing (Polar.sh) and premium catalog sync. | | request "<capability>" | Log a gap in the catalog. |

Also ships vanara-mcp — a zero-dependency MCP server (stdio) exposing search_catalog, get_item, and recommend to any MCP client: claude mcp add vanara -- npx -y -p vanara vanara-mcp (the bin ships inside the vanara package, so npx needs -p vanara). Read-only by design — installing stays a human action in the terminal.

Free vs Pro — no API keys, ever

The free catalog ships inside the package: npx vanara works for anyone, offline, with zero configuration and zero API keys. Tiers:

• Free — 30 items (code-review-pack, security-pack and their members, plus core skills including vanara-orchestrate and vanara-route). Install freely, forever.
• Pro ($10/mo) — all 213 items. Subscribe via Polar.sh (they handle payment + tax), get a license key, then: vanara unlock <license-key>. The key is validated against Polar's public API (no secrets in this CLI), re-checked weekly, with a 7-day offline grace period. vanara account shows your tier; vanara unlock --remove returns to free.

The one key in the system is the Pro license key — never an LLM/API key.

Trust model — plan first, verify always

• Plan before write — install prints every destination path and a per-item content hash and asks for confirmation before anything lands. Installs only ever write under .claude/ (or .cursor/rules/ with --target cursor); the install step is a plain file copy — nothing executes.
• Signed catalog — the release process signs a manifest of per-item content hashes (ed25519); the public key is pinned in this package. install and init refuse items that don't match the signed manifest. Unsigned dev catalogs still work and are reported as unsigned.
• Checksums recorded — per-file sha256 hashes land in .vanara.json at install. vanara verify re-hashes anytime and exits non-zero on any drift — including items compiled for Cursor.
• Capability governance — every agent declares its tools; vanara scope --record commits a baseline and vanara scope --diff exits non-zero when an update escalates capabilities (an agent gaining shell or network access shows up in PR review, not in production).
• Pinned source — the free catalog is pinned by the npm package version + integrity hash in your lockfile; catalog-meta.json stamps the exact source commit. Free items mirror the public Apache-2.0 repo at github.com/vanara-agents/skills.

Memory that compounds

Agents read three layers, most specific first: project (.claude/memory/<agent>.md, written by agents as they work), global (~/.vanara/memory/<agent>.md, carried across all your repos, fed only by vanara memory promote), and the team playbook (.claude/playbook.md, committed conventions). Agents write only project memory — nothing crosses repos without your explicit say-so.

How it works

• Catalog source — a directory with agents/ skills/ packs/ (flat <name>.md or packaged dirs with AGENT.md / SKILL.md / PACK.md plus references/ examples/ scripts/). Resolution order: --source flag → VANARA_REGISTRY env → synced premium catalog → the catalog bundled in this package.
• Packs are bundles — installing one resolves its members (validated first; missing members abort with provenance, nothing half-installs) and records the pack as a named group in the lockfile.
• Lockfile — .vanara.json records every installed item, its version, target, and exact file list, so uninstall and update are exact.