Skip to main content
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 install vrin
Requires Python 3.9+. Installs the vrin command globally.

​
Authentication

Set your API key as an environment variable: 
export VRIN_API_KEY=vrin_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:
ContextOutput formatExample
Interactive terminal (TTY)Human-readablevrin query "..."
Piped / non-TTYJSONvrin query "..." | jq .
--json flagJSON (forced)vrin query "..." --json
VRIN_OUTPUT=json env varJSON (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:
CodeMeaning
0Success
1General error
2Authentication failed
3Rate limited
4Validation error
5Job failed
6Timeout
7Service unavailable
4. Errors go to stderr, data goes to stdout. Your agent can parse stdout for results and stderr for errors independently.

​
Next steps