CLI Overview

The VRIN CLI lets you interact with your knowledge base directly from the terminal. It’s designed for both humans and AI agents: human-readable output at a TTY, structured JSON when piped or called programmatically.

Installation

pip (Python)
npm (Node.js)
curl (no install)

pip install vrin

Requires Python 3.9+. Installs the vrin command globally.

npm install -g @vrin/cli

Wraps the Python CLI. Requires Python 3.9+ on the system.

Use the REST API directly:

curl -X POST https://api.vrin.cloud/query \
  -H "Authorization: Bearer vrin_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "What is ACME revenue?"}'

Authentication

Set your API key as an environment variable:

export VRIN_API_KEY=vrin_live_your_api_key

Or pass it inline per command:

VRIN_API_KEY=vrin_... vrin query "What is ACME's revenue?"

Get an API key at vrin.cloud, or create one from the CLI:

vrin auth login you@example.com
vrin auth create-key --name "my-agent"

Quick start

# Insert knowledge
vrin insert "ACME Corp reported $50M revenue in Q4 2025" --title "ACME Q4"

# Query
vrin query "What is ACME's revenue?"

# Upload a file
vrin upload ./earnings_report.pdf

# Get raw facts (no AI summary)
vrin facts "ACME revenue"

# Stream a response
vrin query "Summarize ACME performance" --stream

Output modes

The CLI automatically detects its environment:

Context	Output format	Example
Interactive terminal (TTY)	Human-readable	`vrin query "..."`
Piped / non-TTY	JSON	`vrin query "..." \| jq .`
`--json` flag	JSON (forced)	`vrin query "..." --json`
`VRIN_OUTPUT=json` env var	JSON (forced)	For agent environments

JSON output format:

// Success
{"ok": true, "data": {"summary": "...", "facts_count": 12, ...}}

// Error (always to stderr)
{"ok": false, "error": {"code": "auth_failed", "message": "Invalid API key"}}

For AI agents

VRIN is built to be called by AI agents. Key patterns: 1. Auto-discovery: Run vrin --describe to get a machine-readable JSON schema of all commands, arguments, and flags. Point your agent here first.

vrin --describe

2. Always use --json when invoking programmatically:

vrin query "What is ACME's revenue?" --json

3. Exit codes map to error types:

Code	Meaning
0	Success
1	General error
2	Authentication failed
3	Rate limited
4	Validation error
5	Job failed
6	Timeout
7	Service unavailable

4. Errors go to stderr, data goes to stdout. Your agent can parse stdout for results and stderr for errors independently.

Next steps

Query commands — modes, depth levels, streaming, conversations
Knowledge commands — insert, upload, bulk-insert, async jobs
Admin commands — health, limits, specialization, graph
Auth commands — login, register, API key management
Python SDK — programmatic access from Python code
MCP Server — connect VRIN to Claude, Cursor, or any MCP-compatible agent
Vrin for AI Agents — the 3-minute agent-onboarding page

Get Started

MCP Server

CLI

Python SDK

TypeScript SDK

Concepts

Guides

CLI Overview

Installation

Authentication

Quick start

Output modes

For AI agents

Next steps

​Installation

​Authentication

​Quick start

​Output modes

​For AI agents

​Next steps

Installation

Authentication

Quick start

Output modes

For AI agents

Next steps